ファイル列のデータを使用する

[アーティクル]
02/01/2024

画像列またはファイル列を使用して、Dataverse に画像データを保存できます。画像列を含むファイル列には、多くの API を使用できます。画像列には、アプリケーション内でのイメージの表示をサポートするために、いくつかの特別な動作と制限があります。

次の表は、画像列とファイル列の違いの一部を示しています。

	Image	File
File Size	30 MB に制限されています。	最大 10 GB。 API は最大 10 GB のサイズのファイルを処理できますが、 Power Apps クライアントコントロールは現在、最大128 MBのファイルのみをサポートしています。これらのコントロールを使用するときに128 MBの値を超えると、ファイルのアップロードまたはダウンロードでエラーが発生します。
ファイルの種類	画像ファイルの種類のみ	Organization.BlockedAttachments 値で許可されているすべてのファイルの種類。詳細: Dataverse のテーブルの種類
更新で設定	更新を使用して、画像列データを他のレコードデータと一緒に設定できます。	ファイル列のプロパティには、ファイルを個別にアップロードすることしかできません。
更新で削除	属性またはプロパティを `null` に設定して画像列データを削除し、レコードを更新できます。詳細: イメージの削除	`DeleteFile` メッセージを使用するか、Web API を使用して特定の列に `DELETE` リクエストを送信することによってのみ、ファイル列データを削除できます。詳細: ファイルの削除
作成で設定	画像列が主画像の場合、作成で他のレコードデータと画像データをセットすることができます。詳細: 主画像	レコードが作成された後、ファイル列のプロパティには、ファイルを個別にアップロードすることしかできません。
取得で返す	取得を使用して、他のレコードデータと一緒にサムネイルサイズの画像を取得できます。	返された値はファイル ID です。詳細: 取得時の動作
ダウンロード URL	各画像列には、画像ファイルをダウンロードできるアプリケーションに含めることができる相対 URL を含む文字列列があります。詳細: URL をダウンロードする	ダウンロード URL を含む文字列列はありませんが、Web API から直接ファイルをダウンロードする URL を作成できます。詳細: Web API を使用して 1 回のリクエストでファイルをダウンロードする

画像の最大サイズ

ファイル列と同様に、MaxSizeInKb プロパティを使用して画像列に格納されるデータの最大サイズを指定できます。しかし、許可される最大バッチサイズは 30 MB です。

大きすぎるファイルをアップロードしようとすると、次のエラーが発生します:

名前: ProcessImageFailure
コード: 0x80072553
番号: -2147015341
メッセージ: Error occured when processing image. Reason: File size is too big. MaxSize: 0 MB, Uploaded filesize: 0 MB.

次の例を使用して、最大ファイルサイズを確認できます:

.NET 用 SDK
Web API

次の静的 GetImageColumnMaxSizeInKb メソッドは、ImageAttributeMetadata 列の MaxSizeInKB 値を返します。

/// <summary>
/// Retrieves the MaxSizeInKb property of an image column.
/// </summary>
/// <param name="service">IOrganizationService</param>
/// <param name="entityLogicalName">The logical name of the table that has the column</param>
/// <param name="imageColumnLogicalName">The logical name of the image column.</param>
/// <returns></returns>
/// <exception cref="Exception"></exception>
public static int GetImageColumnMaxSizeInKb(
   IOrganizationService service, 
   string entityLogicalName, 
   string imageColumnLogicalName) 
{

   RetrieveAttributeRequest retrieveAttributeRequest = new() { 
         EntityLogicalName = entityLogicalName,
         LogicalName = imageColumnLogicalName
   };

   RetrieveAttributeResponse retrieveAttributeResponse;
   try
   {
         retrieveAttributeResponse = (RetrieveAttributeResponse)service.Execute(retrieveAttributeRequest);
   }
   catch (Exception)
   {
         throw;
   }

   if (retrieveAttributeResponse.AttributeMetadata is ImageAttributeMetadata imageColumn)
   {
         return imageColumn.MaxSizeInKB.Value;
   }
   else
   {
         throw new Exception($"{entityLogicalName}.{imageColumnLogicalName} is not a image column.");
   }
}

詳細情報:

次のリクエストは、account テーブルの論理名 sample_imagecolumn のImageAttributeMetadata 列の MaxSizeInKB 値を返します。

