Utiliser des données de colonne de fichier dans Microsoft Dataverse

static void RetrieveAccountRecordWithFileColumns(
    IOrganizationService service,
    Guid accountid) 
{

   Entity account = service.Retrieve(
         "account", 
         accountid, 
         new ColumnSet("name", "sample_filecolumn", "sample_filecolumn_name"));

   Console.WriteLine($"name: {account["name"]}");
   Console.WriteLine($"sample_filecolumn: {account["sample_filecolumn"]}");
   Console.WriteLine($"sample_filecolumn_name: {account["sample_filecolumn_name"]}");
}

Sortie :

name: Contoso Ltd.
sample_filecolumn: <file id>
sample_filecolumn_name: 25mb.pdf

Pour plus d’informations :

• En quoi consiste le SDK pour .NET
• Méthode IOrganizationService."Retrieve"

Demande :

GET [Organization Uri]/api/data/v9.2/accounts(<accountid>)?$select=name,sample_filecolumn,sample_filecolumn_name HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

Réponse :

HTTP/1.1 200 OK

{
    "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#accounts(name,sample_filecolumn,sample_filecolumn_name)/$entity",
    "@odata.etag": "W/\"75119522\"",
    "name": "Contoso Ltd.",
    "sample_filecolumn": "<file id>",
    "sample_filecolumn_name": "25mb.pdf",
    "accountid": "<accountid>"
}

Pour plus d’informations, récupérez une ligne de table à l’aide de l’API web.

La méthode statique RetrieveAccountRecordWithFileData montre comment renvoyer des informations sur toutes les colonnes de fichier contenant des données liées à l’enregistrement account avec la valeur accountid correspondante.

static void RetrieveAccountRecordWithFileData(
    IOrganizationService service, 
    Guid accountid)
{
    // Create query for related records
    var relationshipQueryCollection = new RelationshipQueryCollection {
        {
            new Relationship("account_FileAttachments"),
            new QueryExpression("fileattachment"){
                ColumnSet = new ColumnSet(
                                "createdon",
                                "mimetype",
                                "filesizeinbytes",
                                "filename",
                                "regardingfieldname",
                                "fileattachmentid")
            }
        }
    };

    // Include the related query with the Retrieve Request
    RetrieveRequest request = new RetrieveRequest
    {
        ColumnSet = new ColumnSet("accountid"),
        RelatedEntitiesQuery = relationshipQueryCollection,
        Target = new EntityReference("account", accountid)
    };

    // Send the request
    RetrieveResponse response = (RetrieveResponse)service.Execute(request);

    //Display related FileAttachment data for the account record
    response.Entity.RelatedEntities[new Relationship("account_FileAttachments")]
        .Entities.ToList().ForEach(e =>
        {
            Console.WriteLine($"createdon: {e.FormattedValues["createdon"]}");
            Console.WriteLine($"mimetype: {e["mimetype"]}");
            Console.WriteLine($"filesizeinbytes: {e.FormattedValues["filesizeinbytes"]}");
            Console.WriteLine($"filename: {e["filename"]}");
            Console.WriteLine($"regardingfieldname: {e["regardingfieldname"]}");
            Console.WriteLine($"fileattachmentid: {e["fileattachmentid"]}");
        });
}

Sortie :

Dans ce cas, il y a une seule colonne de fichier dans la table des comptes nommée sample_filecolumn, et il s’agit des données sur le fichier stocké dans cette colonne.

createdon: 10/22/2022 2:01 PM
mimetype: application/pdf
filesizeinbytes: 25,870,370
filename: 25mb.pdf
regardingfieldname: sample_filecolumn
fileattachmentid: 63a6afb7-4c52-ed11-bba1-000d3a9933c9

Pour plus d’informations :

• En quoi consiste le SDK pour .NET
• Récupérer avec des lignes associées

La requête suivante retourne des informations sur toutes les colonnes de fichier qui contiennent des données relatives à l'enregistrement spécifié à l'aide de accountaccountid.

Demande :

GET [Organization URI]/api/data/v9.2/accounts(<accountid>)?$filter=sample_filecolumn ne null&$expand=account_FileAttachments($select=createdon,mimetype,filesizeinbytes,filename,regardingfieldname)&$select=accountid HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

