Usar dados de coluna de imagem no Microsoft Dataverse

Você pode armazenar dados de imagem em Microsoft Dataverse usando colunas de imagem ou colunas de arquivo. As colunas de imagem no Dataverse têm comportamentos especiais e limitações que dão suporte à exibição de imagens em aplicativos. Você pode usar muitas das mesmas APIs para colunas de arquivo e colunas de imagem.

A tabela a seguir apresenta algumas das diferenças entre colunas de imagem e arquivo.

Imagem Arquivo
File Size. Limitado a 30 MB. Até 10 GB. Embora a API possa manipular arquivos de até 10 GB de tamanho, os controles de cliente do Power Apps atualmente só dão suporte a arquivos de até 128 MB. Exceder o valor de 128 MB ao usar esses controles resulta em erros ao carregar ou baixar arquivos.
Tipos de arquivo Somente tipos de arquivo de imagem Todos os tipos de arquivo permitidos pelo valor Organization.BlockedAttachments. Mais informações: bloquear determinados tipos de arquivos
Configurar com Atualização Você pode definir dados da coluna de imagem com outros dados de registro por meio de uma atualização. Você só pode carregar arquivos individualmente nas propriedades da coluna de arquivo.
Excluir através de Atualização Você pode excluir dados da coluna de imagem definindo o atributo ou a propriedade como null e, em seguida, atualizando o registro. Mais informações: Excluir imagens Você só pode excluir dados da coluna de arquivo usando a DeleteFile mensagem ou enviando uma DELETE solicitação para a coluna específica usando a API Web. Mais informações: Excluir Arquivos
Configurar com Criar Quando a coluna de imagem é a imagem primária, você pode definir dados de imagem com outros dados de registro usando create. Mais informações: Imagens Primárias Você só pode carregar arquivos individualmente nas propriedades da coluna de arquivo depois que o registro é criado.
Retornar com Recuperação Você pode recuperar imagens em miniatura com outros dados de registro usando retrieve. O valor retornado é a ID do arquivo. Mais informações: Comportamento ao recuperar
Baixar URL Cada coluna de imagem tem uma coluna de cadeia de caracteres que contém uma URL relativa que você pode incluir em um aplicativo que permite baixar o arquivo de imagem. Mais informações: Baixar URL Não há nenhuma coluna de cadeia de caracteres com uma URL de download, mas você pode compor uma URL para baixar o arquivo diretamente da API Web. Mais informações: baixar um arquivo em uma única solicitação usando a API Web

Tamanho máximo da imagem

Assim como as colunas de arquivo, você pode especificar o tamanho máximo dos dados armazenados em uma coluna de imagem usando a MaxSizeInKb propriedade. No entanto, o tamanho máximo permitido é de 30 MB.

Se você tentar carregar um arquivo muito grande, receberá a seguinte mensagem de erro:

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

Para verificar o tamanho máximo do arquivo, use os seguintes exemplos:

O método estático GetImageColumnMaxSizeInKb a seguir retorna o valor MaxSizeInKB para a coluna 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.");
   }
}

Mais informações:

Tipos de arquivo de imagem

As colunas de imagem armazenam os seguintes tipos de imagem binária:

Formato de Arquivo tipo de MIME Extensões de arquivo
formato GIF image/gif .gif
Imagem conjunta do Grupo de Especialistas Fotográficos image/jpeg .jpg, .jpeg
Arquivo bitmap image/bmp .bmp
formato PNG image/png .png

Se você tentar salvar um arquivo que não é um desses tipos, você receberá a seguinte mensagem de erro:

Nome: ProcessImageFailure
Código: 0x80072553
Número: -2147015341
Mensagem: Error occurred when processing image. Reason: Update image properties failed for objectid: <id of record>, logicalName: <logical name of table>, attribute: <logical name of image column

Imagens em tamanho real e em miniatura

Quando você define um valor de coluna de imagem, o Dataverse gera automaticamente uma imagem do tamanho de miniatura adequada para uso como um ícone em um aplicativo.

Se você configurar a coluna de imagem para armazenar uma imagem de tamanho completo, poderá salvar e baixar um arquivo até o configurado MaxSizeInKb separadamente da imagem em tamanho de miniatura. A propriedade ImageAttributeMetadata.CanStoreFullImage controla se uma coluna de imagem armazena uma imagem de tamanho completo.