要求:

GET [Organization Uri]/api/data/v9.2/EntityDefinitions(LogicalName='account')/Attributes(LogicalName='sample_imagecolumn')/Microsoft.Dynamics.CRM.ImageAttributeMetadata?$select=MaxSizeInKB HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

応答:

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.ImageAttributeMetadata(MaxSizeInKB)/$entity",
  "MaxSizeInKB": 102400,
  "MetadataId": "f315e7f1-6355-ed11-bba3-000d3a9933c9"
}

詳細情報:

画像ファイルの種類

イメージ列には、次のバイナリイメージタイプが格納されます。

File Format	MIME の種類	ファイル拡張子
JPEグラフィックス交換形式	`image/gif`	`.gif`
共同写真専門家グループのイメージ	`image/jpeg`	`.jpg`, `.jpeg`
ビットマップファイル	`image/bmp`	`.bmp`
ポータブルネットワークグラフィックス	`image/png`	`.png`

これらのタイプ以外のファイルを保存しようとすると、次のエラーが発生します。

名前: ProcessImageFailure
コード: 0x80072553
番号: -2147015341
メッセージ: Error occured when processing image. Reason: Update image properties failed for objectid: <id of record>, logicalName: <logical name of table>, attribute: <logical name of image column

フルサイズとサムネイルサイズの画像

画像列の値が設定されると、Dataverse は、アプリケーションでアイコンとして使用するのに適したサムネイルサイズの画像を自動的に生成します。

画像列がフルサイズの画像を保存するように構成されている場合、構成された MaxSizeInKb までのファイルを、サムネイルサイズの画像とは別に保存およびダウンロードできます。 ImageAttributeMetadata.CanStoreFullImage プロパティは、画像列にフルサイズの画像を保存するかどうかを制御します。

フルサイズの画像をサポートする画像列を検出する

画像属性構成 (AttributeImageConfig) テーブルをクエリして、parententitylogicalname、attributelogicalname、および canstorefullimage 列の値を使用して、フルサイズの画像をサポートする画像列のリストを取得できます。

.NET 用 SDK
Web API

静的 PrintFullSizedImageColumns メソッドは、フルサイズの画像を格納できるテーブルと画像列の名前を書き込みます。

static void PrintFullSizedImageColumns(IOrganizationService service)
{
    QueryExpression query = new QueryExpression("attributeimageconfig")
    {
        ColumnSet = new ColumnSet("parententitylogicalname", "attributelogicalname"),
        Criteria = new FilterExpression(LogicalOperator.And)
        {
            Conditions =
            {
                new ConditionExpression(
                    attributeName: "canstorefullimage",
                    conditionOperator: ConditionOperator.Equal,
                    value: true)
            }
        }
    };

    EntityCollection response = service.RetrieveMultiple(query);
    foreach (Entity record in response.Entities)
    {
        Console.WriteLine($"{record["parententitylogicalname"]}.{record["attributelogicalname"]}");
    }
}

Output

account.sample_sampleimage

子のリクエストは、フルサイズの画像を格納できるテーブルと画像列の名前を書き込みます。

要求:

GET [Organization URI]/api/data/v9.2/attributeimageconfigs?$select=parententitylogicalname,attributelogicalname&$filter=canstorefullimage eq true HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

応答:

HTTP/1.1 200 OK
Cache-Control: no-cache
Allow: OPTIONS,GET,HEAD,POST
Content-Type: application/json; odata.metadata=minimal; odata.streaming=true
OData-Version: 4.0

{
  "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#attributeimageconfigs(parententitylogicalname,attributelogicalname)",
  "value": [
    {
      "@odata.etag": "W/\"76501240\"",
      "parententitylogicalname": "account",
      "attributelogicalname": "sample_sampleimage",
      "attributeimageconfigid": "b8c1750f-c24f-ea11-a813-000d3a5391c8"
    }
  ]
}

スキーマ定義をクエリして、ImageAttributeMetadata.CanStoreFullImage プロパティが true のある列を返すこともできます。詳細: セグメントクエリの定義

サムネイルサイズの画像のサイズ変更ルール

サムネイルサイズの画像を生成するには、Dataverse は次のルールに従って、画像をトリミングして正方形にサイズ変更します。