Réponse :

Dans ce cas, il y a une seule colonne de fichier dans la table des comptes nommée sample_filecolumn, et il s’agit des données sur le fichier stocké dans cette colonne.

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{
  "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(accountid,account_FileAttachments(createdon,mimetype,filesizeinbytes,filename,regardingfieldname))/$entity",
  "@odata.etag": "W/\"75119522\"",
  "accountid": "<accountid>",
  "account_FileAttachments": [
    {
      "@odata.etag": "W/\"75119363\"",
      "createdon": "2022-10-22T21:01:45Z",
      "mimetype": "application/pdf",
      "filesizeinbytes": 25870370,
      "filename": "25mb.pdf",
      "regardingfieldname": "sample_filecolumn",
      "fileattachmentid": "<file id>"
    }
  ]
}

Plus d’informations : Récupérer avec les lignes associées.

Pour charger un fichier ou une image, utilisez une fonction comme celle suivante qui utilise les classes InitializeFileBlocksUploadRequest, UploadBlockRequest et CommitFileBlocksUploadRequest .

/// <summary>
/// Uploads a file or image column value
/// </summary>
/// <param name="service">The service</param>
/// <param name="entityReference">A reference to the record with the file or image column</param>
/// <param name="fileAttributeName">The name of the file or image column</param>
/// <param name="fileInfo">Information about the file or image to upload.</param>
/// <param name="fileMimeType">The mime type of the file or image, if known.</param>
/// <returns></returns>
static Guid UploadFile(
         IOrganizationService service,
         EntityReference entityReference,
         string fileAttributeName,
         FileInfo fileInfo,
         string fileMimeType = null)
{

   // Initialize the upload
   InitializeFileBlocksUploadRequest initializeFileBlocksUploadRequest = new()
   {
         Target = entityReference,
         FileAttributeName = fileAttributeName,
         FileName = fileInfo.Name
   };

   var initializeFileBlocksUploadResponse =
         (InitializeFileBlocksUploadResponse)service.Execute(initializeFileBlocksUploadRequest);

   string fileContinuationToken = initializeFileBlocksUploadResponse.FileContinuationToken;

   // Capture blockids while uploading
   List<string> blockIds = new();

   using Stream uploadFileStream = fileInfo.OpenRead();

   int blockSize = 4 * 1024 * 1024; // 4 MB

   byte[] buffer = new byte[blockSize];
   int bytesRead = 0;

   long fileSize = fileInfo.Length;
   // The number of iterations that will be required:
   // int blocksCount = (int)Math.Ceiling(fileSize / (float)blockSize);
   int blockNumber = 0;

   // While there is unread data from the file
   while ((bytesRead = uploadFileStream.Read(buffer, 0, buffer.Length)) > 0)
   {
         // The file or final block may be smaller than 4MB
         if (bytesRead < buffer.Length)
         {
            Array.Resize(ref buffer, bytesRead);
         }

         blockNumber++;

         string blockId = Convert.ToBase64String(Encoding.UTF8.GetBytes(Guid.NewGuid().ToString()));

         blockIds.Add(blockId);

         // Prepare the request
         UploadBlockRequest uploadBlockRequest = new()
         {
            BlockData = buffer,
            BlockId = blockId,
            FileContinuationToken = fileContinuationToken,
         };

         // Send the request
         service.Execute(uploadBlockRequest);
   }

   // Try to get the mimetype if not provided.
   if (string.IsNullOrEmpty(fileMimeType))
   {
         var provider = new FileExtensionContentTypeProvider();

         if (!provider.TryGetContentType(fileInfo.Name, out fileMimeType))
         {
            fileMimeType = "application/octet-stream";
         }
   }

   // Commit the upload
   CommitFileBlocksUploadRequest commitFileBlocksUploadRequest = new()
   {
         BlockList = blockIds.ToArray(),
         FileContinuationToken = fileContinuationToken,
         FileName = fileInfo.Name,
         MimeType = fileMimeType
   };

   var commitFileBlocksUploadResponse =
         (CommitFileBlocksUploadResponse)service.Execute(commitFileBlocksUploadRequest);

   return commitFileBlocksUploadResponse.FileId;

}

