Teilen über

Dateispaltendaten verwenden

  • Artikel

Dateispalten unterscheiden sich von den anderen Systemspalten, die Binärdaten speichern können, da Sie die Werte weder direkt in einem Erstellungs- oder Aktualisierungsvorgang festlegen noch die Dateidaten mit dem Datensatz abrufen können. Sie müssen die in diesem Artikel beschriebenen Methoden verwenden, um Binärdaten für Dateispalten zu erstellen, abzurufen, zu aktualisieren oder zu löschen.

Es gibt verschiedene Möglichkeiten, mit Dateispaltendaten über die Web-API zu arbeiten. Alle Methoden werden gleichermaßen unterstützt. Wählen Sie die Methode aus, die für Sie am besten geeignet ist. Da Binärdateien groß sein können, ist es häufig erforderlich, die Datei in mehrere Abschnitte (oder Blöcke) aufzuteilen, die nacheinander oder parallel gesendet oder empfangen werden können, um die Leistung zu verbessern.

Dateinamenspalte

Jede Dateispalte verfügt über eine unterstützende schreibgeschützte Zeichenfolgenspalte, die den Namen der Datei enthält. Der Schemaname für diese Spalte hat denselben Namen wie die Dateispalte, es ist jedoch _Name daran angehängt. Wenn der Schemaname also sample_FileColumn lautet, lautet die unterstützende Zeichenfolgenspalte sample_FileColumn_Name. Der logische Name für die unterstützende Spalte lautet sample_filecolumn_name.

Hinweis

Die Dateinamenspalte wird im Power Apps-Designer nicht angezeigt.

Beziehung zur FileAttachment-Tabelle

Wenn eine Dateispalte für eine Tabelle erstellt wird, wird eine neue 1:n-Beziehung zwischen der Tabelle und der FileAttachment-Tabelle erstellt. Der Name der Beziehung lautet {table logical name}_FileAttachments. Wenn die Dateispalte beispielsweise Teil der Kontotabelle ist, lautet der Beziehungsname account_FileAttachments.

Sie können diese Beziehung verwenden, um weitere Daten über die Dateispalte und alle anderen Dateispalten für die Tabelle zurückzugeben. Weitere Informationen: Zusätzliche Informationen zu Dateien für einen Datensatz abrufen.

Verhalten beim Abrufen

Wenn Sie einen Datensatz abrufen und eine Dateispalte einbeziehen, ist der zurückgegebene Wert ein eindeutiger Bezeichner für die Datei. Sie können diesen Wert verwenden, um die Datei mit der Meldung DeleteFile zu löschen. Diese ID dient ausschließlich dazu, zu überprüfen, ob die Spalte einen Wert aufweist. Weitere Informationen: DeleteFile-Meldung verwenden.

Die folgenden Beispiele zeigen, was Sie erwarten können, wenn Sie Daten aus Dateispalten wie bei anderen Spalten abrufen.

Bei diesen Beispiele werden die Spalten name, sample_filecolumn und sample_filecolumn_name für einen Kontodatensatz abgerufen:

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:

Zusätzliche Informationen zu Dateien für einen Datensatz abrufen

Sie können die Beziehung zwischen der Dateispaltentabelle und der FileAttachment-Tabelle verwenden, um Informationen über alle Dateispalten zurückzugeben, die dieser Tabellenzeile zugeordnet sind.

Die statische RetrieveAccountRecordWithFileData-Methode unten zeigt, wie Informationen zu allen Dateispalten zurückgegeben werden, die Daten enthalten, die sich auf den account-Datensatz des übereinstimmenden accountid-Werts 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:

Dateien hochladen

Es gibt drei verschiedene Möglichkeiten, Dateien in eine Dateispalte hochzuladen:

  • Dataverse-Meldungen verwenden, die sowohl für das SDK als auch für die Web-API verfügbar sind
  • Eine Datei in eine einzelne Anforderungen über die Web-API hochladen
  • Die Datei in Blöcken über die Web-API hochladen

Hinweis

  • Sie sollten überprüfen, ob die maximale Dateigröße für Spalten groß genug ist, damit die Datei akzeptiert wird, die Sie hochladen. Weitere Informationen: Maximale Dateigröße überprüfen
  • Sie können diese APIs auch verwenden, um Bildspaltendaten hochzuladen. Weitere Informationen: Bildspaltendaten verwenden

Dataverse-Nachrichten zum Hochladen einer Datei verwenden