Detectar quais colunas de imagem dão suporte a imagens de tamanho completo

Use a mensagem RetrieveMetadataChanges para consultar definições de esquema e recuperar todas as colunas de imagem. Em seguida, verifique a propriedade ImageAttributeMetadata.CanStoreFullImage para identificar as colunas que dão suporte a imagens de tamanho completo. Para obter mais informações, consulte definições de esquema de consulta.

Note

A mensagem RetrieveMetadataChanges não dá suporte à filtragem na propriedade ImageAttributeMetadata.CanStoreFullImage. Filtre em AttributeMetadata.AttributeTypeName para retornar todas as colunas de imagem e verifique a propriedade CanStoreFullImage nos resultados.

O método estático PrintFullSizedImageColumns usa a RetrieveMetadataChangesRequest classe para gravar os nomes lógicos de tabelas e colunas de imagem que podem armazenar imagens de tamanho completo.

static void PrintFullSizedImageColumns(IOrganizationService service)
{
    EntityQueryExpression query = new()
    {
        Properties = new MetadataPropertiesExpression("LogicalName", "Attributes"),
        AttributeQuery = new AttributeQueryExpression
        {
            Properties = new MetadataPropertiesExpression(
                "LogicalName",
                "CanStoreFullImage"),
            Criteria = new MetadataFilterExpression(LogicalOperator.And)
            {
                Conditions =
                {
                    new MetadataConditionExpression(
                        propertyName: "AttributeTypeName",
                        conditionOperator: MetadataConditionOperator.Equals,
                        value: AttributeTypeDisplayName.ImageType)
                }
            }
        }
    };

    RetrieveMetadataChangesRequest request = new()
    {
        Query = query
    };

    RetrieveMetadataChangesResponse response =
        (RetrieveMetadataChangesResponse)service.Execute(request);

    foreach (EntityMetadata table in response.EntityMetadata)
    {
        foreach (ImageAttributeMetadata imageColumn in table.Attributes)
        {
            if (imageColumn.CanStoreFullImage == true)
            {
                Console.WriteLine($"{table.LogicalName}.{imageColumn.LogicalName}");
            }
        }
    }
}

Saída

account.sample_sampleimage

Regras de redimensionamento para imagens em miniatura

Para gerar uma imagem em miniatura, o Dataverse corta e redimensiona a imagem para uma forma quadrada de acordo com as seguintes regras:

  • Se pelo menos um lado da imagem for maior que 144 pixels, o Dataverse cortará a imagem no centro para 144 x 144 pixels.
  • Se ambos os lados da imagem forem menores que 144 pixels, o Dataverse cortará o quadrado da imagem para o lado menor.

A tabela a seguir mostra dois exemplos.

Antes Após
Captura de tela de uma imagem de 300 x 428 pixels antes que o Dataverse a redimensione para uma miniatura.

300x428		 imagem após redimensionar

144x144
Captura de tela de uma imagem menor de 91 x 130 pixels antes que o Dataverse a corte para um quadrado.

91x130		 redimensionar imagem menor após

91x91

Imagens primárias

Cada tabela pode ter várias colunas de imagem, mas você só pode definir uma coluna de imagem como a imagem primária. Você só pode definir a imagem primária usando uma operação de criação. Para obter mais informações, consulte Definir apenas imagens primárias para a operação de criação.

A propriedade ImageAttributeMetadata.IsPrimaryImage controla qual coluna de imagem representa a imagem primária da tabela.

A propriedade EntityMetadata.PrimaryImageAttribute retorna o nome lógico da coluna de imagem que é a imagem primária atual da tabela.

Você também pode consultar a tabela Entity Image Configuration (EntityImageConfig) para determinar quais colunas de imagem representam a imagem primária atual, usando os valores das colunas parententitylogicalname e primaryimageattribute.

O método estático PrintPrimaryImageColumns no exemplo a seguir grava os nomes de coluna de tabela e imagem para todas as colunas de imagem primária.

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

Saída

account.sample_sampleimage

Mais informações: Criar consultas com QueryExpression

Baixar URL

Cada coluna de imagem tem as seguintes colunas complementares, mas nenhuma delas aparece no designer do Power Apps .

