Verwenden von Dateispaltendaten in 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"]}");
}

Ausgabe:

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

Weitere Informationen:

• Was ist das SDK für .NET
• IOrganizationService.Retrieve-Methode

Anforderung:

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

Antwort:

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

Weitere Informationen: Abrufen einer Tabellenzeile mithilfe der Web-API.

Die statische RetrieveAccountRecordWithFileData-Methode zeigt, wie Informationen zu allen Dateispalten zurückgegeben werden, die Daten enthalten, die sich auf den account-Datensatz mit dem übereinstimmenden accountid-Wert beziehen.

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

Ausgabe:

In diesem Fall gibt es eine einzelne Dateispalte in der Kontentabelle mit dem Namen sample_filecolumn, und dies sind die Daten zu der in dieser Spalte gespeicherten Datei.

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

Weitere Informationen:

• Was ist das SDK für .NET
• Abrufen mit verwandten Zeilen

Die folgende Anforderung gibt Informationen zu allen Dateispalten zurück, die Daten enthalten, die sich auf den mit der account Verwendung accountidangegebenen Datensatz beziehen.

Anforderung:

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

Antwort:

In diesem Fall gibt es eine einzelne Dateispalte in der Kontentabelle mit dem Namen sample_filecolumn, und dies sind die Daten zu der in dieser Spalte gespeicherten Datei.

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

Weitere Informationen: Mit verwandten Zeilen abrufen.

Verwenden Sie zum Hochladen einer Datei oder eines Bilds eine Funktion wie die folgende, die die Klassen InitializeFileBlocksUploadRequest, UploadBlockRequest und CommitFileBlocksUploadRequest verwendet.

/// <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;

}

Weitere Informationen:

• Das SDK für .NET verwenden
• IOrganizationService.Execute Methode

Die folgende Abfolge von Anforderungen und Antworten zeigt die Interaktion bei Verwendung der Web-API, um eine PDF-Datei mit dem Namen 25mb.pdf auf die Dateispalte mit dem Namen sample_filecolumn in der Tabelle account für einen Datensatz mit der angegebenen accountid zu setzen.

Anforderung:

Die erste Anfrage verwendet die InitializeFileBlocksUpload-Aktion.

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

Antwort:

Die Antwort ist ein InitializeFileBlocksUploadResponse ComplexType , der den FileContinuationToken Wert für nachfolgende Anforderungen bereitstellt.

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

Anschließend müssen Sie die Datei in Blöcke von 4 MB oder weniger aufteilen und jeden Block mithilfe der UploadBlock-Aktion mit den folgenden Eigenschaften senden:

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

Anforderung:

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

Antwort:

HTTP/1.1 204 NoContent
OData-Version: 4.0

Nachdem Sie alle Teile der Datei mithilfe mehrerer Anforderungen gesendet haben, die die UploadBlock-Aktion verwenden, verwenden Sie die CommitFileBlocksUpload-Aktion , um den Upload mithilfe dieser Eigenschaften abzuschließen:

Anforderung:

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

Antwort:

Der CommitFileBlocksUploadResponse ComplexType gibt den FileSizeInBytes Wert und den FileId Wert zurück. Sie können den FileId Wert verwenden, um die Datei mithilfe der DeleteFile-Aktion zu löschen.

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
}

Weitere Informationen finden Sie unter Verwenden von Web-API-Aktionen.

Die statische GetFileColumnMaxSizeInKb-Methode gibt den MaxSizeInKB-Wert für eine Dateispalte zurück.

/// <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.");
   }
}

Weitere Informationen:

• RetrieveAttributeRequest-Klasse
• FileAttributeMetadata.MaxSizeInKB

Die folgende Anforderung gibt den MaxSizeInKB-Wert für eine Dateispalte mit dem logischen Namen sample_filecolumn in der account-Tabelle zurück.

Anforderung:

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

Antwort:

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

Weitere Informationen:

• Tabellendefinitionen über die Web-API abfragen > Attribute abrufen
• FileAttributeMetadata EntityType

Sie können eine Funktion wie die folgende verwenden, um eine Datei oder ein Bild herunterzuladen, indem Sie das SDK und die Klassen InitializeFileBlocksDownloadRequest und DownloadBlockRequest verwenden.

/// <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();
}

Weitere Informationen:

• Was ist das SDK für .NET
• IOrganizationService.Execute Methode

Die folgende Reihe von Anfragen und Antworten zeigt die Interaktion bei Verwendung der Web-API, um eine PDF-Datei namens 25mb.pdf aus der Spalte namens sample_filecolumn in der Tabelle account für einen Datensatz mit dem accountid, der <accountid> entspricht, herunterzuladen.

Anforderung:

Die Anforderung verwendet die InitializeFileBlocksUpload-Aktion.

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

Antwort:

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
}

Die Antwort ist ein InitializeFileBlocksDownloadResponse ComplexType der Folgendes bereitstellt:

• FileSizeInBytes: Die Größe der Datei
• FileName: Den Namen der Datei
• FileContinuationToken: Das Dateifortsetzungstoken, das in nachfolgenden Anforderungen verwendet werden kann
• IsChunkingSupported: Flag zur Angabe, ob das Herunterladen in Chunks unterstützt wird oder nicht

Basierend auf der Größe der Datei und der Größe des Blocks, den Sie herunterladen möchten, senden Sie weitere Anforderungen mithilfe der DownloadBlock-Aktion , wie im folgenden Abschnitt gezeigt.

Anforderung:

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

Bei jeder Anforderung wird der Offset-Wert inkrementell um die Anzahl der Bytes erhöht, die in der vorherigen Anforderung angefordert wurden. Die folgenden Werte wurden zum Beispiel verwendet, um eine Datei mit 25870370 Bytes in sieben Anfragen herunterzuladen.

Antwort:

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

Weitere Informationen finden Sie unter Verwenden von Web-API-Aktionen.

Verwenden Sie eine Funktion wie das folgende Beispiel, um eine Datei mithilfe des eindeutigen Bezeichners und der DeleteFileRequest-Klasse zu löschen.

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

Verwenden Sie die folgende Anforderung, um eine Datei mithilfe der ID und der Web-API DeleteFile-Aktion zu löschen.

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

Antwort:

HTTP/1.1 204 NoContent
OData-Version: 4.0

Weitere Informationen finden Sie unter Verwenden von Web-API-Aktionen.