Sie können Dataverse-Nachrichten über das SDK für .NET oder die Web-API verwenden. Wenn eine Datei auf diese Weise hochgeladen wird, muss ein Satz von drei Nachrichten verwendet werden:

Nachricht Beschreibung des Dataflows
InitializeFileBlocksUpload Verwenden Sie diese Nachricht, um die Spalte anzugeben, in die Sie eine Datei hochladen möchten. Es wird ein Dateifortsetzungstoken zurückgegeben, mit dem Sie die Datei blockweise über die UploadBlock-Nachricht und mit CommitFileBlocksUpload hochladen können.
UploadBlock Teilen Sie Ihre Datei in Blöcke auf, und generieren Sie für jeden Block eine blockid. Senden Sie dann mehrere Anforderungen, bis alle Blöcke zusammen mit dem Dateifortsetzungstoken gesendet wurden.
CommitFileBlocksUpload Nachdem Sie Anforderungen für alle Blöcke mit UploadBlock gesendet haben, verwenden Sie diese Nachricht, um den Upload-Vorgang zu bestätigen, indem Sie Folgendes senden:
- Die Liste der generierten Blockids
- Der Name der Datei
- Der MIME-Typ der Datei
- Partitionsfortsetzungstoken

Sie können eine Funktion wie die folgende verwenden, um eine Datei oder ein Bild mit den Klassen InitializeFileBlocksUploadRequest, UploadBlockRequest und CommitFileBlocksUploadRequest hochzuladen.

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

Hinweis

Diese Beispielmethode enthält eine Logik, mit der versucht wird, den MIME Typ der Datei mit Hilfe der Methode FileExtensionContentTypeProvider.TryGetContentType(String, String) zu ermitteln, wenn er nicht bereitgestellt wird. Wenn der Typ nicht gefunden wird, wird er auf application/octet-stream gesetzt.

Eine Datei in eine einzelne Anforderungen über die Web-API hochladen

Wenn die Dateigrößer weniger als 128 MB beträgt, können Sie sie in einer einzelnen Anforderung die Web-API hochladen.

Im folgenden Beispiel wird eine Textdatei mit dem Namen 4094kb.txt in die Dateispalte mit dem Namen sample_filecolumn in der account-Tabelle für einen Datensatz mit der accountid hochgeladen, die <accountid> entspricht.

Anforderung:

PATCH [Organization Uri]/api/data/v9.2/accounts(<accountid>)/sample_filecolumn HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json
Content-Type: application/octet-stream
x-ms-file-name: 4094kb.txt
Content-Length: 4191273

< binary content removed for brevity>

Antwort:

HTTP/1.1 204 NoContent
OData-Version: 4.0

PowerShell-Beispiel zum Hochladen einer Datei in einer einzigen Anforderung

Die folgende PowerShell-Set-FileColumn-Funktion zeigt, wie eine Datei mithilfe der Web-API in einer einzigen Anforderung hochgeladen wird.

Erfahren Sie mehr über die Verwendung von PowerShell und Visual Studio Code mit der Dataverse-Web-API:

Diese Funktion erfordert eine Verbindung, die die globale $baseURI und $baseHeaders festlegt, die mit der Connect-Funktion beschrieben in Funktion „Verbinden“ erstellen festgelegt werden.

<#
.SYNOPSIS
Sets a column value for a file in a specified table.

.DESCRIPTION
The Set-FileColumn function sets a column value for a file in a specified table. 
It uses a single request and can work with files less than 128 MB.

.PARAMETER setName
The entity set name of the table where the file is stored.

.PARAMETER id
The unique identifier of record.

.PARAMETER columnName
The logical name of the file column to set the value for.

.PARAMETER file
The path to the file to upload.

.EXAMPLE
Set-FileColumn `
   -setName 'accounts' `
   -id [System.Guid]::New('12345678-1234-1234-1234-1234567890AB') `
   -columnName 'new_filecolumn' `
   -file 'C:\Path\To\File.txt'
   
Sets the value of the 'new_filecolumn' column for the file with the specified ID 
in the account table to the contents of the File.txt file.

