ファイル列

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

注意

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

Web API	.NET 用 SDK
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 以降でサポートされています。 ファイル列は、メモ (注釈) テーブルでのみ Power Apps ポータルでサポートされます。

サポートされている列

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

MaxValue 列

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

注意

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

ファイル データの取得

Retrieve および RetrieveMultiple メッセージを使用してファイル データをダウンロードできません。

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

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

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

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

Web API

要求

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 用 SDK

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

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

Create および Update メッセージを使用してファイル データをアップロードできません。

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

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

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

注意

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

例: Web 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 の単一データ ファイルに自動的に結合します。

Web API

最初の要求

要求

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 

次の要求

要求

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 用 SDK

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

関連項目

イメージ列

注意

ドキュメントの言語設定についてお聞かせください。 簡単な調査を行います。 (この調査は英語です)

この調査には約 7 分かかります。 個人データは収集されません (プライバシー ステートメント)。