イメージ列

[アーティクル]
07/07/2022

特定のシステムテーブルとすべてのカスタムテーブルはエンティティイメージをサポートします。イメージをサポートするテーブルには、サムネイルとフルサイズのプライマリイメージの両方を含めることができます。サムネイルイメージは、フォームデータを表示するときに Web アプリケーションで表示できます。テーブルには複数のイメージ列を含めることができますが、プライマリイメージは 1 つだけにすることができます。ただし、その列の IsPrimaryImage を true に設定設定することで、プライマリイメージを別のイメージに変更できます。フルサイズの各画像列のサイズは 30MB に制限されています。エンティティイメージ列の SchemaName は EntityImage です。

注意

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

サムネイル画像と画像のメタデータは、画像全体を取得するために必要な情報を含む Microsoft Dataverse に格納されます。フル画像は、Azure Blob のファイルストレージに保存され、データストレージの消費を削減します。

Web API	.NET 用 SDK
ImageAttributeMetadata	ImageAttributeMetadata
`IsPrimaryImage`、`MaxHeight`、`MaxWidth`	IsPrimaryImage、 MaxHeight、 MaxWidth

カスタムテーブルは、画像列に加えて、任意のファイルデータを含むことができる 0 個以上のファイル列をサポートします。これらのファイル列には、画像列よりもはるかに大量のデータを含めることができます。詳細については、ファイル列を参照してください。

注意

1 つのテーブルに複数のイメージ列を格納する機能、Azure BLOB に画像データを格納する機能、最大 30 MB のイメージサイズ、およびファイル列が SdkClientVersion 9.0.45.329 以降および Web API バージョン 9.1 以降でサポートされています。

サポートされている列

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

EntityImage_Timestamp 列

属性の種類名: BigIntType

EntityImage_Timestamp 値は、イメージが最後に更新されときに表され、イメージの最新版がクライアントでダウンロードされ、キャッシュされることが確実にできるように使用されます。

EntityImage_URL 列

属性の種類名: StringType

クライアントでエンティティイメージを表示する絶対 URL。

EntityImage_URL 列の値は、URL が次のように構成されている場合です。

{0}/image/download.aspx?entity={1}&attribute={2}&id={3}&timestamp={4}

0 : 組織 URL
1 : テーブルの論理名
2 : 列の論理名
3 : EntityImageId の値です。
4 : EntityImage_Timestamp の値

例:

https://myorg.crm.dynamics.com/image/download.aspx?attribute=entityimage&entity=contact&id={ECB6D3DF-4A04-E311-AFE0-00155D9C3020}&timestamp=635120312218444444

EntityImageId

属性の種類名: UniqueIdentifierType

画像の一意識別子。

MaxSizeInKB 列

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

注意

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

CanStoreFullImage 列

CanStoreFullImage 値は、画像の列に完全な画像を保存できるかどうかを示します。 CanStoreFullImage プロパティを参照してください。

イメージデータを取得する

サムネイル画像の列データをダウンロードするには、次の API を使用します。

Web API	.NET 用 SDK
GET /api/data/v9.1/<entity-type(id)>/<image-attribute-name>/$value	RetrieveRequest または RetrieveMultipleRequest

注意

RetrieveMultiple または Retrieve を使用すると、ColumnSet.AllColumns プロパティが true に設定されている場合は EntityImage は含まれません。この列のデータの潜在的なサイズのために、この列を返すためには、明示的に要求する必要があります。

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

詳細については、ファイル列を参照してください。

フルイメージの列データをダウンロードするには、次の API を使用します。

Web API	.NET 用 SDK
なし	InitializeFileBlocksDownloadRequest
GET /api/data/v9.1/<entity-type(id)>/<image-attribute-name>/$value?size=full	DownloadBlockRequest

この場合、イメージ列のダウンロードはファイル列のメッセージ要求を利用することに注意してください。

