通过

使用图像列数据

可以使用图像列或文件列在 Dataverse 中存储图像数据。 可以将许多 API 用于包含图像列的文件列。 图像列具有一些特殊行为和限制，可支持在应用程序中显示图像。

下表介绍了图像列和文件列之间的一些差异。

图像 File
文件大小 限制为 30 MB。 最多 10 GB。 虽然 API 可以处理大小高达 10 GB 的文件，但 Power Apps 客户端控件目前仅支持高达 128 MB 的文件。 使用这些控件时超过 128 MB 值将导致上传或下载文件时出错。
文件类型 仅 图像文件类型 Organization.BlockedAttachments 值允许的所有文件类型。 详细信息： 阻止某些类型的文件
使用更新进行设置 可以使用更新通过其他记录数据设置图像列数据。 您只能将文件单独上传到文件列属性。
使用更新进行删除 可以通过将属性或特性设置为 null，然后更新记录，来删除图像列的数据。 详细信息： 删除映像 只能使用 DeleteFile 消息删除文件列数据，也可以使用 Web API 向特定列发送 DELETE 请求。 详细信息： 删除文件
使用 Create 设置 当图像列是 主映像时，可以使用 create 设置图像数据和其他记录数据。 详细信息： 主要图像 创建记录后，只能单独将文件上传到文件列属性。
使用检索返回 可以使用检索功能获取缩略图大小的图像和其他记录数据。 返回的值是文件 ID。 详细信息： 检索时的行为
下载 URL 每个图像列都有一个包含相对URL的字符串列，你可以将该URL包含在一个允许下载图像文件的应用程序中。 详细信息： 下载 URL 没有包含下载 URL 的字符串列，但你可以编写 URL 以直接从 Web API 下载文件。 详细信息： 使用 Web API 在单个请求中下载文件

最大图像大小

与文件列一样，可以使用属性指定存储在图像列中 MaxSizeInKb 的最大数据大小。 但是，允许的最大大小为 30 MB。

如果尝试上传过大的文件，将收到以下错误：

名称：ProcessImageFailure
代码：0x80072553
编号： -2147015341
消息：Error occured when processing image. Reason: File size is too big. MaxSize: 0 MB, Uploaded filesize: 0 MB.

可以使用以下示例检查最大文件大小：

以下静态 GetImageColumnMaxSizeInKb 方法返回 MaxSizeInKBImageAttributeMetadata 列的值。

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

详细信息：

图像文件类型

图像列存储以下二进制图像类型：

文件格式 MIME 类型 文件扩展名
图形交换格式 image/gif .gif
联合摄影专家组图像 image/jpeg .jpg、.jpeg
位图文件 image/bmp .bmp
可移植网络图形格式 image/png .png

如果尝试保存不是以下类型之一的文件，将收到以下错误：

名称：ProcessImageFailure
代码：0x80072553
编号： -2147015341
消息：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

全尺寸图像和缩略图尺寸图像

设置图像列值时，Dataverse 将自动生成适合用作应用程序中图标的缩略图大小的图像。

如果图像列配置为存储全尺寸图像，则可以保存一个大小最多为 MaxSizeInKb 的文件，并且该文件可以与缩略图大小的图像分开下载。 ImageAttributeMetadata.CanStoreFullImage 属性控制图像列是否存储完全大小的图像。

检测哪些图像列支持全尺寸图像

可以查询图像属性配置（AttributeImageConfig）表，以检索支持使用parententitylogicalname和attributelogicalnamecanstorefullimage列值的全尺寸图像的图像列列表。

静态 PrintFullSizedImageColumns 方法将写入可存储全尺寸图像的表和图像列的名称。

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

输出

account.sample_sampleimage

还可以查询架构定义以返回 ImageAttributeMetadata.CanStoreFullImage 属性 为 true 的列。 详细信息： 查询架构定义

调整缩略图大小的规则

若要生成缩略图大小的图像，Dataverse 将按照以下规则裁剪图像并将其大小调整为正方形形状：

  • 至少一侧大于 144 像素的图像在中心裁剪为 144x144。
  • 两边小于 144 的图像会裁剪成正方形，尺寸取其较小的边长。

下表显示了两个示例。

之前 在 后
调整大小之前的图像

300x428		 调整大小后的图像

144x144
在之前调整较小的图像大小

91x130		 在以下之后调整较小的图像大小

91x91

主图像