Pour plus d’informations :

• Utiliser le SDK pour .NET
• Méthode IOrganizationService.Execute

La série suivante de requêtes et de réponses montre l’interaction lors de l’utilisation de l’API Web pour définir un fichier PDF nommé 25mb.pdf sur la colonne de fichier nommée sample_filecolumn de la table account pour un enregistrement avec la valeur accountid spécifiée.

Demande :

La première requête utilise l’Action InitializeFileBlocksUpload.

POST [Organization Uri]/api/data/v9.2/InitializeFileBlocksUpload HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json
Content-Type: application/json; charset=utf-8
Content-Length: 207

{
  "Target": {
    "accountid": "<accountid>",
    "@odata.type": "Microsoft.Dynamics.CRM.account"
  },
  "FileName": "25mb.pdf",
  "FileAttributeName": "sample_filecolumn"
}

Réponse :

La réponse est un ComplexType InitializeFileBlocksUploadResponse qui fournit la FileContinuationToken valeur à utiliser avec les requêtes suivantes.

HTTP/1.1 200 OK
OData-Version: 4.0

{
  "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.InitializeFileBlocksUploadResponse",
  "FileContinuationToken": "<Removed for brevity>"
}

Vous devez ensuite décomposer le fichier en blocs de 4 Mo ou moins et envoyer chaque bloc à l’aide de l’action UploadBlock avec les propriétés suivantes :

string blockId = Convert.ToBase64String(Encoding.UTF8.GetBytes(Guid.NewGuid().ToString()));

Demande :

POST [Organization Uri]/api/data/v9.2/UploadBlock HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json
Content-Type: application/json; charset=utf-8
Content-Length: 5593368

{
  "BlockId": "OThjODg5NjgtNzM2Zi00YmI1LTgyNzktNmU2NzgwMTRiMzFk",
  "BlockData": "<Base64 encoded string of byte[] data removed for brevity>",
  "FileContinuationToken": "<file continuation token value removed for brevity>"
}

Réponse :

HTTP/1.1 204 NoContent
OData-Version: 4.0

Après avoir envoyé toutes les parties du fichier à l’aide de plusieurs requêtes qui utilisent l’action UploadBlock, utilisez l’action CommitFileBlocksUpload pour terminer le chargement à l’aide de ces propriétés :

Demande :

POST [Organization Uri]/api/data/v9.2/CommitFileBlocksUpload HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json
Content-Type: application/json; charset=utf-8
Content-Length: 1213

{
  "FileName": "25mb.pdf",
  "MimeType": "application/pdf",
  "BlockList": [
    "OThjODg5NjgtNzM2Zi00YmI1LTgyNzktNmU2NzgwMTRiMzFk",
    "ZWUxNzcxZjgtNjEwOC00NDk1LWI2NzMtODFkNDM3YjMyNTFm",
    "YWMwYzhjMzEtY2U0My00NjUwLThlZmEtNjg3NDM5ZTA1MGJi",
    "ZGM3NWQ2NjUtNTViMy00ODQ2LWE5NmQtNDE3ZGUyYTIxYjhi",
    "NzE2OWYyZGEtZGQ1Ni00YWMwLWJiNWUtNjIyNDlkYzRiNmEy",
    "ZmU2ZDMzNjQtMzg2My00ZGZlLWIwYjItMDc4NTY2MDE1MzY1",
    "NWY1ZDAyMWUtNTJiNi00YjA5LTg4ZWItYzg3OTdhMDYxMTRl"
  ],
  "FileContinuationToken": "<file continuation token value removed for brevity>"
}

Réponse :

CommitFileBlocksUploadResponse ComplexType retourne les valeurs FileSizeInBytes et FileId. Vous pouvez utiliser la FileId valeur pour supprimer le fichier à l’aide de l’action DeleteFile.

HTTP/1.1 200 OK
OData-Version: 4.0

{
  "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.CommitFileBlocksUploadResponse",
  "FileId": "3878e950-8e51-ed11-bba1-000d3a9933c9",
  "FileSizeInBytes": 25870370
}

