Partager via

Utiliser les données de colonne d’image

  • Article

Vous pouvez stocker des données d’image dans Dataverse à l’aide de colonnes d’image ou de colonnes de fichier. Vous pouvez utiliser de nombreuses API pour les colonnes de fichiers avec des colonnes d’images. Les colonnes d’image ont des comportements et des limitations spécifiques pour prendre en charge l’affichage d’images dans les applications.

Le tableau suivant présente certaines différences entre les colonnes d’image et de fichier.

Image File
Taille de fichier Limité à 30 Mo. Jusqu’à 10 Go. Bien que l’API puisse gérer des fichiers d’une taille maximale de 10 Go, les contrôles client de Power Apps ne prennent actuellement en charge que les fichiers d’une taille maximale de 128 Mo. Le dépassement de la valeur de 128 Mo lors de l’utilisation de ces contrôles entraînera des erreurs lors du chargement ou du téléchargement des fichiers.
Types de fichiers Seulement des types de fichier Image Tous les types de fichiers autorisés par la valeur Organization.BlockedDocuments joints. Pour plus d’informations : Bloquer certains types de fichiers
Définir avec Update Vous pouvez définir des données de colonne d’image avec d’autres données d’enregistrement à l’aide de Update. Vous pouvez uniquement télécharger des fichiers individuellement dans les propriétés de colonne de fichier.
Supprimer avec Update Vous pouvez supprimer des données de colonne d’image en définissant l’attribut ou la propriété sur null , puis mettre à jour l’enregistrement. Pour plus d’informations : Supprimer des images Vous ne pouvez supprimer les données de colonne de fichier qu’à l’aide du message DeleteFile ou de l’envoi d’une requête DELETE à la colonne spécifique à l’aide de l’API web. Pour plus d’informations : Supprimer des fichiers
Définir avec Create Lorsque la colonne d’image est l image principale, vous pouvez définir des données d’image avec d’autres données d’enregistrement à l’aide de create. Pour plus d’informations : Images principales Vous ne pouvez charger de fichiers individuellement dans les propriétés de colonne de fichier qu’après la création de l’enregistrement.
Récupérer avec Retrieve Vous pouvez récupérer des images de la taille d’une vignette avec d’autres données d’enregistrement à l’aide de Retrieve. La valeur retournée est l’ID du fichier. Pour plus d’informations : Comportement lors de la récupération
URL de téléchargement Chaque colonne d’image a une colonne de chaîne qui contient une URL relative que vous pouvez inclure dans une application et qui permet de télécharger le fichier image. Pour plus d’informations : URL de téléchargement Il n’y a pas de colonne de chaîne avec une URL de téléchargement, mais vous pouvez composer une URL pour télécharger le fichier directement à partir de l’API web. Pour plus d’informations : Télécharger un fichier dans une seule requête en utilisant l’API web

Taille d’image maximale

Tout comme les colonnes de fichier, vous pouvez spécifier la taille maximale des données stockées dans une colonne d’image à l’aide de la propriété MaxSizeInKb . Cependant, la taille maximale autorisée est de 30 Mo.

Si vous essayez de charger un fichier trop volumineux, vous obtiendrez l’erreur suivante :

Nom: ProcessImageFailure
Code : 0x80072553
Nombre : -2147015341
Message : Error occured when processing image. Reason: File size is too big. MaxSize: 0 MB, Uploaded filesize: 0 MB.

Vous pouvez utiliser les exemples suivants pour vérifier la taille de fichier maximale :

La méthode statique GetImageColumnMaxSizeInKb suivante renvoie la valeur MaxSizeInKB d’une colonne ImageAttributeMetadata.

/// <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.");
   }
}

Pour plus d’informations :

Types de fichiers image

Les colonnes d’image stockent les types d’images binaires suivants :

Format du fichier Type de l’MIME Extension(s) de fichier
GIF (Graphics Interchange Format) image/gif .gif
Image JPEG (Joint Photographic Expert Group) image/jpeg .jpg, .jpeg
Fichier bitmap image/bmp .bmp
PNG (Portable Network Graphics) image/png .png