#>
function Set-FileColumn {
   param (
      [Parameter(Mandatory)]
      [string]
      $setName,
      [Parameter(Mandatory)]
      [System.Guid]
      $id,
      [Parameter(Mandatory)]
      [string]
      $columnName,
      [Parameter(Mandatory, ValueFromPipeline, ValueFromPipelineByPropertyName)]
      [System.IO.FileInfo]$file
   )

   $uri = '{0}{1}({2})/{3}' -f $baseURI, $setName, $id, $columnName

   $patchHeaders = $baseHeaders.Clone()
   $patchHeaders.Add('Content-Type', 'application/octet-stream')
   $patchHeaders.Add('x-ms-file-name', $file.Name)

   $body = [System.IO.File]::ReadAllBytes($file.FullName)

   $FileUploadRequest = @{
      Uri     = $uri
      Method  = 'Patch'
      Headers = $patchHeaders
      Body    = $body
   }

   Invoke-RestMethod @FileUploadRequest
}

Die Datei in Blöcken über die Web-API hochladen

Verwenden Sie den folgenden Satz von Anforderungen, um Ihre Datei in Blöcken über die Web-API hochzuladen.

Im folgenden Beispiel wird eine PDF-Datei mit dem Namen 25mb.pdf in die Dateispalte mit dem Namen sample_filecolumn in der account-Tabelle für einen Datensatz mit der accountid hochgeladen, die <accountid> entspricht.

Anforderung:

Die erste Anforderung muss den folgenden Header enthalten: x-ms-transfer-mode: chunked.

Legen Sie den Dateinamen mit dem x-ms-file-name-Abfrageparameter fest.

PATCH [Organization Uri]/api/data/v9.2/accounts(<accountid>)/sample_filecolumn?x-ms-file-name=25mb.pdf HTTP/1.1
x-ms-transfer-mode: chunked
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

Hinweis

Der Dateiname kann auch als x-ms-file-name-Anforderungsheader eingeschlossen werden, aber dies unterstützt keine Dateinamen außerhalb des ASCII-Zeichensatzes. Wenn der Header verwendet wird, hat er Vorrang vor dem x-ms-file-name-Abfrageparameter.

Antwort:

HTTP/1.1 200 OK
Accept-Ranges: bytes
Location: [Organization Uri]/api/data/v9.2/accounts(<accountid>)/sample_filecolumn?sessiontoken=<sessiontoken value removed for brevity>
OData-Version: 4.0
x-ms-chunk-size: 4194304
Access-Control-Expose-Headers: x-ms-chunk-size

Der Location-Header der Antwort enthält eine URL, die in nachfolgenden Anforderungen verwendet werden soll. Er enthält einen sessiontoken-Abfrageparameter, der angibt, dass alle damit gesendeten Anforderungen Teil desselben Vorgangs sind.

Die Antwort enthält die folgenden Header.

Header Beschreibung des Dataflows
x-ms-chunk-size Stellt eine empfohlene Blockgröße in Bytes bereit.
Accept-Ranges Gibt an, dass der Server Teilanforderungen des Clients für Dateidownloads unterstützt. Der Wert bytes gibt an, dass der Bereichswert in nachfolgenden Anforderungen in Bytes angegeben werden sollte.
Access-Control-Expose-Headers Zeigt an, dass der x-ms-chunk-size-Header-Wert als Antwort auf eine Cross-Origin-Anforderung Skripten zur Verfügung gestellt werden sollte, die im Browser ausgeführt werden.

Anforderung:

Nachfolgende Anforderungen sollten den Wert des Location-Headers verwenden, der von der ersten Anforderung zurückgegeben wird, sodass der sessiontoken-Wert enthalten ist.

Jede Anforderung muss diesen Teil der Datei im Textkörper sowie die folgenden Header enthalten:

Header Beschreibung des Dataflows
x-ms-file-name Der Name der Datei.
Inhaltsart Auf application/octet-stream festlegen
Content-Range Bei Verwendung dieses Formats:
<unit> <range-start>-<range-end>/<size>
Der Wert der ersten Anforderung: bytes 0-4194303/25870370 gibt an, dass die Messung Bytes verwendet. Diese Anfrage umfasst die ersten 4194303 Bytes einer Datei, deren Größe 25870370 Bytes (fast 25 MB) beträgt.
Bei jeder nachfolgenden Anforderung wird dieser Wert erhöht, bis die gesamte Datei gesendet wurde:
bytes 4194304-8388607/25870370
bytes 8388608-12582911/25870370
bytes 12582912-16777215/25870370
bytes 16777216-20971519/25870370
bytes 20971520-25165823/25870370
bytes 25165824-25870369/25870370
Inhaltslänge Gibt die Größe der Nachricht an. Im Beispiel oben lautet dieser Wert für die letzte Anforderung 704546 statt 4194304. 
PATCH [Organization Uri]/api/data/v9.2/accounts(<accountid>)/sample_filecolumn?sessiontoken=<sessiontoken value removed for brevity> HTTP/1.1
x-ms-file-name: 25mb.pdf
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json
Content-Type: application/octet-stream
Content-Range: bytes 0-4194303/25870370
Content-Length: 4194304

