Utiliser les données de colonne de fichier

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>"
}

Plus d’informations : Récupérer 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 ci-dessous renverra des informations sur toutes les colonnes de fichier contenant des données liées à l’enregistrement account spécifié avec accountid.

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>"
    }
  ]
}

Pour plus d’informations : Extraire avec des lignes associées.

Vous pouvez utiliser une fonction comme la suivante pour charger un fichier ou une image en utilisant 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 InitializeFileBlocksUploadResponse ComplexType qui fournit la valeur FileContinuationToken à 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 diviser le fichier en blocs de 4 Mo ou moins et envoyer chaque bloc en utilisant 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

Une fois que toutes les parties du fichier ont été envoyées en plusieurs requêtes en utilisant l’Action UploadBlock, utilisez l’Action CommitFileBlocksUpload pour terminer le chargement en utilisant 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 renvoie FileSizeInBytes et la valeur FileId que vous pouvez utiliser pour supprimer le fichier en utilisant 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 : 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 RetrieveAttributeRequest
• 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ération des attributs
• FileAttributeMetadata EntityType

Vous pouvez utiliser une fonction comme la suivante pour télécharger un fichier ou une image avec le kit SDK en utilisant les 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 allez télécharger, envoyez des requêtes supplémentaires en utilisant l’action DownloadBlock, comme indiqué ci-dessous.

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 : Utiliser les actions de l’API web

Vous pouvez utiliser une fonction comme la suivante pour supprimer un fichier avec l’identificateur unique en utilisant 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 avec l’ID en utilisant 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 : Utiliser les actions de l’API web