Colonnes d’image

Certaines tables système et toutes les tables personnalisées prennent en charge les images d'entité. Les tables qui prennent en charge les images peuvent contenir à la fois une miniature et une image principale en taille réelle. L’image miniature peut être vue dans l’application Web lors de l’affichage des données du formulaire. Il peut y avoir plusieurs colonnes d’image dans une table, mais il ne peut y avoir qu’une seule image principale. Cependant, vous pouvez changer l’image principale d’une image à une autre en définissant IsPrimaryImage pour cette colonne sur true. Chaque colonne d’image pleine taille est limitée à 30 Mo. Le SchemaName de la colonne d'image d'entité est EntityImage. Pour plus d'informations : Images d'entité

Notes

Vous n’êtes pas sûr de l’entité par rapport à la table ? Voir Développeurs : Comprendre la terminologie dans Microsoft Dataverse.

Les images miniatures et les métadonnées d'image sont stockées dans Microsoft Dataverse, qui comprend les informations nécessaires pour récupérer l'image complète. Les images complètes sont stockées dans le stockage de fichiers sur le blob Azure pour réduire la consommation de stockage de données.

API Web (REST) API .NET (SOAP)
ImageAttributeMetadata ImageAttributeMetadata
IsPrimaryImage, MaxHeight, MaxWidth IsPrimaryImage, MaxHeight, MaxWidth

En plus des colonnes d’image, les tables personnalisées prennent en charge zéro ou plusieurs colonnes de fichier pouvant contenir des données de fichier. Ces colonnes de fichiers peuvent contenir une quantité de données beaucoup plus importante que les colonnes d’images. Pour plus d’informations, consultez les Colonnes de fichier.

Notes

La possibilité de stocker plusieurs colonnes d’image dans une table, le stockage des données d’image dans un objet blob Azure, une taille d’image maximale de 30 Mo et les colonnes de fichier sont prises en charge dansSdkClientVersion 9.0.45.329 ou supérieur et API Web version 9.1 ou supérieure.

Colonnes de soutien

Lorsqu’une colonne d’image est ajoutée à une table, des colonnes supplémentaires sont créées pour la prendre en charge.

Colonne EntityImage_Timestamp

Nom du type d’attribut : BigIntType

La valeur représente la date à laquelle l’image a été mise à jour pour la dernière fois et permet de garantir que la dernière version de l’image est téléchargée et mise en cache sur le client.

Colonne EntityImage_URL

Nom du type d'attribut : StringType

Une URL absolue pour afficher l'image d'entité d'un client.

L'URL est composée de cette façon :

{0}/image/download.aspx?entity={1}&attribute={2}&id={3}&timestamp={4}
  • 0 : URL de l'organisation

  • 1 : Nom logique de la table

  • 2 : Nom logique de la colonne

  • 3 : Valeur EntityImageId

  • 4 : Valeur EntityImage_Timestamp

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

EntityImageId

Nom du type d’attribut : UniqueIdentifierType

Identificateur unique de l’image.

Colonne MaxSizeInKB

Cette valeur représente la taille maximale (en kilo-octets) des données d’image que la colonne peut contenir. Définissez cette valeur sur la plus petite taille de données accessible appropriée pour cette application spécifique. Consultez la propriété MaxSizeInKB pour connaître la limite de la taille autorisée et la valeur par défaut.

Notes

MaxSizeInKB est défini lorsque la colonne d’image est ajoutée à une table. Cette propriété ne peut pas être modifiée une fois qu'elle est définie.

Colonne CanStoreFullImage

Cette valeur indique si une colonne d’image peut peut stocker une image complète. Consultez la propriété CanStoreFullImage.

Récupérer les données d'image

Pour télécharger les données de la colonne d’image miniature, utilisez les API suivantes.

API Web (REST) API .NET (SOAP)
GET /api/data/v9.1/<entity-type(id)>/<image-attribute-name>/$value RetrieveRequest ou RetrieveMultipleRequest

Notes

Lorsque vous utilisez RetrieveMultiple ou Retrieve, l'EntityImage n'est pas incluse lorsque la propriété ColumnSet.AllColumns est définie sur true. En raison de la taille potentielle des données de la colonne, pour la retourner vous devez explicitement le demander.

Les transferts des données d'image depuis les points de terminaison du service Web sont limités à un volume maximum de données de 16 Mo dans un appel de service unique. Les données d'image supérieures à ce volume doivent être réparties en blocs de données de 4 Mo maximum où chaque bloc est reçu dans un appel d'API distinct jusqu'à ce que toutes les données d'image aient été reçues. Il en va de votre responsabilité de joindre les blocs de données chargés pour former l'image complète en associant les blocs de données dans la même séquence que celle où les blocs ont été reçus.