例: REST サムネイルのダウンロード

要求

GET [Organization URI]/api/data/v9.1/accounts(b9ccec62-f266-e911-8196-000d3a6de638)/myentityimage/$value

Headers:
Content-Type: application/octet-stream

応答

204 No Content

Body:
byte[]

例: REST 完全なイメージのダウンロード (<=16MB)

要求

GET [Organization URI]/api/data/v9.1/accounts(C0864F1C-0B71-E911-8196-000D3A6D09B3)/myentityimage/$value?size=full

Headers:
Content-Type: application/octet-stream

応答

204 No Content

Body:
byte[]

Response Headers:
x-ms-file-name: "sample.png"
x-ms-file-size: 12345

上記の例では、クエリ文字列のパラメーター size=full が、完全なイメージをダウンロードすることを示します。ファイル名とサイズは、応答ヘッダーで提供されます。

例: REST 完全なイメージのダウンロード (>16MB)

要求

GET [Organization URI]/api/data/v9.1/accounts(C0864F1C-0B71-E911-8196-000D3A6D09B3)/myentityimage/$value?size=full

Header:
Range: bytes=0-1023/8192

応答

206 Partial Content

Body:
byte[]

Response Headers:
x-ms-file-name: "sample.png"
x-ms-file-size: 8192
Location: api/data/v9.1/accounts(id)/myentityimage?FileContinuationToken

上記の例では、範囲ヘッダーは、合計 8192 バイトのイメージに対して 1024 バイトの最初のチャンクにしたダウンロードを示します。

イメージデータをアップロードする

画像を更新するには、画像列の値を画像ファイルのコンテンツを含むバイトアレイに設定します。サムネイルイメージは、保存前にデータのサイズを小さくするために、Web サービスによって 144x144 ピクセルの四角形に切り取られ、サイズ変更されます。サイズの縮小は、次のルールに従います:

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

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

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

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

注意

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

1 回の呼び出しで完全なイメージデータをアップロードするには、次の API を使用します。

Web API	.NET 用 SDK
`PUT`/api/data/v9.1/<entity-type(id)>/<image-attribute-name>	CreateRequest
`PATCH` /api/data/v9.1/<entity-type(id)>/<image-attribute-name>	UpdateRequest

例: REST フルイメージのアップロード

要求

PUT [Organization URI]/api/data/v9.1/accounts(C0864F1C-0B71-E911-8196-000D3A6D09B3)/myentityimage

Header:
Content-Type: application/octet-stream
x-ms-file-name: sample.png

Body:
byte[]

アップロードが完了したら、サムネイル画像は、Webサービスによって自動的に生成されます。

コードが従来の方法を使用している場合、Web サービスエンドポイントからのイメージデータ転送は、1 回のサービス呼び出しで最大 16MB のデータに制限されます。 16MB 以上のイメージデータは 4MB 以下のデータブロック (チャンク) に分割する必要があり、すべてのイメージデータが受信されるまで、各ブロックが個別の API 呼び出しでアップロードされます。イメージデータを最大 4 MB のブロックに分割し、正しい順序でアップロードするのはユーザーの責任です。

詳細については、ファイル列を参照してください。

従来のチャンクを使用して 16MB を超えるサイズのイメージデータをアップロードするには、次の API を使用します。

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

例: チャンクを使用した REST アップロード

最初の要求

要求

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

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

応答

Response:
200 OK

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

上記の例で x-ms-transfer-mode: chunked ヘッダーは、チャンクアップロードを示します。

次の要求

要求

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

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

Body:
byte[]

応答

204 No Content

上記要求では、データの次のブロックがアップロードがされます。すべてのイメージデータが、Web サービスによって受け取られた後、サムネイル画像が Web サービスによって自動的に作成されます。

参照

ファイル列
 Microsoft Dataverse のテーブル定義
 列の定義
 サンプル: エンティティイメージを設定および取得する

注意

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

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