Coluna Tipo Convenção de nomenclatura Description
ID da imagem Identificador exclusivo <image column name>Id Um identificador exclusivo para a imagem.
Carimbo de Data/Hora BigInt <image column name>_Timestamp Representa quando a imagem foi atualizada pela última vez. Esse valor ajuda a garantir que a versão mais recente da imagem seja baixada em vez de o cliente usar uma versão em cache que foi recuperada antes.
URL cadeia <image column name>_URL Uma URL relativa para baixar uma versão em miniatura da imagem

O ID da imagem e os valores da coluna de carimbo de data/hora não têm nenhum caso de uso, exceto quando são utilizados no valor da coluna da cadeia de caracteres de URL.

Quando a coluna de um registro contém dados, a URL de download é uma URL relativa que usa o seguinte formato:

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

Você pode acrescentar esse valor ao URI da organização para construir uma URL que pode ser usada para baixar o arquivo de imagem em miniatura. Por exemplo:

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

URL para baixar imagem de tamanho completo

Se a coluna de imagem estiver configurada para armazenar imagens de tamanho completo, você poderá acrescentar &Full=true à URL e o link baixará a imagem em tamanho completo. Por exemplo:

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

Se a coluna não estiver configurada para armazenar imagens de tamanho completo, a solicitação não retornará dados.

Usar dados de imagem com registros

Quando você trabalha com registros, a maneira como lida com dados de imagem depende se você está usando o SDK ou a API Web.

O método estático RetrieveAndUpdateImageColumn a seguir recupera um byte[] valor de imagem de uma coluna, salva-o localmente e envia uma nova imagem.

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

Se você definir a propriedade ColumnSet.AllColumns como true, a consulta não inclui colunas de imagem. Por motivos de desempenho, você deve especificar explicitamente que deseja recuperar dados de imagem.

Mais informações:

Definir apenas imagens primárias para a operação de criação

Ao criar um registro, defina apenas o valor da coluna de imagem primária atual. Se você tentar definir o valor de qualquer outra coluna de imagem, receberá esta mensagem de erro:

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

Para obter mais informações, consulte Imagens Primárias.

Recuperar apenas imagens em miniatura

Os dados de imagem que você acessa por meio de propriedades de registro são sempre as imagens em miniatura. Para acessar imagens de tamanho completo, você deve baixá-las. Para obter mais informações, consulte Baixar imagens.

Carregar imagens

Para carregar imagens, use as mesmas APIs usadas para carregar arquivos. Para obter mais informações, consulte Carregar Arquivos.

Baixar imagens

Para baixar imagens, use as mesmas APIs usadas para baixar arquivos. Esteja ciente das diferenças a seguir.

Usar mensagens do Dataverse para baixar imagens

Se você usar as mensagens InitializeFileBlocksDownload e DownloadBlock, sempre baixará a imagem de tamanho completo se a coluna de imagem der suporte a isso. Você não pode baixar a imagem em miniatura usando esse método. Para obter mais informações, consulte Usar mensagens do Dataverse para baixar um arquivo.

Se a coluna de imagem não der suporte a imagens de tamanho completo ou se a propriedade ImageAttributeMetadata.CanStoreFullImage for falsa quando você carregar a imagem, o seguinte erro será retornado:

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

Usar a API Web para baixar imagens

Ao baixar imagens usando a API Web sem usar as mensagens do Dataverse, você baixa a imagem em miniatura por padrão. Para baixar a imagem de tamanho completo, acrescente esse parâmetro à URL: ?size=full.

Se a coluna de imagem não der suporte a imagens de tamanho completo ou se a propriedade ImageAttributeMetadata.CanStoreFullImage for falsa quando você carregar a imagem, a resposta retornará 204 No Content.

Para obter mais informações, consulte Baixar Arquivos.

Excluir imagens

Você pode excluir imagens definindo o valor da coluna de imagem para o registro como nulo como faria para qualquer outra propriedade.

Defina o valor do atributo de imagem como nulo e atualize a entidade. Para obter mais informações, consulte a atualização básica.

Consulte também

Visão geral de arquivos e imagens
Trabalhar com definições de coluna de imagem usando código
Exemplo: Operações de imagem usando o SDK do Dataverse para .NET
Exemplo: Operações de imagem usando a API Web do Dataverse
Usar dados da coluna do arquivo

  • Última atualização a