Columnas imagen

Artigo
07/06/2022
3 minutos de lectura

Algunas tablas del sistema y todas las entidades personalizadas admiten imágenes. Las tablas que admiten imágenes pueden contener tanto una miniatura como una imagen principal de tamaño completo. La imagen en miniatura se puede ver en la aplicación web al ver los datos del formulario. Puede haber varias columnas de imágenes en una tabla, pero solo puede haber una imagen principal. Sin embargo, puede cambiar la imagen primaria de una imagen a otra estableciendo IsPrimaryImage para esa columna en true. Cada columna de imagen de tamaño completo está limitada a 30 MB de tamaño. El SchemaName de la columna de imagen de la entidad es EntityImage.

Nota

¿No está seguro de entidad frente a tabla? Vea Desarrolladores: comprender la terminología en Microsoft Dataverse.

Las imágenes en miniatura y los metadatos de las imágenes se almacenan en Microsoft Dataverse, que incluye la información necesaria para recuperar la imagen completa. Las imágenes completas se almacenan en el almacenamiento de archivos en el blob de Azure para reducir el consumo de almacenamiento de datos.

API Web	SDK para .NET
ImageAttributeMetadata	ImageAttributeMetadata
`IsPrimaryImage`, `MaxHeight`, `MaxWidth`	IsPrimaryImage, MaxHeight, MaxWidth

Además de las columnas de imagen, las tablas personalizadas admiten cero o más columnas de archivo que pueden contener cualquier dato de archivos. Estas columnas de archivos pueden contener una cantidad de datos mucho mayor que las columnas de imágenes. Para más información, conute Columnas de archivos.

Nota

La capacidad de almacenar más de una columna de imagen en una tabla, el almacenamiento de datos de imagen en un blob de Azure, un tamaño de imagen máximo de 30 MB y las columnas de archivo son compatibles con SdkClientVersion, vesión 9.0.45.329 o superior, y Web API, versión 9.1 o superior.

Columnas de apoyo

Cuando se agrega una columna de imagen a una tabla, se crean algunas columnas adicionales para respaldarla.

EntityImage_Timestamp column

Nombre del tipo de atributo: BigIntType

El EntityImage_Timestamp value representa el momento en que la imagen se actualizó por última vez y se usa para asegurarse de que la versión más reciente de la imagen se descarga y se almacena en caché en el cliente.

EntityImage_URL column

Nombre del tipo de atributo: StringType

Dirección URL absoluta para mostrar la imagen de la entidad en un cliente.

El valor de la columna EntityImage_URL es una dirección URL se compone así:

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

0: la URL de la organización
1: nombre lógico de la tabla
2: nombre lógico de la columna
3: el EntityImageId value.
4: el EntityImage_Timestamp value

Por ejemplo:

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

EntityImageId

Nombre del tipo de atributo: UniqueIdentifierType

El identificador único de la imagen.

Columna MaxSizeInKB

Este valor representa el tamaño máximo (en kilobytes) de los datos de imagen que puede contener la columna. Establezca este valor en el tamaño de datos más pequeño que pueda usar para su aplicación específica. Vea MaxSizeInKB property para el límite de tamaño permisible y el valor predeterminado.

Nota

MaxSizeInKB se establece cuando la columna Imagen se agrega a una tabla. Esto no se puede cambiar después de establecerse.

Columna CanStoreFullImage

El CanStoreFullImage value indica si una columna de imagen puede almacenar una imagen completa. Vea CanStoreFullImage property.

Recuperar datos de imagen

Para descargar datos de columnas de imágenes en miniatura, utilice las siguientes API.

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

Nota

Cuando use RetrieveMultiple o Retrieve, EntityImage no se incluirá cuando la propiedad ColumnSet.AllColumns se ajuste en true. Debido al tamaño que pueden alcanzar los datos en esta columna, para devolver esta columna debe solicitarlo explícitamente.

Las transferencias de datos de imagen desde extremos de servicio web están limitadas a un máximo de 16 MB de datos en una sola llamada de servicio. Los datos de imagen más grandes que la cantidad se deben dividir en bloques de datos de 4 MB o más pequeños (fragmentos) donde cada bloque se recibe en una llamada API independiente hasta que se hayan recibido todos los datos de imagen. Es responsabilidad suya unir los bloques de datos descargados para formar la imagen completa combinando los bloques de datos en la misma secuencia en que se recibieron.