Si vous essayez d’enregistrer un fichier qui n’appartient pas à l’un de ces types, vous obtiendrez l’erreur suivante :

Nom: ProcessImageFailure
Code : 0x80072553
Nombre : -2147015341
Message : 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

Images en taille réelle et miniatures

Lorsqu’une valeur de colonne d’image est définie, Dataverse génère automatiquement une image de la taille d’une vignette pouvant être utilisée comme icône dans une application.

Si la colonne d’image est configurée pour stocker une image en taille réelle, un fichier d’une taille maximale de la taille MaxSizeInKb configurée peut être enregistré et téléchargé séparément de l’image miniature. La propriété ImageAttributeMetadata.CanStoreFullImage contrôle si une colonne d’image stockera une image en taille réelle.

Détecter quelles colonnes d’images prennent en charge les images en taille réelle

Vous pouvez interroger la table de configuration des attributs d’image (AttributeImageConfig) pour récupérer une liste de colonnes d’images prenant en charge les images en taille réelle à l’aide des valeurs de colonne parententitylogicalname, attributelogicalname et canstorefullimage.

La méthode statique PrintFullSizedImageColumns écrira les noms des colonnes de table et d’image pouvant stocker des images en taille réelle.

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

Sortie

account.sample_sampleimage

Vous pouvez également interroger les définitions de schéma pour renvoyer les colonnes où la propriété ImageAttributeMetadata.CanStoreFullImage est true. Pour plus d’informations : Interroger les définitions de schéma

Règles de redimensionnement pour les images de la taille d’une vignette

Pour générer une image de la taille d’une vignette, Dataverse recadre et redimensionne l’image selon une forme carrée selon 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
image plus petite avant redimensionnement

91 x 130		 image plus petite après redimensionnement

91 x 91

Images principales

Chaque table peut comporter plusieurs colonnes d’image, mais une seule colonne d’image peut être définie comme image principale. Seule l’image principale peut être définie avec une opération create. Pour plus d’informations : Seules les images principales peuvent être définies pour Create

La Propriété ImageAttributeMetadata.IsPrimaryImage contrôle quelle colonne d’image représente l’image principale pour la table.

La Propriété EntityMetadata.PrimaryImageAttribute renvoie le nom logique de la colonne image qui est l’image principale actuelle de la table.

Vous pouvez également interroger la table de configuration d’image d’entité (EntityImageConfig) pour déterminer quelles colonnes d’image représentent l’image principale actuelle à l’aide des valeurs de colonne parententitylogicalname et primaryimageattribute.

La méthode statique PrintPrimaryImageColumns ci-dessous écrira les noms de colonne de table et d’image de toutes les colonnes d’image principale.

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

Sortie

account.sample_sampleimage

Pour plus d’informations : Générer des requêtes avec QueryExpression

Télécharger URL

Chaque colonne d’image a les colonnes associées suivantes, mais aucune d’entre elles n’apparaît dans le concepteur Power Apps.

Colonne Type Convention d’affectation de noms Description
ID d’image Identificateur unique <image column name>Id Identificateur unique de l’image.
Horodatage BigInt <image column name>_Timestamp Représente la date à laquelle l’image a été mise à jour pour la dernière fois. Cette valeur permet de s’assurer que la dernière version de l’image est téléchargée, au lieu que le client utilise une version mise en cache qui a été récupérée auparavant.
URL string <image column name>_URL URL relative pour télécharger une version miniature de l’image

Les valeurs de colonne d’ID d’image et d’horodatage n’ont aucun cas d’utilisation, sauf qu’elles sont utilisées dans la valeur de colonne de chaîne d’URL.

Lorsque la colonne d’un enregistrement contient des données, l’URL de téléchargement est une URL relative au format suivant :

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

Vous pouvez ajouter cette valeur à l’URI de l’organisation pour créer une URL pouvant être utilisée pour télécharger le fichier image de la taille d’une vignette. Par exemple :

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

URL pour télécharger l’image en taille réelle