Pour plus d'informations, consultez Utiliser les actions de l'API Web.

La méthode GetFileColumnMaxSizeInKb statique renvoie la valeur MaxSizeInKB d’une colonne de fichier.

/// <summary>
/// Retrieves the MaxSizeInKb property of a file column.
/// </summary>
/// <param name="service">IOrganizationService</param>
/// <param name="entityLogicalName">The logical name of the table that has the column</param>
/// <param name="fileColumnLogicalName">The logical name of the file column.</param>
/// <returns></returns>
/// <exception cref="Exception"></exception>
public static int GetFileColumnMaxSizeInKb(
    IOrganizationService service, 
    string entityLogicalName, 
    string fileColumnLogicalName) 
{

   RetrieveAttributeRequest retrieveAttributeRequest = new() { 
         EntityLogicalName = entityLogicalName,
         LogicalName = fileColumnLogicalName
   };

   RetrieveAttributeResponse retrieveAttributeResponse;
   try
   {
         retrieveAttributeResponse = (RetrieveAttributeResponse)service.Execute(retrieveAttributeRequest);
   }
   catch (Exception)
   {
         throw;
   }

   if (retrieveAttributeResponse.AttributeMetadata is FileAttributeMetadata fileColumn)
   {
         return fileColumn.MaxSizeInKB.Value;
   }
   else
   {
         throw new Exception($"{entityLogicalName}.{fileColumnLogicalName} is not a file column.");
   }
}

Pour plus d’informations :

• Classe de demande de récupération d'attribut
• FileAttributeMetadata.MaxSizeInKB

La requête suivante renvoie la valeur MaxSizeInKB pour une colonne de fichier avec le nom logique sample_filecolumn dans la table account.

Demande :

GET [Organization Uri]/api/data/v9.2/EntityDefinitions(LogicalName='account')/Attributes(LogicalName='sample_filecolumn')/Microsoft.Dynamics.CRM.FileAttributeMetadata?$select=MaxSizeInKB HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

Réponse :

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{
  "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#EntityDefinitions('account')/Attributes/Microsoft.Dynamics.CRM.FileAttributeMetadata(MaxSizeInKB)/$entity",
  "MaxSizeInKB": 102400,
  "MetadataId": "f315e7f1-6355-ed11-bba3-000d3a9933c9"
}

Pour plus d’informations :

• Interroger les définitions de table à l'aide de l'API Web > Récupérer les attributs
• FileAttributeMetadata EntityType

Vous pouvez utiliser une fonction comme celle-ci pour télécharger un fichier ou une image à l’aide du Kit de développement logiciel (SDK) et des classes InitializeFileBlocksDownloadRequest et DownloadBlockRequest .

/// <summary>
/// Downloads a file or image
/// </summary>
/// <param name="service">The service</param>
/// <param name="entityReference">A reference to the record with the file or image column</param>
/// <param name="attributeName">The name of the file or image column</param>
/// <returns></returns>
private static byte[] DownloadFile(
            IOrganizationService service,
            EntityReference entityReference,
            string attributeName)
{
   InitializeFileBlocksDownloadRequest initializeFileBlocksDownloadRequest = new()
   {
         Target = entityReference,
         FileAttributeName = attributeName
   };

   var initializeFileBlocksDownloadResponse =
         (InitializeFileBlocksDownloadResponse)service.Execute(initializeFileBlocksDownloadRequest);

   string fileContinuationToken = initializeFileBlocksDownloadResponse.FileContinuationToken;
   long fileSizeInBytes = initializeFileBlocksDownloadResponse.FileSizeInBytes;

   List<byte> fileBytes = new((int)fileSizeInBytes);

   long offset = 0;
   // If chunking is not supported, chunk size will be full size of the file.
   long blockSizeDownload = !initializeFileBlocksDownloadResponse.IsChunkingSupported ? fileSizeInBytes :  4 * 1024 * 1024;

   // File size may be smaller than defined block size
   if (fileSizeInBytes < blockSizeDownload)
   {
         blockSizeDownload = fileSizeInBytes;
   }

   while (fileSizeInBytes > 0)
   {
         // Prepare the request
         DownloadBlockRequest downLoadBlockRequest = new()
         {
            BlockLength = blockSizeDownload,
            FileContinuationToken = fileContinuationToken,
            Offset = offset
         };

         // Send the request
         var downloadBlockResponse =
                  (DownloadBlockResponse)service.Execute(downLoadBlockRequest);

         // Add the block returned to the list
         fileBytes.AddRange(downloadBlockResponse.Data);

         // Subtract the amount downloaded,
         // which may make fileSizeInBytes < 0 and indicate
         // no further blocks to download
         fileSizeInBytes -= (int)blockSizeDownload;
         // Increment the offset to start at the beginning of the next block.
         offset += blockSizeDownload;
   }

   return fileBytes.ToArray();
}