Para más información sobre fragmentación: Columnas de archivos.

Para descargar todos los datos de la columna de imagen, utilice las siguientes API.

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

Tenga en cuenta que, en este caso, la descarga de la columna de imagen utiliza las solicitudes de mensajes de la columna de archivo.

Ejemplo: descarga de miniatura REST

Solicitud

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

Headers:
Content-Type: application/octet-stream

Respuesta

204 No Content

Body:
byte[]

Ejemplo: Descarga de imagen completa REST (<=16MB)

Solicitud

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

Headers:
Content-Type: application/octet-stream

Respuesta

204 No Content

Body:
byte[]

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

En el ejemplo anterior, el parámetro de cadena de consulta size=full indica descargar la imagen completa. El nombre de archivo y el tamaño se proporcionarán en los encabezados de respuesta.

Ejemplo: Descarga de imagen completa REST (>16MB)

Solicitud

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

Header:
Range: bytes=0-1023/8192

Respuesta

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

En el ejemplo anterior, el encabezado Intervalo indica la primera descarga en fragmentos de 1024 bytes para una imagen que tiene 8192 bytes en total.

Carga de datos de imagen

Para actualizar las imágenes, establezca el valor de la columna de imagen en una matriz de bytes que contenga el archivo de imagen. Las imágenes en miniatura se recortan y ajustan de tamaño en un cuadrado de 144x144 píxeles por el servicio web para reducir el tamaño de los datos antes de guardarlos. La reducción de tamaño sigue estas 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
300x428	144x144
91x130	91x91

Las imágenes se pueden cargar en su totalidad hasta el tamaño máximo configurado, o en fragmentos.

Nota

A partir de la fecha de publicación de este artículo, se eliminó la restricción de usar la carga fragmentada para imágenes de más de 16 MB. Las API de fragmentación seguirán estando disponibles para mantener la compatibilidad con las soluciones existentes.

Para cargar datos de imagen completos en una sola llamada, use las siguientes API.

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

Ejemplo: Carga de imagen completa REST

Solicitud

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

Una vez completada la carga, una imagen en miniatura es creada automáticamente por el servicio web.

Si su código utiliza el método heredado, las transferencias de datos de imágenes desde los puntos finales del servicio web están limitadas a un máximo de 16 MB de datos en una sola llamada de servicio. Los datos de imagen de 16 MB o más deben dividirse en bloques de datos de 4 MB o más pequeños (fragmentos) donde cada bloque se carga en una llamada API separada hasta que se hayan recibido todos los datos de imagen. Es su responsabilidad dividir los datos de imagen en bloques de hasta 4MB de tamaño y cargarlos en la secuencia correcta.

Para más información sobre fragmentación: Columnas de archivos.

Para usar la fragmentación heredada para cargar datos de imágenes de más de 16 MB de tamaño, use las siguientes API.

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

Ejemplo: Carga REST con fragmentación

Primera solicitud

Solicitud

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

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

Respuesta

Response:
200 OK

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

En el ejemplo anterior, el encabezado x-ms-transfer-mode: chunked indica una carga fragmentada.

Siguiente solicitud

Solicitud

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

Respuesta

204 No Content

En la solicitud anterior, el siguiente bloque de datos está siendo cargado. Después de que todos los datos de imagen han sido recibidos por el servicio web, una imagen en miniatura es creada automáticamente por el servicio web.

Consulte también

Columnas de archivo
Definiciones de tabla en Microsoft Dataverse
Definiciones de columnas
Ejemplo: establecer y recuperar imágenes de entidad

Nota

¿Puede indicarnos sus preferencias de idioma de documentación? Realice una breve encuesta. (tenga en cuenta que esta encuesta está en inglés)

La encuesta durará unos siete minutos. No se recopilan datos personales (declaración de privacidad).

Columnas imagen

Columnas de apoyo

EntityImage_Timestamp column

EntityImage_URL column

EntityImageId

Columna MaxSizeInKB

Columna CanStoreFullImage

Recuperar datos de imagen

Ejemplo: descarga de miniatura REST

Ejemplo: Descarga de imagen completa REST (<=16MB)

Ejemplo: Descarga de imagen completa REST (>16MB)

Carga de datos de imagen

Ejemplo: Carga de imagen completa REST

Ejemplo: Carga REST con fragmentación

Primera solicitud

Siguiente solicitud

Consulte también

Comentarios