Usar datos de columna de imagen

  • Artículo

Puede almacenar datos de imagen en Dataverse usando columnas de imagen o columnas de archivo. Puede usar muchas de las API para columnas de archivos con columnas de imágenes. Las columnas de imagen tienen algunos comportamientos y limitaciones especiales para admitir la visualización de imágenes dentro de las aplicaciones.

La siguiente tabla presenta algunas de las diferencias entre las columnas de imagen y archivo.

Imagen Archivo
Tamaño de archivo Limitado a 30 MB. Hasta 10 GB. Si bien la API puede manejar archivos de hasta 10 GB de tamaño, los controles de cliente de Power Apps actualmente solo admiten archivos de hasta 128 MB. Si se excede el valor de 128 MB al usar estos controles, se producirán errores al cargar o descargar archivos.
Tipos de archivos Solo tipos de archivo de imagen Todos los tipos de archivos permitidos por el valor de Organization.BlockedAttachments. Más información: Bloquear ciertos tipos de archivos
Establecer con actualización Puede configurar los datos de la columna de imagen con otros datos de registro mediante la actualización. Solo puede cargar archivos individualmente en las propiedades de la columna de archivo.
Eliminar con actualización Puede eliminar los datos de la columna de imágenes configurando el atributo o la propiedad en null y luego actualice el registro. Más información: Eliminar imágenes Solo puede eliminar los datos de la columna del archivo usando el mensaje DeleteFile o enviando una solicitud DELETE a la columna específica usando la API web. Más información: Eliminar archivos
Establecer con creación Cuando la columna de la imagen es la imagen principal, puede configurar los datos de la imagen con otros datos de registro usando crear. Más información: Imágenes primarias Solo puede cargar archivos individualmente en las propiedades de la columna de archivo después de crearse el registro.
Regresar con recuperación Puede recuperar imágenes del tamaño de una miniatura con otros datos de registro usando recuperar. El valor devuelto es el id. de archivo. Más información: Comportamiento en la recuperación
URL de descarga Cada columna de imagen tiene una columna de cadena que contiene una URL relativa que puede incluir en una aplicación que permite descargar el archivo de imagen. Más información: URL de descarga No hay una columna de cadena con una URL de descarga, pero puede redactar una URL para descargar el archivo directamente desde la API web. Más información: Descargar un archivo en una sola solicitud usando la API web

Tamaño máximo de imagen

Al igual que las columnas de archivo, puede especificar el tamaño máximo de los datos almacenados en una columna de imagen mediante la propiedad MaxSizeInKb. Sin embargo, el tamaño máximo permitido es de 30 MB.

Si intenta cargar un archivo que es demasiado grande, obtendrá el siguiente error:

Nombre: ProcessImageFailure
Código: 0x80072553
Número: -2147015341
Mensaje: Error occured when processing image. Reason: File size is too big. MaxSize: 0 MB, Uploaded filesize: 0 MB.

Puede utilizar los siguientes ejemplos para comprobar el tamaño máximo de archivo:

El siguiente método GetImageColumnMaxSizeInKb devuelve el valor MaxSizeInKB para una columna 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.");
   }
}

Más información:

Tipos de archivo de imagen

Las columnas de imágenes almacenan los siguientes tipos de imágenes binarias:

Formato de archivo Tipo de MIME Extensiones de archivo
Formato de intercambio de gráficos JPEG image/gif .gif
Imagen del Grupo Conjunto de Expertos en Fotografía image/jpeg .jpg, .jpeg
Archivo de mapa de bits image/bmp .bmp
Gráficos de red portátiles image/png .png

Si intenta guardar un archivo que no es uno de estos tipos, recibirá el siguiente error:

Nombre: ProcessImageFailure
Código: 0x80072553
Número: -2147015341
Mensaje: 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

Imágenes en tamaño completo y en miniatura

Cuando se establece un valor de columna de imagen, Dataverse generará automáticamente una imagen en miniatura que es adecuada para usar como icono en una aplicación.

Si la columna de imagen está configurada para almacenar una imagen de tamaño completo, un archivo hasta el MaxSizeInKb configurado se puede guardar y descargar por separado de la imagen en miniatura. La propiedad ImageAttributeMetadata.CanStoreFullImage controla si una columna de imagen almacenará una imagen de tamaño completo.

Detecte qué columnas de imágenes admiten imágenes de tamaño completo

Puedes consultar la tabla de configuración de atributos de imagen (AttributeImageConfig) para recuperar una lista de columnas de imágenes que admiten imágenes de tamaño completo utilizando los valores de columna parententitylogicalname, attributelogicalname y canstorefullimage.

El método estático PrintFullSizedImageColumns escribirá los nombres de las columnas de la tabla y la imagen que pueden almacenar imágenes de tamaño completo.

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

También puede consultar definiciones de esquema para devolver columnas donde la propiedad ImageAttributeMetadata.CanStoreFullImage sea true. Más información: Definiciones de esquema de consulta

Reglas de cambio de tamaño para imágenes en miniatura

Para generar una imagen del tamaño de una miniatura, Dataverse recortará y cambiará el tamaño de la imagen a una forma cuadrada de acuerdo con las siguientes reglas:

  • Las imágenes que tengan al menos un lado de más de 144 píeles se recortan en el centro a 144x144.
  • Las imágenes que tengan ambos lados con menos de 144 píxeles se recortarán con forma de cuadrado cuyo lado coincide con la dimensión más pequeña.

En la siguiente tabla se muestran dos ejemplos.

Antes Después
Imagen antes de cambio de tamaño

300x428		 imagen después de cambiar el tamaño

144x144
imagen antes de cambio de tamaño

91x130		 imagen después del cambio de tamaño

