ファイル列

ファイル列は、指定された最大サイズまでのファイル データを格納するために使用されます。 カスタムまたはカスタマイズ可能なテーブルには、0 個以上のファイル列と、各メモに 0 から 1 個の添付ファイルがあるメモ (注釈) コレクションを含めることができます。 ファイル列の SchemaName は、EntityFile です。

注意

エンティティとテーブルの違いがわかりませんか? Microsoft Dataverse で「開発者: 用語を理解する」を参照してください。

Web API (REST) .NET API (SOAP)
FileAttributeMetadata FileAttributeMetadata

許可されないファイルの種類については、 ブロックする添付ファイルの拡張子の設定 設定の システム設定全般タブ を参照してください。

重要

いくつかの制限は、 Microsoft Dataverse のファイルおよび拡張イメージ データ型を使用するときに適用されます。 テナントで顧客管理キー (CMK) が有効になっている場合、テナントの組織は IoT データ型を使用できません。 除外されたデータ型を含むソリューションはインストールされません。 これらのデータ型を使用するには、顧客が CMK をオプトアウトする必要があります。

バージョン: 9.2.21052.00103 現在のすべての CMK 組織は、Dataverse ファイルと画像のデータ型をサポートできます。 CMK 組織内のファイルは、ファイルあたり最大 128MB のサイズに制限されています。 CMK 組織内のすべてのファイルと画像は、Dataverse ファイル Blob Storage の代わりに Dataverse に保存されます。 その他の制限事項:

  • ユーザー委任 SAS ダウンロードはサポートされていません
  • チャンクのアップロードとダウンロードは 1 つのチャンクに制限されています

ファイル列は、SdkClientVersion 9.0.45.329 以降および Web API バージョン 9.1 以降でサポートされています。

サポートされている列

ファイル列がテーブルに追加されると、一部の追加の列がそれをサポートするために作成されます。

MaxValue 列

この値は、列に含めることができるファイル データの最大サイズ (KB) を表します。 この値を、特定のアプリケーションに適した最小の使用可能データ サイズに設定してください。 許容サイズ制限と既定値に対する MaxSizeInKB のプロパティを参照してください。

注意

MaxValue は、ファイル列がテーブルに追加されるときに設定されます。 設定後は変更するできません。

ファイル データ の取得

ファイル列データを取得するには、次の API を使用します。

Web API (REST) .NET API (SOAP)
なし InitializeFileBlocksDownloadRequest
InitializeAttachmentBlocksDownloadRequest
InitializeAnnotationBlocksDownloadRequest
GET /api/data/v9.1/<entity-type(id)>/<file-attribute-name>/$value DownloadBlockRequest

Webサービス エンドポイントからのファイル データ転送は、単一のサービス コールで最大16 MBデータに制限されています。 その量を超えるファイル データは、4 MB以下のデータ ブロック (チャンク) に分割する必要があり、各ブロックはすべてのファイル データが受信されるまで、個別の API 呼び出しで受信されます。 ダウンロードしたデータ ブロックを結合して、ブロックを受信したのと同じ順序でデータ ブロックを結合して完全なデータ ファイルを形成するのは、ユーザーの責任です。

RetrieveRequestRetrieveMultipleRequest などのメッセージは、ファイル列データのダウンロードには使用できません。

例: チャンクを使用した REST ダウンロード

要求

GET [Organization URI]/api/data/v9.1/accounts(id)/myfileattribute/$value
Headers:
Range: bytes=0-1023/8192

回答

206 Partial Content

Body:
byte[]

Response Headers:
Content-Disposition: attachment; filename="sample.txt"
x-ms-file-name: "sample.txt"
x-ms-file-size: 8192
Location: api/data/v9.1/accounts(id)/myfileattribute?FileContinuationToken

チャンクは、リクエストの Range ヘッダー の存在に基づいて決定されます。 範囲ヘッダー値の形式は: startByte-endByte/total バイトです。 Range ヘッダーが含まれない場合、完全なファイルは 1 回のリクエストで (最大 16 MB) ダウンロードされます。 チャンクの場合、 Location 応答ヘッダーは、クエリ可能なパラメーター FileContinuationToken を含みます。 次の GET 要求で保存先ヘッダー値を使用して、順序内の次のデータ ブロックを取得します。

例: チャンクを使用してダウンロードするための .NET C# コード

static async Task ChunkedDownloadAsync(
            Uri urlPrefix,
            string customEntitySetName,
            string entityId,
            string entityFileOrAttributeAttributeLogicalName,
            string fileRootPath,
            string downloadFileName,
            string token)
        {
            var url = new Uri(urlPrefix, $"{customEntitySetName}({entityId})/{entityFileOrAttributeAttributeLogicalName}/$value?size=full");
            var increment = 4194304;
            var from = 0;
            var fileSize = 0;
            byte[] downloaded = null;
            do
            {
                using (var request = new HttpRequestMessage(HttpMethod.Get, url))
                {
                    request.Headers.Range = new System.Net.Http.Headers.RangeHeaderValue(from, from + increment - 1);
                    request.Headers.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", token);
                    using (var response = await Client.SendAsync(request))
                    {
                        if (downloaded == null)
                        {
                            fileSize = int.Parse(response.Headers.GetValues("x-ms-file-size").First());
                            downloaded = new byte[fileSize];
                        }

                        var responseContent = await response.Content.ReadAsByteArrayAsync();
                        responseContent.CopyTo(downloaded, from);
                    }
                }

                from += increment;
            } while (from < fileSize);

            await File.WriteAllBytesAsync(Path.Combine(fileRootPath, downloadFileName), downloaded);
        }

ファイル データ のアップロード

ファイル列データをアップロードするには、次の API を使用します。