少なくとも 1 つの側面が 144 ピクセルより大きいイメージは中心で 144x144 に切り取られます。
両側が144未満のイメージは最小のサイドに正方形に切り取られます。

次の表に2つの例を示します。

次の日付より前	後
300x428	144x144
91x130	91x91

プライマリイメージ

各テーブルには複数の画像列を含めることができますが、プライマリイメージ として定義できるのは 1 つの画像列のみです。作成操作で設定できるのはプライマリイメージのみです。詳細: プライマリイメージのみを作成用に設定できます

プライマリイメージを表すイメージ列を表す、ImageAttributeMetadata.IsPrimaryImage プロパティコントロール。

EntityMetadata.PrimaryImageAttribute プロパティは、テーブルのプライマリイメージである画像れるの論理名を返します。

エンティティイメージ構成 (EntityImageConfig) テーブルを使用して、parententitylogicalname と primaryimageattribute 列の値を使用して、現在のプライマリイメージを表すイメージ列を特定します。

.NET 用 SDK
Web API

静的 PrintPrimaryImageColumns 以下のメソッドは、すべてのプライマリイメージ列のテーブルとイメージの列名を書き込みます。

static void PrintPrimaryImageColumns(IOrganizationService service)
{
    QueryExpression query = new QueryExpression("entityimageconfig")
    {
        ColumnSet = new ColumnSet("parententitylogicalname", "primaryimageattribute"),
    };

    EntityCollection response = service.RetrieveMultiple(query);
    foreach (Entity record in response.Entities)
    {
        Console.WriteLine($"{record["parententitylogicalname"]}.{record["primaryimageattribute"]}");
    }
}

Output

account.sample_sampleimage

詳細情報: QueryExpression を使用してクエリを作成する

以下のリクエストは、すべてのプライマリイメージ列のテーブルとイメージの列名を書き込みます。

要求:

GET [Organization URI]/api/data/v9.2/entityimageconfigs?$select=parententitylogicalname,primaryimageattribute HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

応答:

HTTP/1.1 200 OK
Cache-Control: no-cache
Allow: OPTIONS,GET,HEAD,POST
Content-Type: application/json; odata.metadata=minimal; odata.streaming=true
OData-Version: 4.0

{
  "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#entityimageconfigs(parententitylogicalname,primaryimageattribute)",
  "value": [
    {
      "@odata.etag": "W/\"76501240\"",
      "parententitylogicalname": "account",
      "primaryimageattribute": "sample_sampleimage",
      "entityimageconfigid": "b8c1750f-c24f-ea11-a813-000d3a5391c8"
    }
  ]
}

詳細: Web API を使用するクエリデータ

Download URL

各画像列には次のコンパニオン列がありますが、いずれも Power Apps デザイナー内には現れません。

Column	タイプ	名前付け規則	Description
画像 ID	一意識別子	`<image column name>Id`	イメージの一意の識別子。
タイムスタンプ	BigInt	`<image column name>_Timestamp`	イメージが最後に更新した時を表します。この値は、クライアントが以前に取得されたキャッシュバージョンを使用するのではなく、最新バージョンのイメージがダウンロードされるようにするのに役立ちます。
[URL]	string	`<image column name>_URL`	画像のサムネイルサイズバージョンをダウンロードするための相対 URL

イメージ ID とタイムスタンプの列の値には、URL 文字列の列の値内で使用される場合を除いて、使用例はありません。

レコードの列にデータが含まれている場合、ダウンロード URL は次の形式を使用した相対 URL になります。

/Image/download.aspx?Entity=<entity logical name>&Attribute=<image column logical name>&Id=<image id value>&Timestamp=<time stamp value>

この値を組織の URI に追加して、サムネイルサイズの画像ファイルのダウンロードに使用できるURLを作成できます。例:

https://yourorg.crm.dynamics.com/Image/download.aspx?Entity=account&Attribute=sample_imagecolumn&Id=7a4814f9-b0b8-ea11-a812-000d3a122b89&Timestamp=637388308718090885

フルサイズの画像をダウンロードする URL

画像列がフルサイズの画像を保存するように構成されている場合、URLに &Full=true を追加すると、リンクからフルサイズの画像がダウンロードされます。例:

https://yourorg.crm.dynamics.com/Image/download.aspx?Entity=account&Attribute=sample_imagecolumn&Id=7a4814f9-b0b8-ea11-a812-000d3a122b89&Timestamp=637388308718090885&Full=true

フルサイズの画像を格納するように列が構成されていない場合、データは返されません。

レコードで画像データを使用する

レコードを操作する場合、画像データを操作する方法は、SDK と Web API のどちらを使用しているかによって異なります。

.NET 用 SDK
Web API

次の静的 RetrieveAndUpdateImageColumn メソッドは、列から byte[] イメージの値を取得し、それをローカルに保存して、新しいイメージをアップロードします。

static void RetrieveAndUpdateImageColumn(
    IOrganizationService service,
    Guid accountid,
    string imageColumnLogicalName) 
{

    // Retrieve account with image
    Entity account = service.Retrieve(
        entityName: "account",
        id: accountid, 
        columnSet: new ColumnSet(imageColumnLogicalName));

    // Save the image retrieved
    File.WriteAllBytes(
        path: "original_image.png",
        bytes: account.GetAttributeValue<byte[]>(imageColumnLogicalName));


    // Instantiate a new entity for update with new image
    Entity accountForUpdate = new("account") { 
        Attributes = {
            { "accountid", accountid },
            { imageColumnLogicalName , File.ReadAllBytes("new_image.png")}
        }
    };

    // Update the account
    service.Update(accountForUpdate);               
}

注意

ColumnSet.AllColumns プロパティを true に設定すると、画像列は含まれません。パフォーマンス上の理由から、イメージデータを取得することを明示的に指定する必要があります。

詳細情報:

Web API では、プロパティ値は byte[] データを表す base 64 でエンコードされた文字列値です。

このリクエストは、取引先企業レコードを持つ sample_imagecolumn という名前の画像列とアカウントレコードを返します。

要求:

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

応答:

HTTP/1.1 200 OK
ETag: W/"76796548"
OData-Version: 4.0

{
  "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#accounts(sample_imagecolumn)/$entity",
  "@odata.etag": "W/\"76796548\"",
  "sample_imagecolumn": "<base 64 encoded string truncated for brevity>",
  "accountid": "<accountid>"
}

このリクエストは、sample_imagecolumn 画像列を更新された画像で更新します。

要求:

PATCH [Organization Uri]/api/data/v9.2/accounts(<accountid>) HTTP/1.1
If-Match: *
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json
Content-Type: application/json; charset=utf-8
Content-Length: 5220

{
  "sample_imagecolumn": "<base 64 encoded string truncated for brevity>"
}

応答:

HTTP/1.1 204 NoContent
OData-Version: 4.0
OData-EntityId: [Organization Uri]/api/data/v9.2/accounts(<accountid>)

JSON.NET など、JSON をシリアライズおよびデシリアライズするために使用する一部のライブラリは、これらのエンコードされた文字列値を自動的に byte[] に変換します。トランスポートプロトコルが base 64 文字列を使用していることに注意してください。

Base 64 でエンコードされた文字列の詳細については、次を参照してください。

詳細情報:

プライマリイメージのみを作成用に設定できます

レコードを作成するときは、現在のプライマリイメージ列の値のみを設定できます。他の画像列の値を設定しようとすると、次のエラーが発生します。

名前: CannotUploadNonPrimaryImageAttributeOnCreate
コード: 0x80090487
番号: -2146892665
メッセージ: Non-primary image attribute <image column logical name> of entity <table logical name> is not allowed to upload during Create operation.

詳細: 主画像

サムネイル画像のみ取得可能

レコードプロパティを介してアクセスする画像データは、常にサムネイルサイズの画像になります。フルサイズの画像にアクセスするには、ダウンロードする必要があります。詳細: イメージをダウンロードする

画像のアップロード

ファイルのアップロードに使用するのと同じ API を使用して、画像を個別にアップロードします。詳細: ファイルの更新

イメージのダウンロード

ファイルのダウンロードに使用するのと同じ API を使用して画像をダウンロードしますが、次の違いに注意してください。

Dataverse メッセージの使用