< byte[] content removed for brevity>

Für jede Anforderung, die einen Teilinhalt enthält, lautet die Antwort 206 PartialContent.

Antwort:

HTTP/1.1 206 PartialContent
OData-Version: 4.0

Für die letzte Anforderung, die den letzten Teil der Datei enthält, lautet die Antwort 204 NoContent.

Antwort:

HTTP/1.1 204 NoContent
OData-Version: 4.0

PowerShell-Beispiel zum Hochladen einer Datei in Blöcken

Die folgende PowerShell-Set-FileColumnInChunks-Funktion zeigt, wie eine Datei mithilfe der Web-API in Blöcken hochgeladen wird. Diese Funktion erfordert eine Verbindung, die die globale $baseURI und $baseHeaders festlegt, die mit der Connect-Funktion beschrieben in Funktion „Verbinden“ erstellen festgelegt werden.

<#
.SYNOPSIS
Sets a column value for a file in a specified table.

.DESCRIPTION
The Set-FileColumnInChunks function sets a column value for a file in a specified table. 
It uses chunked file upload to efficiently upload large files.

.PARAMETER setName
The name of the table where the file is stored.

.PARAMETER id
The unique identifier of record.

.PARAMETER columnName
The logical name of the file column to set the value for.

.PARAMETER file
The path to the file to upload.

.EXAMPLE
Set-FileColumnInChunks `
   -setName 'accounts' `
   -id [System.Guid]::New('12345678-1234-1234-1234-1234567890AB') `
   -columnName 'new_filecolumn' `
   -file 'C:\Path\To\File.txt'
   
Sets the value of the 'new_filecolumn' column for the file with the specified ID in the account table to the contents of the File.txt file.