Pour plus d’informations :

• En quoi consiste le SDK pour .NET
• Méthode IOrganizationService.Execute

La série suivante de requêtes et de réponses montre l’interaction lors de l’utilisation de l’API Web pour télécharger un fichier PDF nommé 25mb.pdf à partir de la colonne de fichier nommée sample_filecolumn de la table account pour un enregistrement avec accountid égal à <accountid>.

Demande :

Cette requête utilise l’Action InitializeFileBlocksDownload.

POST [Organization Uri]/api/data/v9.2/InitializeFileBlocksDownload HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json
Content-Type: application/json; charset=utf-8
Content-Length: 180

{
  "Target": {
    "accountid": "<accountid>",
    "@odata.type": "Microsoft.Dynamics.CRM.account"
  },
  "FileAttributeName": "sample_filecolumn"
}

Réponse :

HTTP/1.1 200 OK
OData-Version: 4.0

{
  "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.InitializeFileBlocksDownloadResponse",
  "FileSizeInBytes": 25870370,
  "FileName": "25mb.pdf",
  "FileContinuationToken": "<file continuation token value removed for brevity>",
  "IsChunkingSupported": true
}

La réponse est un InitializeFileBlocksDownloadResponse ComplexType qui fournit :

• FileSizeInBytes : taille du fichier
• FileName : nom du fichier
• FileContinuationToken : jeton de continuation de fichier à utiliser dans les requêtes ultérieures
• IsChunkingSupported : indicateur révélant si le téléchargement segmenté est pris en charge ou non

En fonction de la taille du fichier et de la taille du bloc que vous souhaitez télécharger, envoyez plus de demandes à l’aide de l’action DownloadBlock , comme indiqué dans la section suivante.

Demande :

POST [Organization Uri]/api/data/v9.2/DownloadBlock HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json
Content-Type: application/json; charset=utf-8
Content-Length: 921

{
  "Offset": 0,
  "BlockLength": 4194304,
  "FileContinuationToken": "<file continuation token value removed for brevity>"
}

Avec chaque requête, incrémentez la valeur Offset du nombre d’octets demandés dans la requête précédente. Par exemple, les valeurs suivantes ont été utilisées pour télécharger un fichier de 25870370 octets en sept requêtes :

Réponse :

HTTP/1.1 200 OK
OData-Version: 4.0

{
  "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.DownloadBlockResponse",
  "Data": "<byte[] data removed for brevity>"
}

Pour plus d'informations, consultez Utiliser les actions de l'API Web.

Utilisez une fonction comme l’exemple suivant pour supprimer un fichier à l’aide de l’identificateur unique et de la classe DeleteFileRequest.

static Guid DeleteFile(IOrganizationService service, Guid fileId)
{
   DeleteFileRequest deleteFileRequest = new()
   {
      FileId = fileId
   };
   service.Execute(deleteFileRequest);
}

Utilisez la requête suivante pour supprimer un fichier en utilisant l'ID et l'action DeleteFile de l'API web.

POST [Organization Uri]/api/data/v9.2/DeleteFile HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json
Content-Type: application/json; charset=utf-8
Content-Length: 56

{
  "FileId": "3878e950-8e51-ed11-bba1-000d3a9933c9"
}

Réponse :

HTTP/1.1 204 NoContent
OData-Version: 4.0

Pour plus d'informations, consultez Utiliser les actions de l'API Web.