每个表可以有多个图像列，但只能将一个图像列定义为 主映像。 只能通过创建操作来设置主映像。 详细信息： 只能设置用于创建的主映像

ImageAttributeMetadata.IsPrimaryImage 属性控制哪些图像列表示表的主映像。

EntityMetadata.PrimaryImageAttribute 属性返回图像列的逻辑名称，该列是表的当前主映像。

还可以通过查询实体映像配置（EntityImageConfig）表中的parententitylogicalname和primaryimageattribute列值，来确定哪些图像列代表当前的主要映像。

下面的静态 PrintPrimaryImageColumns 方法将写入所有主映像列的表和图像列名称。

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

输出

account.sample_sampleimage

详细信息： 使用 QueryExpression 生成查询

下载 URL

每个图像列都有以下配套列，但它们均未显示在 Power Apps 设计器中。

列 类型 命名约定 说明
图像 ID 唯一标识符 <image column name>Id 图像的唯一标识符。
时间戳 BigInt <image column name>_Timestamp 表示上次更新映像的时间。 此值有助于确保客户端下载的是最新版本的镜像，而不是使用之前缓存的版本。
URL 字符串 <image column name>_URL 用于下载图像缩略图版本的相对 URL

图像 ID 和时间戳列的值除了用于 URL 字符串列外，没有其他用途。

记录的列包含数据时，下载 URL 将是使用以下格式的相对 URL：

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

可以将此值追加到组织 URI，以构造可用于下载缩略图大小的图像文件的 URL。 例如：

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

用于下载完整大小的映像的 URL

如果图像列配置为存储全尺寸图像，则可以追加 &Full=true 到 URL，链接将下载完整大小的图像。 例如：

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

如果未将列配置为存储全尺寸图像，则不会返回任何数据。

将图像数据与记录配合使用

使用记录时，如何处理图像数据取决于使用的是 SDK 还是 Web API。

以下静态 RetrieveAndUpdateImageColumn 方法从列检索 byte[] 图像值，将其保存在本地并上传新图像。

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

注释

如果将 ColumnSet.AllColumns 属性 设置为 true，则不包括图像列。 出于性能原因，必须明确指定要检索图像数据。

详细信息：

只能为创建过程设置主图像

创建记录时，只能设置当前主映像列的值。 如果尝试设置任何其他图像列的值，将收到此错误：

名称：CannotUploadNonPrimaryImageAttributeOnCreate
代码：0x80090487
编号： -2146892665
消息：Non-primary image attribute <image column logical name> of entity <table logical name> is not allowed to upload during Create operation.

详细信息： 主要图像

只能检索缩略图图像

通过记录属性访问的图像数据将始终是缩略图大小的图像。 若要访问完全大小的映像，必须下载它们。 详细信息： 下载映像

上传图像

使用相同的 API 来单独上传图像，就像上传文件一样。 详细信息： 上传文件

下载图片

使用用于下载文件来下载映像的相同 API，但请注意以下差异。

使用 Dataverse 消息

如果使用 InitializeFileBlocksDownload 和 DownloadBlock 消息，如果映像列支持这些图像，则始终下载完整大小的映像。 无法使用此方法下载缩略图大小的图像。 详细信息： 使用 Dataverse 消息下载文件

如果图像列不支持全尺寸图像，或者上传图像时 ImageAttributeMetadata.CanStoreFullImage 属性 为 false，则返回以下错误：

名称：ObjectDoesNotExist
代码：0x80040217
编号： -2147220969
消息：No FileAttachment records found for imagedescriptorId: <guid> for image attribute: <image column logical name> of <entity logical name> record with id <guid>.

使用 Web API

使用 Web API 下载图像而不使用 Dataverse 消息时，默认情况下将下载缩略图大小的图像。 若要下载完整大小的图像，必须将此参数追加到 URL： ?size=full

如果图像列不支持全尺寸图像，或者上传图像时 ImageAttributeMetadata.CanStoreFullImage 属性 为 false，则响应将返回 204 No Content。

详细信息： 下载文件

删除映像

可以通过将记录的图像列值设置为 null 来删除图像，就像对任何其他属性一样。

只需将图像属性的值设置为 null 并更新实体。 详细信息： 基本更新

另请参阅

文件和映像概述
使用代码处理图像列定义
示例：使用 Dataverse SDK for .NET 进行图像操作
示例：使用 Dataverse Web API 进行图像操作
使用文件列数据

  • Last updated on