Si la colonne d’image est configurée pour stocker des images en taille réelle, vous pouvez ajouter &Full=true à l’URL et le lien téléchargera l’image en taille réelle. Par exemple :

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

Si la colonne n’est pas configurée pour stocker des images en taille réelle, aucune donnée ne sera renvoyée.

Utiliser des données d’image avec des enregistrements

Lorsque vous travaillez avec des enregistrements, la façon dont vous travaillez avec les données d’image dépend du fait que vous utilisez le SDK ou l’API web.

La méthode statique RetrieveAndUpdateImageColumn suivante récupère une valeur d’image byte[] d’une colonne, l’enregistre localement et charge une nouvelle image.

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

Notes

Les colonnes d’image ne sont pas incluses si vous définissez la propriété ColumnSet.AllColumns sur true. Pour des raisons de performances, vous devez spécifier explicitement que vous souhaitez récupérer des données d’image.

Pour plus d’informations :

Seules les images principales peuvent être définies pour Create

Lorsque vous créez un enregistrement, vous ne pouvez définir que la valeur de la colonne d’image principale actuelle. Si vous essayez de définir la valeur d’une autre colonne d’image, vous obtiendrez cette erreur :

Nom: CannotUploadNonPrimaryImageAttributeOnCreate
Code : 0x80090487
Nombre : -2146892665
Message : Non-primary image attribute <image column logical name> of entity <table logical name> is not allowed to upload during Create operation.

Pour plus d’informations : Images principales

Seules les images miniatures peuvent être récupérées

Les données d’image auxquelles vous accédez via les propriétés d’enregistrement seront toujours les images de la taille d’une vignette. Pour accéder aux images en taille réelle, vous devez les télécharger. Pour plus d’informations : Télécharger des images

Charger des images

Utilisez les mêmes API que vous utilisez pour charger des fichiers pour charger des images individuellement. Pour plus d’informations : Charger des fichiers

Télécharger des images

Utilisez les mêmes API que vous utilisez pour télécharger des fichiers pour télécharger des images, mais soyez conscient des différences suivantes.

Utilisation des messages Dataverse

Si vous utilisez les messages InitializeFileBlocksDownload et DownloadBlock , l’image en taille réelle sera toujours téléchargée si la colonne d’image les prend en charge. Vous ne pouvez pas télécharger l’image de la taille d’une vignette en utilisant cette méthode. Pour plus d’informations : Utiliser des messages Dataverse pour télécharger un fichier

Si la colonne d’image ne prend pas en charge les images en taille réelle, ou si la propriété ImageAttributeMetadata.CanStoreFullImage était false lors du chargement de l’image, l’erreur suivante est renvoyée :

Nom: ObjectDoesNotExist
Code : 0x80040217
Nombre : -2147220969
Message : No FileAttachment records found for imagedescriptorId: <guid> for image attribute: <image column logical name> of <entity logical name> record with id <guid>.

Utilisation de l’API web

Lorsque vous téléchargez des images à l’aide de l’API web sans utiliser les messages Dataverse, l’image de la taille d’une vignette sera téléchargée par défaut. Pour télécharger l’image en taille réelle, vous devez ajouter ce paramètre à l’URL : ?size=full.

Si la colonne d’image ne prend pas en charge les images en taille réelle, ou si la propriété ImageAttributeMetadata.CanStoreFullImage était false lors du chargement de l’image, la réponse renverra 204 No Content.

Pour plus d’informations : Télécharger des fichiers

Supprimer des images

Vous pouvez supprimer des images en définissant la valeur de la colonne image pour l’enregistrement sur null, comme vous le feriez pour toute autre propriété.

Définissez simplement la valeur de l’attribut d’image sur null et mettez à jour l’entité. More information: Mise à jour de base

Voir aussi

Vue d’ensemble des fichiers et des images
Utiliser des définitions de colonne d’image avec du code
Exemple : opérations sur les images en utilisant le SDK Dataverse pour .NET
Exemple : opérations sur les images en utilisant l’API web de Dataverse
Utiliser les données de colonne de fichier