InitializeFileBlocksDownload メッセージと DownloadBlock メッセージを使用すると、画像列がフルサイズの画像をサポートしていれば、常にフルサイズの画像がダウンロードされます。この方法を使用してサムネイルサイズの画像をダウンロードすることはできません。詳細: Dataverse メッセージを使用してファイルをダウンロードする

画像列がフルサイズの画像をサポートしていない場合、または画像がアップロードされたときに ImageAttributeMetadata.CanStoreFullImage プロパティが false であった場合、次のエラーが返されます。

名前: ObjectDoesNotExist
コード: 0x80040217
番号: -2147220969
メッセージ: No FileAttachment records found for imagedescriptorId: <guid> for image attribute: <image column logical name> of <entity logical name> record with id <guid>.

Web API の使用

Dataverse メッセージを使用せずに Web API を使用して画像をダウンロードすると、デフォルトでサムネイルサイズの画像がダウンロードされます。フルサイズの画像をダウンロードするには、このパラメーターを URL に追加する必要があります: ?size=full。

画像列がフルサイズの画像をサポートしていない場合、または画像がアップロードされたときに ImageAttributeMetadata.CanStoreFullImage プロパティが false であった場合、204 No Content が返されます。

詳細: ファイルをダウンロードする

画像を削除する

他のプロパティの場合と同様に、レコードの画像列の値を null に設定することで、画像を削除できます。

.NET 用 SDK
Web API

単に画像属性の値を null に設定して、エンティティをアップロードします。詳細情報: 基本アップデート

Web API を使用して画像列の値を削除するには、3 つの方法があります。

PATCH を使用し、画像列の値を null に設定する

要求:

PATCH [Organization Uri]/api/data/v9.2/accounts(<accountid>) HTTP/1.1
If-Match: *
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json
Content-Type: application/json; charset=utf-8
Content-Length: 90

{
  "accountid": "<accountid>",
  "sample_imagecolumn": null
}

応答:

HTTP/1.1 204 NoContent
OData-Version: 4.0
OData-EntityId: [Organization Uri]/api/data/v9.2/accounts(<accountid>)

詳細情報: 基本アップデート

PUT を使用し、画像列の値を null に設定する

要求:

PUT [Organization Uri]/api/data/v9.2/accounts(<accountid>)/sample_imagecolumn 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: 15

{"value": null}

応答:

HTTP/1.1 204 NoContent
OData-Version: 4.0

詳細: 単一のプロパティ値を更新する

画像列を参照するリソース URL で DELETE を使用します

要求:

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

応答:

HTTP/1.1 204 NoContent
OData-Version: 4.0

詳細情報: 単一のプロパティ値を削除する

参照

ファイルおよび画像の概要
 コードを使って画像列定義を操作する
 サンプル: Dataverse SDK for .NET を使用したファイル操作
 サンプル: Dataverse Web API を使用したファイル操作
 ファイル列のデータを使用する

次の方法で共有

ファイル列のデータを使用する

画像の最大サイズ

画像ファイルの種類

フルサイズとサムネイルサイズの画像

フルサイズの画像をサポートする画像列を検出する

サムネイルサイズの画像のサイズ変更ルール

プライマリイメージ

Download URL

フルサイズの画像をダウンロードする URL

レコードで画像データを使用する

プライマリイメージのみを作成用に設定できます

サムネイル画像のみ取得可能

画像のアップロード

イメージのダウンロード

Dataverse メッセージの使用

Web API の使用

画像を削除する

PATCH を使用し、画像列の値を null に設定する

PUT を使用し、画像列の値を null に設定する

画像列を参照するリソース URL で DELETE を使用します

参照

フィードバック

その他のリソース

次の方法で共有

ファイル列のデータを使用する

画像の最大サイズ

画像ファイルの種類

フルサイズとサムネイルサイズの画像

フルサイズの画像をサポートする画像列を検出する

サムネイル サイズの画像のサイズ変更ルール

プライマリ イメージ

Download URL

フルサイズの画像をダウンロードする URL

レコードで画像データを使用する

プライマリ イメージのみを作成用に設定できます

サムネイル画像のみ取得可能

画像のアップロード

イメージのダウンロード

Dataverse メッセージの使用

Web API の使用

画像を削除する

参照

フィードバック

その他のリソース

サムネイルサイズの画像のサイズ変更ルール

プライマリイメージ

プライマリイメージのみを作成用に設定できます