Partager via

Utiliser des données de colonne d’image dans Microsoft Dataverse

Vous pouvez stocker des données d’image dans Microsoft Dataverse à l’aide de colonnes d’images ou de colonnes de fichier. Les colonnes d’images dans Dataverse ont des comportements et des limitations spéciaux conçus pour prendre en charge l’affichage d’images dans les applications, et vous pouvez utiliser plusieurs des mêmes API pour les colonnes de fichiers avec des colonnes d’image.

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

Image Fichier
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.BlockedAttachments. 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 Mise à jour 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 format vignette avec d’autres données d’enregistrement en utilisant la fonction de récupération. 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 MaxSizeInKb propriété. Toutefois, la taille maximale autorisée est de 30 Mo.

Si vous essayez de charger un fichier trop volumineux, vous obtenez le message d’erreur suivant :

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.

Pour vérifier la taille maximale du fichier, utilisez les exemples suivants :

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 Extensions 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’est pas l’un de ces types, vous obtenez le message d’erreur suivant :

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

Lorsque vous définissez une valeur de colonne d’image, Dataverse génère automatiquement une image de taille miniature qui convient à une utilisation en tant qu’icône dans une application.

Si vous configurez la colonne d’image pour stocker une image de taille complète, vous pouvez enregistrer et télécharger un fichier jusqu’à l’image configurée MaxSizeInKb séparément de l’image de taille miniature. La propriété ImageAttributeMetadata.CanStoreFullImage contrôle si une colonne d’image stocke une image de taille complète.

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

Vous pouvez interroger la table Configuration d’attributs d’image (AttributeImageConfig) pour récupérer une liste de colonnes d’images qui prennent en charge des images de taille complète en utilisant les valeurs des colonnes parententitylogicalname, attributelogicalname, et canstorefullimage.

La méthode statique PrintFullSizedImageColumns écrit les noms des colonnes de table et d’image qui peuvent stocker des images de taille complète.

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 des définitions de schéma pour retourner des colonnes où la propriété ImageAttributeMetadata.CanStoreFullImage est vraie. Pour plus d’informations, consultez Définitions de schéma de requête.

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

Pour générer une image de taille miniature, Dataverse rogne et redimensionne l’image en une forme carrée en fonction des règles suivantes :

  • Si au moins un côté de l’image est supérieur à 144 pixels, Dataverse rogne l’image sur le centre à 144 x 144 pixels.
  • Si les deux côtés de l’image sont inférieurs à 144 pixels, Dataverse rogne le carré de l’image sur le côté le plus petit.

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 avoir plusieurs colonnes d’image, mais vous ne pouvez définir qu’une seule colonne d’image comme image principale. Vous ne pouvez définir l’image principale qu’à l’aide d’une opération de création. Pour plus d’informations, consultez Définir uniquement les images principales pour l’opération de création.

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 Entity Image Configuration (EntityImageConfig) pour déterminer les colonnes d’image qui représentent l’image primaire actuelle à l’aide des parententitylogicalname valeurs et primaryimageattribute valeurs de colonne.

La méthode statique PrintPrimaryImageColumns de l’exemple suivant écrit les noms de colonnes de table et d’image pour toutes les colonnes d’image primaires.

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 qui utilise le 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 construire une URL que vous pouvez utiliser pour télécharger le fichier image de taille miniature. 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 de taille complète, vous pouvez ajouter &Full=true à l’URL et le lien télécharge l’image de taille complète. 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 de taille complète, la requête ne retourne aucune donnée.

Utiliser des données d’image avec des enregistrements

Lorsque vous travaillez avec des enregistrements, la façon dont vous gérez les données d’image dépend de l’utilisation du Kit de développement logiciel (SDK) ou de l’API web.

La méthode statique RetrieveAndUpdateImageColumn suivante récupère une valeur d’image byte[] à partir 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);               
}

Note

Si vous définissez la propriété ColumnSet.AllColumns sur true, la requête n’inclut pas de colonnes d’image. 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 :

Définir uniquement les images principales pour l’opération de création

Lorsque vous créez un enregistrement, définissez uniquement la valeur de la colonne d’image principale actuelle. Si vous essayez de définir la valeur d’une autre colonne d’image, vous obtenez ce message d’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, consultez Images principales.

Récupérer uniquement des images miniatures

Les données d’image que vous accédez via les propriétés d’enregistrement sont toujours les images de taille miniature. Pour accéder aux images en taille réelle, vous devez les télécharger. Pour plus d’informations, consultez Télécharger des images.

Charger des images

Pour charger des images, utilisez les mêmes API que celles que vous utilisez pour charger des fichiers. Pour plus d’informations, consultez Charger des fichiers.

Télécharger des images

Pour télécharger des images, utilisez les mêmes API que celles que vous utilisez pour télécharger des fichiers. Tenez compte des différences suivantes.

Utilisation des messages Dataverse

Si vous utilisez les messages InitializeFileBlocksDownload et DownloadBlock, vous téléchargez toujours l’image de taille complète si la colonne d’image la prend en charge. Vous ne pouvez pas télécharger l’image de taille miniature à l’aide de cette méthode. Pour plus d’informations, consultez Utiliser les messages Dataverse pour télécharger un fichier.

Si la colonne d’image ne prend pas en charge les images de taille complète ou si la propriété ImageAttributeMetadata.CanStoreFullImage est false lorsque vous chargez l’image, l’erreur suivante est retourné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, vous téléchargez l’image de taille miniature par défaut. Pour télécharger l’image de taille complète, ajoutez ce paramètre à l’URL : ?size=full.

Si la colonne d’image ne prend pas en charge les images de taille complète ou si la propriété ImageAttributeMetadata.CanStoreFullImage est false lorsque vous chargez l’image, la réponse renvoie 204 No Content.

Pour plus d’informations, consultez 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 la valeur de l’attribut image sur Null et mettez à jour l’entité. Pour plus d’informations, voir 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

  • Last updated on