Web API (REST) .NET API (SOAP)
なし InitializeFileBlocksUploadRequest
InitializeAttachmentBlocksUploadRequest
InitializeAnnotationBlocksUploadRequest
PATCH /api/data/v9.1/<entity-type(id)>/<file-attribute-name> UploadBlockRequest
なし CommitFileBlocksUploadRequest
CommitAttachmentBlocksUploadRequest
CommitAnnotationBlocksUploadRequest

ファイルは、構成された最大サイズまで完全にアップロードすることも、チャンクでアップロードすることもできます。

注意

この記事の公開日をもって、16MB を超えるファイルに対してチャンク アップロードを使用するという制限がなくなりました。 チャンキング API は、既存のソリューションとの下位互換性を維持するために引き続き利用できます。

例: 完全なファイル アップロード用の.NET C# コード

static async Task FullFileUploadAsync(
            Uri urlPrefix,
            string customEntitySetName,
            string entityId,
            string entityFileOrAttributeAttributeLogicalName,
            string fileRootPath,
            string uploadFileName,
            string accessToken)
        {
            var filePath = Path.Combine(fileRootPath, uploadFileName);
            var fileStream = File.OpenRead(filePath);
            var url = new Uri(urlPrefix, $"{customEntitySetName}({entityId})/{entityFileOrAttributeAttributeLogicalName}");

            using (var request = new HttpRequestMessage(new HttpMethod("PATCH"), url))
            {
                request.Headers.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", accessToken);
                                request.Content = new StreamContent(fileStream);
                request.Content.Headers.Add("Content-Type", "application/octet-stream");
                request.Content.Headers.Add("x-ms-file-name", uploadFileName);
                                
                using (var response = await Client.SendAsync(request))
                {
                    response.EnsureSuccessStatusCode();
                }
            }
        }

以下は、4MB 以下のファイルデータブロックを分割して16MB 以上のデータファイルをアップロードする従来の方法です。 データ ブロックの完全なセットをアップロードし、コミット 要求を送信すると、Web サービスは、データ ブロックがアップロードされたのと同じ順序で、ブロックを Azure Blob Storage の単一データ ファイルに自動的に結合します。

CreateRequestUpdateRequest などのメッセージは、ファイル列データのアップロードには使用できません。

例: REST チャンクを使用してアップロード (最初の要求)

要求

PATCH [Organization URI]/api/data/v9.1/accounts(id)/myfileattribute 

Headers: 
x-ms-transfer-mode: chunked 
x-ms-file-name: sample.png

要求 (代替フォーム)

このフォームの要求では、クエリ文字列パラメーターを使用し、非 ASCII 言語ファイル名をサポートします。 ファイル名がヘッダーとクエリ文字列パラメーターの両方で指定されている場合は、ヘッダー値が優先されます。

PATCH [Organization URI]/api/data/v9.1/accounts(id)/myfileattribute?x-ms-file-name=测试.txt

Headers: 
x-ms-transfer-mode: chunked

回答

200 OK 

Response Headers: 
x-ms-chunk-size: 4096 
Accept-Ranges: bytes 
Location: api/data/v9.1/accounts(id)/myfileattribute?FileContinuationToken 

例: REST チャンクを使用してアップロード (次の要求)

要求

PATCH [Organization URI]/api/data/v9.1/accounts(id)/myfileattribute?FileContinuationToken 

Headers: 
Content-Range: bytes 0-4095/8192 
Content-Type: application/octet-stream
x-ms-file-name: sample.png

Body:
byte[]

応答

206 Partial Content

例: チャンクを使用してアップロードするための .NET C# コード

static async Task ChunkedUploadAsync(
            Uri urlPrefix,
            string customEntitySetName,
            string entityId,
            string entityFileOrAttributeAttributeLogicalName,
            string fileRootPath,
            string uploadFileName,
            string accessToken)
        {
            var filePath = Path.Combine(fileRootPath, uploadFileName);
            var fileBytes = await File.ReadAllBytesAsync(filePath);
            var url = new Uri(urlPrefix, $"{customEntitySetName}({entityId})/{entityFileOrAttributeAttributeLogicalName}");

            var chunkSize = 0;
            using (var request = new HttpRequestMessage(HttpMethod.Patch, url))
            {
                request.Headers.Add("x-ms-transfer-mode", "chunked");
                request.Headers.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", accessToken);
                request.Headers.Add("x-ms-file-name", uploadFileName);
                using (var response = await Client.SendAsync(request))
                {
                    response.EnsureSuccessStatusCode();
                    url = response.Headers.Location;
                    chunkSize = int.Parse(response.Headers.GetValues("x-ms-chunk-size").First());
                }
            }

            for (var offset = 0; offset < fileBytes.Length; offset += chunkSize)
            {
                var count = (offset + chunkSize) > fileBytes.Length ? fileBytes.Length % chunkSize : chunkSize;
                using (var content = new ByteArrayContent(fileBytes, offset, count))
                using (var request = new HttpRequestMessage(HttpMethod.Patch, url))
                {
                    content.Headers.Add("Content-Type", "application/octet-stream");
                    content.Headers.ContentRange = new System.Net.Http.Headers.ContentRangeHeaderValue(offset, offset + (count - 1), fileBytes.Length);
                    request.Headers.Add("x-ms-file-name", uploadFileName);
                    request.Headers.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", accessToken);
                    request.Content = content;
                    using (var response = await Client.SendAsync(request))
                    {
                        response.EnsureSuccessStatusCode();
                    }
                }
            }
        }

ファイル データの削除

ファイル列データをストレージから削除するには、次の API を使用します。

Web API (REST) .NET API (SOAP)
DELETE /api/data/v9.1/<entity-type(id)>/<attribute-name> DeleteFileRequest

関連項目

イメージ列