Pour plus d’informations sur la segmentation : Colonnes de fichier.

Pour télécharger les données de la colonne d’image complète, utilisez les API suivantes.

API Web (REST) API .NET (SOAP)
aucun(e) InitializeFileBlocksDownloadRequest
GET /api/data/v9.1/<entity-type(id)>/<image-attribute-name>/$value?size=full DownloadBlockRequest

Notez que dans ce cas, le téléchargement de la colonne d’image utilise les demandes de message de la colonne de fichier.

Exemple : chargement de la miniature REST

Demande

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

Headers:
Content-Type: application/octet-stream

Réponse

204 No Content

Body:
byte[]

Exemple : chargement de l'image en taille réelle REST (<=16 Mo)

Demande

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

Headers:
Content-Type: application/octet-stream

Réponse

204 No Content

Body:
byte[]

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

Dans l'exemple ci-dessus, le paramètre de chaîne de requête size=full indique de charger l'image en taille réelle. Le nom du fichier et la taille seront renseignés dans les en-têtes de réponse.

Exemple : chargement de l'image en taille réelle REST (>16 Mo)

Demande

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

Header:
Range: bytes=0-1023/8192

Réponse

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

Dans l'exemple ci-dessus, l'en-tête Plage indique le premier chargement segmenté de 1 024 octets pour une image qui en fait 8 192 octets en tout.

Charger des données d'image

Pour mettre à jour les images, définissez la valeur de la colonne d’image sur un tableau d’octets contenant le contenu de l’image. Les images miniatures sont rognées et redimensionnées en un carré de 144 x 144 pixels par le service Web afin de limiter la taille des données avant d'être enregistré. La réduction de la taille suit les règles suivantes :

  • Les images possédant au moins un côté supérieur à 144 pixels sont rognées au centre sur 144 x 144.

  • Les images avec les deux côtés inférieurs à 144 sont rognées à angle droit sur leur plus petit côté.

    Le tableau suivant présente deux exemples.

Avant Après
Image avant redimensionnement

300 x 428
image après redimensionnement

144 x 144
Deuxième exemple de redimensionnement d’image

91 x 130
deuxième exemple de redimensionnement

91 x 91

Les images peuvent être chargées en totalité jusqu’à la taille maximale configurée, ou bien par segments.

Notes

À compter de la date de publication de cet article, la restriction d’utilisation du chargement fragmenté pour les images d’une taille supérieure à 16 Mo a été supprimée. Les API de segmentation continueront d’être disponibles pour maintenir la rétrocompatibilité avec les solutions existantes.

Pour charger des données d’image en entier en un seul appel, utilisez les API suivantes.

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

Exemple : Chargement de l’image en taille réelle REST

Demande

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[]

Une fois le chargement terminé, une image miniature est automatiquement créée par le service Web.

Si votre code utilise la méthode héritée, les transferts de données d’image à partir des points de terminaison du service Web sont limités à un maximum de 16 Mo de données en un seul appel de service. Les données d’image de 16 Mo ou plus doivent être divisées en blocs de données de 4 Mo ou moins (segments), où chaque bloc est chargé dans un appel d’API distinct jusqu’à ce que toutes les données d’image aient été reçues. Il en va de votre responsabilité de répartir les données d'image en blocs allant jusqu'à 4 Mo et de les charger dans la bonne séquence.

Pour plus d’informations sur la segmentation : Colonnes de fichier.

Pour utiliser la segmentation héritée afin de télécharger des données d’image d’une taille supérieure à 16 Mo, utilisez les API suivantes.

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

Exemple : Chargement REST avec segmentation (première demande)

Demande

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

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

Réponse

Response:
200 OK

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

Dans l'exemple ci-dessus, l'en-tête x-ms-transfer-mode: chunked indique un chargement segmenté.

Exemple : Chargement REST avec segmentation (demande suivante)

Demande

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[]

Réponse

204 No Content

Dans la demande ci-dessus, le prochain bloc de données est en cours de chargement. Après avoir reçu toutes les données d'image par le service Web, une image miniature est automatiquement créée par le service Web.

Voir aussi

Colonnes de fichier
Présentation des tables dans Dynamics 365
Présentation des colonnes de table dans Dynamics 365
Exemple : Définir et récupérer des images d'entité

Notes

Pouvez-vous nous indiquer vos préférences de langue pour la documentation ? Répondez à un court questionnaire. (veuillez noter que ce questionnaire est en anglais)

Le questionnaire vous prendra environ sept minutes. Aucune donnée personnelle n’est collectée (déclaration de confidentialité).