91x91

Imágenes principales

Cada tabla puede tener varias columnas de imagen, pero solo se puede definir una columna de imagen como imagen principal. Solo la imagen principal se puede configurar con una operación de creación. Más información: Solo las imágenes principales se pueden configurar para crear

La propiedad ImageAttributeMetadata.IsPrimaryImage controla qué columna de imagen representa la imagen principal de la tabla.

La propiedad EntityMetadata.PrimaryImageAttribute devuelve el nombre lógico de la columna de imagen que es la imagen principal actual para la tabla.

También puede consultar la tabla de configuración de imagen de entidad (EntityImageConfig) para determinar qué columnas de imagen representan la imagen principal actual usando los valores de columna parententitylogicalname y primaryimageattribute.

El método estático PrintPrimaryImageColumns siguiente escribirá los nombres de las columnas de la tabla y la imagen de todas las columnas de la imagen principal.

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

Más información: Crear consultas con QueryExpression

Descargar URL

Cada columna de imagen tiene las siguientes columnas complementarias, pero ninguna de ellas aparece dentro del diseñador Power Apps.

Columna Type Convención de nomenclatura Descripción
Id. de imagen Identificador único <image column name>Id Un identificador único para la imagen.
Marca de tiempo BigInt <image column name>_Timestamp Representa cuando la imagen se actualizó por última vez. Este valor ayuda a garantizar que se descargue la última versión de la imagen en lugar de que el cliente use una versión en caché que se recuperó antes.
Dirección URL string <image column name>_URL Una URL relativa para descargar una versión en miniatura de la imagen

Los valores de la columna ID de imagen y marca de tiempo no tienen ningún caso de uso, excepto que están acostumbrados dentro del valor de la columna de cadena de URL.

Cuando la columna de un registro contiene datos, la URL de descarga será una URL relativa con el siguiente formato:

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

Puede agregar este valor al URI de la organización para crear una URL que se pueda usar para descargar el archivo de imagen en miniatura. Por ejemplo:

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

URL para descargar la imagen a tamaño completo

Si la columna de imagen está configurada para almacenar imágenes de tamaño completo, puede agregar &Full=true a la URL y el enlace descargará la imagen de tamaño completo. Por ejemplo:

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 columna no está configurada para almacenar imágenes de tamaño completo, no se devolverán datos.

Usar datos de imagen con registros

Cuando trabaja con registros, la forma en que trabaja con los datos de imagen depende de si está utilizando el SDK o la API web.

El siguiente método estático RetrieveAndUpdateImageColumn recupera un valor de imagen byte[] de una columna, lo guarda localmente y carga una nueva imagen.

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

Nota

Las columnas de imágenes no se incluyen si establece la propiedad ColumnSet.AllColumns en verdadero. Por motivos de rendimiento, debe especificar explícitamente que desea recuperar datos de imagen.

Más información:

Solo las imágenes principales se pueden configurar para crear

Cuando crea un registro, solo puede establecer el valor de la columna de imagen principal actual. Si intenta establecer el valor de cualquier otra columna de imagen, obtendrá este error:

Nombre: CannotUploadNonPrimaryImageAttributeOnCreate
Código: 0x80090487
Número: -2146892665
Mensaje: Non-primary image attribute <image column logical name> of entity <table logical name> is not allowed to upload during Create operation.

Más información: Imágenes primarias

Solo se pueden recuperar imágenes en miniatura

Los datos de imagen a los que accede a través de las propiedades de registro siempre serán imágenes en miniatura. Para acceder a las imágenes en tamaño completo, debe descargarlas. Más información: Descargar imágenes

Cargar imágenes

Use las mismas API que usa para cargar archivos para cargar imágenes individualmente. Más información: Cargar archivos

Descargar imágenes

Use las mismas API que usa para descargar archivos para descargar imágenes, pero tenga en cuenta las siguientes diferencias.

Usar mensajes de Dataverse

Si usa los mensajes InitializeFileBlocksDownload y DownloadBlock, la imagen de tamaño completo siempre se descargará si la columna de imagen los admite. No puede descargar la imagen en miniatura con este método. Más información: Usar mensajes de Dataverse para descargar un archivo

Si la columna de la imagen no admite imágenes de tamaño completo, o si la propiedad ImageAttributeMetadata.CanStoreFullImage era falsa cuando se cargó la imagen, se devuelve el siguiente error:

Nombre: ObjectDoesNotExist
Código: 0x80040217
Número: -2147220969
Mensaje: No FileAttachment records found for imagedescriptorId: <guid> for image attribute: <image column logical name> of <entity logical name> record with id <guid>.

Uso de la API web

Cuando descargue imágenes utilizando la API web sin utilizar los mensajes de Dataverse, la imagen en miniatura se descargará de manera predeterminada. Para descargar la imagen a tamaño completo, debe agregar este parámetro a la URL: ?size=full.

Si la columna de la imagen no admite imágenes de tamaño completo, o si la propiedad ImageAttributeMetadata.CanStoreFullImage era falsa cuando se cargó la imagen, la respuesta devolverá 204 No Content.

Más información: Descargar archivos

Eliminar imágenes

Puede eliminar imágenes configurando el valor de la columna de imagen para el registro en nulo como lo haría con cualquier otra propiedad.

Simplemente establezca el valor del atributo de la imagen en nulo y actualice la entidad. Más información: Actualización básica

Consulte también

Información general sobre imágenes y archivos
Trabajar con definiciones de columna de imagen mediante código
Ejemplo: Operaciones de imagen usando la SDK de Dataverse para .NET
Ejemplo: Operaciones de imagen usando la API web de Dataverse
Usar datos de columna de archivo