#>
function Set-FileColumnInChunks {
   param (
      [Parameter(Mandatory)]
      [string]
      $setName,
      [Parameter(Mandatory)]
      [System.Guid]
      $id,
      [Parameter(Mandatory)]
      [string]
      $columnName,
      [Parameter(Mandatory, ValueFromPipeline, ValueFromPipelineByPropertyName)]
      [System.IO.FileInfo]$file
   )

   $uri = '{0}{1}({2})' -f $baseURI, $setName, $id
   $uri += '/{0}?x-ms-file-name={1}' -f $columnName, $file.Name

   $chunkHeaders = $baseHeaders.Clone()
   $chunkHeaders.Add('x-ms-transfer-mode', 'chunked')

   $InitializeChunkedFileUploadRequest = @{
      Uri     = $uri
      Method  = 'Patch'
      Headers = $chunkHeaders
   }

   Invoke-RestMethod @InitializeChunkedFileUploadRequest `
      -ResponseHeadersVariable rhv

   $locationUri = $rhv['Location'][0]
   $chunkSize = [int]$rhv['x-ms-chunk-size'][0]

   $bytes = [System.IO.File]::ReadAllBytes($file.FullName)

   for ($offset = 0; $offset -lt $bytes.Length; $offset += $chunkSize) {
         
      $count = if (($offSet + $chunkSize) -gt $bytes.Length) 
                  { $bytes.Length % $chunkSize } 
               else { $chunkSize }
      
      $lastByte = $offset + ($count - 1)

      $range = 'bytes {0}-{1}/{2}' -f $offset, $lastByte, $bytes.Length

      $contentHeaders = $baseHeaders.Clone()
      $contentHeaders.Add('Content-Range', $range)
      $contentHeaders.Add('Content-Type', 'application/octet-stream')
      $contentHeaders.Add('x-ms-file-name', $file.Name)

      $UploadFileChunkRequest = @{
         Uri     = $locationUri
         Method  = 'Patch'
         Headers = $contentHeaders
         Body    = [byte[]]$bytes[$offSet..$lastByte]
      }

      Invoke-RestMethod @UploadFileChunkRequest
   }
}

Maximale Dateigröße überprüfen

Bevor Sie eine Datei hochladen, können Sie überprüfen, ob die Größe der Datei die konfigurierte maximale Dateigröße, die in der MaxSizeInKB-Eigenschaft gespeichert ist, überschreitet.

Wenn Sie versuchen, eine zu große Datei hochzuladen, erhalten Sie die folgende Fehlermeldung:

Name: unManagedidsattachmentinvalidfilesize
Code: 0x80044a02
Nummer: -2147202558
Meldung: Attachment file size is too big.

Sie können die folgenden Beispiele verwenden, um die maximale Dateigröße zu überprüfen:

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:

Dateien herunterladen

Es gibt drei verschiedene Methoden, Dateien von einer Dateispalte hochzuladen:

  • Dataverse-Meldungen verwenden, die sowohl für das SDK als auch für die Web-API verfügbar sind
  • Eine Datei in eine einzelne Anforderungen über die Web-API herunterladen
  • Die Datei in Blöcken über die Web-API herunterladen

Hinweis

Diese Methoden können auch zum Herunterladen von Bildspalten verwendet werden, es gibt jedoch einige Unterschiede. Weitere Informationen: Bilder herunterladen

Für lokale Umgebungen, oder wenn eine Umgebung den selbstverwalteten Schlüssel (BYOK) verwendet, befindet sich die Datei nicht im Dateispeicher. Wenn sich eine Datei nicht im Speicher befindet, wird das Herunterladen in mehreren Chunks nicht unterstützt. Der InitializeFileBlocksDownloadResponse ComplexType und InitializeFileBlocksDownloadResponse Class haben eine IsChunkingSupported-Eigenschaft, die angibt, ob die Datei in mehreren Chunks heruntergeladen werden kann oder nicht. Wenn Chunking nicht unterstützt wird, dann legen Sie BlockLength als Dateigröße fest.

Der Versuch, einen Teil eines Chunks herunterzuladen, wenn IsChunkingSupported auf false festgelegt ist, führt zu diesem Fehler:

Name: UploadingAndDownloadingInMultipleChunksNotSupported
Code: 0x80090017
Meldung: Downloading in multiple chunks is not supported for the files stored in the database.

Dataverse-Nachrichten zum Herunterladen einer Datei verwenden

Sie können Dataverse-Nachrichten über das SDK für .NET oder die Web-API verwenden. Wenn eine Datei auf diese Weise heruntergeladen wird, muss ein Nachrichtenpaar verwendet werden:

Nachricht Beschreibung des Dataflows
InitializeFileBlocksDownload Verwenden Sie diese Nachricht, um die Spalte anzugeben, aus der Sie eine Datei herunterladen möchten. Sie gibt die Dateigröße in Bytes und ein file continuation token zurück, mit dem Sie die Datei blockweise über die DownloadBlock-Nachricht herunterladen können.
DownloadBlock Fordern Sie die Größe des Blocks, den Offsetwert und das Dateifortsetzungstoken an.

Nachdem Sie alle Blöcke heruntergeladen haben, müssen Sie sie verbinden, um die komplette heruntergeladene Datei zu erstellen.

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

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

Eine Datei in eine einzelne Anforderungen über die Web-API herunterladen

Im folgenden Beispiel wird eine Textdatei mit dem Namen 4094kb.txt aus der Dateispalte mit dem Namen sample_filecolumn in der account-Tabelle für einen Datensatz mit der accountid heruntergeladen, die <accountid> entspricht.

Anforderung:

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

Antwort:

Die Antwort enthält die folgenden Header.

Header Beschreibung
x-ms-file-size Die Größe der Datei in Bytes.
x-ms-file-name Der Name der Datei.
mimetype Der MIME-Typ der Datei
Access-Control-Expose-Headers Zeigt an, dass die Werte der Header x-ms-file-size, x-ms-file-name und mimetype als Antwort auf eine Cross-Origin-Anforderung Skripten zur Verfügung gestellt werden sollten, die im Browser ausgeführt werden. 
HTTP/1.1 200 OK
x-ms-file-size: 4191273
x-ms-file-name: 4094kb.txt
mimetype: text/plain
Access-Control-Expose-Headers: x-ms-file-size; x-ms-file-name; mimetype

< byte[] content removed for brevity. >

Die Datei in Blöcken über die Web-API herunterladen

Hinweis

Das folgende Beispiel bezieht sich auf Fälle, in denen IsChunkingSupported auf wahr festgelegt ist. Wenn sie falsch ist, verwenden Sie bitte Download einer Datei in einem einzigen Request über Web-API.

Verwenden Sie den folgenden Satz von Anforderungen, um Ihre Datei in Blöcken über die Web-API herunterzuladen.

Im folgenden Beispiel wird eine PDF-Datei mit dem Namen 25mb.pdf in die Dateispalte mit dem Namen sample_filecolumn in der account-Tabelle für einen Datensatz mit der accountid heruntegeladen, die <accountid> entspricht.

Anforderung:

Verwenden Sie den Header Bereich, um die Anzahl der zurückzugebenden Bytes in diesem Format anzugeben:
<unit>=<range-start>-<range-end>
Hierbei beträgt unit Bytes und range-start für die erste Anforderungrage 0.

Sie wissen erst, wie viele Iterationen erforderlich sind, um die gesamte Datei herunterzuladen, wenn Sie die erste Antwort erhalten, deren x-ms-file-size-Antwortheader die Größe der Datei angibt.

Während <range-start> kleiner als die Gesamtgröße der Datei ist, werden für jede nachfolgende Anforderung die Werte <range-start> und <range-end> erhöht, um den nächsten Block der Datei anzufordern.

GET [Organization Uri]/api/data/v9.2/accounts(<accountid>)/sample_filecolumn/$value HTTP/1.1
Range: bytes=0-4194303
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

Antwort:

Die Antwort enthält die folgenden Header:

Header Beschreibung
x-ms-file-size Die Größe der Datei in Bytes.
x-ms-file-name Der Name der Datei.
x-ms-chunk-size Stellt eine empfohlene Blockgröße in Bytes bereit.
mimetype Der MIME-Typ der Datei
Access-Control-Expose-Headers Zeigt an, dass die Werte der Header x-ms-file-size, x-ms-file-name, x-ms-chunk-size und mimetype als Antwort auf eine Cross-Origin-Anforderung Skripten zur Verfügung gestellt werden sollten, die im Browser ausgeführt werden. 
HTTP/1.1 206 PartialContent
x-ms-file-size: 25870370
x-ms-file-name: 25mb.pdf
x-ms-chunk-size: 4194304
mimetype: application/pdf
Access-Control-Expose-Headers: x-ms-file-size; x-ms-file-name; x-ms-chunk-size; mimetype
OData-Version: 4.0

< byte[] content removed for brevity. >

Dateien löschen

Es gibt zwei verschiedene Möglichkeiten, Dateien in eine Dateispalte zu löschen:

  • Die Dataverse DeleteFile-Nachricht verwenden, die sowohl für das SDK als auch für die Web-API verfügbar ist
  • Senden Sie eine DELETE-Anforderung über die Web-API an die Dateispalte des Datensatzes.

Die DeleteFile-Nachricht verwenden

Mithilfe des eindeutigen Bezeichners, der von CommitFileBlocksUploadResponse.FileId zurückgegeben oder aus der Spalte abgerufen werden, wie in Verhalten beim Abrufen beschrieben, können Sie die Datei mit der DeleteFile-Nachricht löschen.

Sie können eine Funktion wie die folgende verwenden, um eine Datei anhand des eindeutigen Bezeichners mit der DeleteFileRequest-Klasse zu löschen.

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

DELETE-Anforderung an die Dateispalte senden

Mit der Web-API können Sie eine Datei löschen, indem Sie eine DELETE-Anforderung an den Speicherort der Dateiressource senden.

Im folgenden Beispiel werden Dateidaten für eine Spalte mit dem Namen sample_filecolumn in der account-Tabelle für einen Datensatz mit der accountid hochgeladen, die <accountid> entspricht.

Anforderung:

DELETE [Organization Uri]/api/data/v9.2/accounts(<accountid>)/sample_filecolumn HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

Antwort:

HTTP/1.1 204 NoContent
OData-Version: 4.0

Weitere Informationen: Einzelnen Eigenschaftswert löschen

Siehe auch

Dateien und Bilder – Übersicht
Spaltendatentypen > Dateispalten
Mithilfe von Code mit Dateispaltendefinitionen arbeiten
Beispiel: Dateivorgänge über das Dataverse-SDK für .NET
Beispiel: Dateivorgänge über die Dataverse-API

Hinweis

Können Sie uns Ihre Präferenzen für die Dokumentationssprache mitteilen? Nehmen Sie an einer kurzen Umfrage teil. (Beachten Sie, dass diese Umfrage auf Englisch ist.)

Die Umfrage dauert etwa sieben Minuten. Es werden keine personenbezogenen Daten erhoben. (Datenschutzbestimmungen).