Azure 存储 Blob 清单

  • 项目

Azure 存储 Blob 清单提供存储帐户中容器、Blob、Blob 版本和快照的列表及其关联属性。 它每天或每周会以逗号分隔值 (CSV) 或 Apache Parquet 格式生成输出报告。 可以使用报表来审核存储帐户内容的保留、法定保留或加密状态，也可以使用它来了解数据的总数据大小、年限、层分布或其他属性。 还可以将 Blob 清单用作列出容器和列出 Blob API 的计划自动化，以使用 Blob 清单来简化业务工作流或加快数据处理作业。 借助 Blob 清单规则，可以按 Blob 类型、前缀或选择要包含在报表中的 Blob 属性来筛选报表的内容。

Azure 存储 blob 清单适用于以下类型的存储帐户：

  • 标准常规用途 v2
  • 高级块 blob 存储
  • Blob 存储

清单功能

以下列表描述了当前版本的 Azure 存储 Blob 清单提供的特性和功能。

  • Blob 和容器的清单报告

    可以生成 Blob 和容器的清单报告。 Blob 的报告可以包含基本 Blob、快照、内容长度、Blob 版本及其关联的属性，例如创建时间和上次修改时间。 blob 清单报表中未列出空容器。 容器的报告描述容器及其关联的属性，例如不可变性策略状态和法定保留状态。

  • 自定义架构

    可以选择要在报告中显示的字段。 从支持的字段列表中进行选择。 本文稍后会提供该列表。

  • CSV 和 Apache Parquet 输出格式

    可以生成 CSV 或 Apache Parquet 输出格式的清单报告。

  • 每份清单报告的清单文件和 Azure 事件网格事件

    将为每份清单报告生成一个清单文件和一个 Azure 事件网格事件。 本文稍后将介绍这些内容。

启用清单报告

通过在存储帐户中添加带有一个或多个规则的策略来启用 Blob 清单报告。 有关指导，请参阅启用 Azure 存储 Blob 清单报告。

升级清单策略

如果你是在 2021 年 6 月之前配置了清单的现有 Azure 存储 Blob 清单用户，可以通过加载策略并在进行更改后重新保存策略，来开始使用新功能。 重载策略时，将使用默认值填充该策略的新字段。 如果需要，可以更改这些值。 此外，还可使用以下两项功能。

  • 现在，每个规则（而不仅仅是策略）都支持目标容器。

  • 现在，会按规则（而不是策略）生成清单文件和 Azure 事件网格事件。

清单策略

清单报表通过使用一个或多个规则添加清单策略来配置。 清单策略是 JSON 文档中规则的集合。

{
  "enabled": true,
  "rules": [
  {
    "enabled": true,
    "name": "inventoryrule1",
    "destination": "inventory-destination-container",
    "definition": {. . .}
  },
  {
    "enabled": true,
    "name": "inventoryrule2",
    "destination": "inventory-destination-container",
    "definition": {. . .}
  }]
}

通过选择 Azure 门户的“Blob 清单”部分中的“代码视图”选项卡，查看清单策略的 JSON 。

参数名称 参数类型 注释 必需？
enabled boolean 用于禁用整个策略。 如果设置为 true，则启用规则级别的字段将重写此参数。 禁用后，将禁用所有规则的清单。 是
规则 规则对象的数组 一个策略至少需要包含一个规则。 每个策略最多支持 100 个规则。 是

清单规则

规则捕获用于生成清单报表的筛选条件和输出参数。 每个规则都会创建一个清单报表。 规则可以有重叠的前缀。 Blob 可以出现在多个清单中，具体取决于规则定义。

策略中的每个规则具有多个参数：

参数名称 参数类型 注释 必需？
name string 规则名称最多只能包含 256 个字母数字字符（区分大小写）。 名称在策略中必须唯一。 是
enabled boolean 允许启用或禁用规则的标志。 默认值为 true。 是
定义 JSON 清单规则定义 每个定义均由规则筛选器集组成。 是
destination 字符串 将在其中生成所有清单文件的目标容器。 目标容器必须已经存在。

全局“已启用 blob 清单”标志优先于规则中的 enabled 参数。

规则定义

参数名称 参数类型 注释 必须
筛选器 json 筛选器确定某个 Blob 或容器是否是清单的一部分。 是
format 字符串 确定清单文件的输出。 有效值为 csv（表示 CSV 格式）和 parquet（表示 Apache Parquet 格式）。 是
objectType string 指示这是适用于 Blob 还是适用于容器的清单规则。 有效值为 blob 和 container。 是
schedule string 运行此规则所依照的计划。 有效值为 daily 和 weekly。 是
schemaFields JSON 数组 作为清单一部分的架构字段的列表。 是

规则筛选器

有多个筛选器可用于自定义 blob 清单报表：

筛选器名称 筛选器类型 注释 必需？
blobTypes 预定义枚举值的数组 对于已启用分层命名空间的帐户，有效值为 blockBlob 和 appendBlob，对于其他帐户，有效值为 blockBlobappendBlob 和 pageBlob。 此字段不适用于容器的清单（objectType：container）。 是
creationTime Number 指定必须已在多少天前创建 blob。 例如，值为 3 时，在报表中仅包含过去 3 天内创建的那些 blob。 否
prefixMatch 要匹配的前缀字符串数组，最多包含 10 个字符串。 如果未定义 prefixMatch 或提供空前缀，规则将应用到存储帐户中的所有 Blob。 前缀必须是容器名称前缀或容器名称。 例如：container、container1/foo。 否
excludePrefix 要排除的前缀字符串数组，最多包含 10 个字符串。 指定要从库存报告中排除的 Blob 路径。

excludePrefix 必须是容器名称前缀或容器名称。 空的 excludePrefix 意味着会列出名称与任何 prefixMatch 字符串匹配的所有 Blob。

如果你想要包含特定的前缀，但要从中排除某个特定的子集，则可以使用 excludePrefix 筛选器。 例如，如果你想包含 container-a 下的所有 Blob，但文件夹 container-a/folder 下的 Blob 除外，则应将 prefixMatch 设置为 container-a，并将 excludePrefix 设置为 container-a/folder。		 否
includeSnapshots boolean 指定清单是否应包含快照。 默认值为 false。 此字段不适用于容器的清单（objectType：container）。 否
includeBlobVersions boolean 指定清单是否应包含 blob 版本。 默认值为 false。 此字段不适用于容器的清单（objectType：container）。 否
includeDeleted boolean 指定清单是否应包含已删除的 Blob。 默认值为 false。 在具有分层命名空间的帐户中，此筛选器包括文件夹以及处于软删除状态的 Blob。

报表中仅显示显式删除的文件夹和文件 (Blob)。 报表中不包括因删除父文件夹而删除的子文件夹和文件。		 否

通过选择 Azure 门户的“Blob 清单”部分中的“代码视图”选项卡，查看清单规则的 JSON 。 筛选器在规则定义中指定。

{
  "destination": "inventory-destination-container",
  "enabled": true,
  "rules": [
  {
    "definition": {
      "filters": {
        "blobTypes": ["blockBlob", "appendBlob", "pageBlob"],
        "prefixMatch": ["inventorytestcontainer1", "inventorytestcontainer2/abcd", "etc"],
        "excludePrefix": ["inventorytestcontainer10", "etc/logs"],
        "includeSnapshots": false,
        "includeBlobVersions": true,
      },
      "format": "csv",
      "objectType": "blob",
      "schedule": "daily",
      "schemaFields": ["Name", "Creation-Time"]
    },
    "enabled": true,
    "name": "blobinventorytest",
    "destination": "inventorydestinationContainer"
  },
  {
    "definition": {
      "filters": {
        "prefixMatch": ["inventorytestcontainer1", "inventorytestcontainer2/abcd", "etc"]
      },
      "format": "csv",
      "objectType": "container",
      "schedule": "weekly",
      "schemaFields": ["Name", "HasImmutabilityPolicy", "HasLegalHold"]
    },
    "enabled": true,
    "name": "containerinventorytest",
    "destination": "inventorydestinationContainer"
    }
  ]
}

Blob 清单支持的自定义架构字段

注意

“Data Lake Storage Gen2”列显示启用了分层命名空间功能的帐户中的支持。

字段 Blob 存储（默认支持） Data Lake Storage Gen2
Name（必填） 是 是
Creation-Time 是 是
Last-Modified 是 是
LastAccessTime1 是 是
ETag 是 是
Content-Length 是 是
Content-Type 是 是
Content-Encoding 是 是
Content-Language 是 是
Content-CRC64 是 是
Content-MD5 是 是
Cache-Control 是 是
Cache-Disposition 是 是
/BlobType 是 是
AccessTier 是 是
AccessTierChangeTime 是 是
LeaseStatus 是 是
LeaseState 是 是
ServerEncrypted 是 是
CustomerProvidedKeySHA256 是 是
Metadata 是 是
Expiry-Time 否 是
hdi_isfolder 否 是
所有者 否 是
组 否 是
权限 否 是
Acl 否 是
Snapshot（在选择将快照包含到报告中时可用且必填） 是 是
Deleted 是 是
DeletedId 否 是
DeletedTime 否 是
RemainingRetentionDays 是 是
VersionId（在选择将 Blob 版本包含到报告中时可用且必填） 是 否
IsCurrentVersion（在选择将 Blob 版本包含到报告中时可用且必填） 是 否
TagCount 是 否
Tags 是 否
CopyId 是 是
CopySource 是 是
CopyStatus 是 是
CopyProgress 是 是
CopyCompletionTime 是 是
CopyStatusDescription 是 是
ImmutabilityPolicyUntilDate 是 是
ImmutabilityPolicyMode 是 是
LegalHold 是 是
RehydratePriority 是 是
ArchiveStatus 是 是
EncryptionScope 是 是
IncrementalCopy 是 是
x-ms-blob-sequence-number 是 否

1默认禁用。 启用访问时间跟踪（可选）。

容器清单支持的自定义架构字段

注意

“Data Lake Storage Gen2”列显示启用了分层命名空间功能的帐户中的支持。

字段 Blob 存储（默认支持） Data Lake Storage Gen2
Name（必填） 是 是
Last-Modified 是 是
ETag 是 是
LeaseStatus 是 是
LeaseState 是 是
LeaseDuration 是 是
Metadata 是 是
PublicAccess 是 是
DefaultEncryptionScope 是 是
DenyEncryptionScopeOverride 是 是
HasImmutabilityPolicy 是 是
HasLegalHold 是 是
ImmutableStorageWithVersioningEnabled 是 是
Deleted（仅当选择了“包括已删除的容器”时才显示） 是 是
Version（仅当选择了“包括已删除的容器”时才显示） 是 是
DeletedTime（仅当选择了“包括已删除的容器”时才显示） 是 是
RemainingRetentionDays（仅当选择了“包括已删除的容器”时才显示） 是 是

清单运行

如果将规则配置为每天运行，该规则会按计划每天运行一次。 如果将规则配置为每周运行，该规则会按计划在每周的星期日（UTC 时间）运行一次。

大多数清单运行在 24 小时内完成。 对于启用了分层命名空间的帐户，运行最长可能需要两天时间，根据要处理的文件数，运行不一定可以在两天内完成。 某个运行在失败之前最多可以有六天时间来完成。

运行不能重叠，因此必须先完成一个运行，然后才能开始同一规则的另一个运行。 例如，如果某个规则计划为每天运行，但前一天的同一规则的运行仍在进行中，则当天不会启动新的运行。 计划每周运行的规则将在每个星期日运行，无论上一次运行是成功还是失败。 如果某个运行未成功完成，请检查后续运行以确定它们是否已完成，然后再联系支持人员。 运行性能可能不同，因此，如果某个运行未完成，后续运行仍可能会完成。

清单策略完全读取或写入。 不支持部分更新。 每天都会评估清单规则。 因此，如果更改规则的定义，但该天已评估了策略的规则，则会等到第二天才会评估更新。

重要

如果为存储帐户启用了防火墙规则，清单请求可能会遭到阻止。 可以通过针对受信任的 Microsoft 服务提供例外来取消阻止这些请求。 有关详细信息，请参阅配置防火墙和虚拟网络中的“例外”部分。

清单已完成事件

针对规则完成清单运行后，将生成 BlobInventoryPolicyCompleted 事件。 如果清单运行由于在开始运行之前出现用户错误而失败，则也会发生此事件。 例如，无效的策略或在目标容器不存在时出现的错误会触发该事件。 以下 JSON 演示了一个示例 BlobInventoryPolicyCompleted 事件。

{
  "topic": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/BlobInventory/providers/Microsoft.EventGrid/topics/BlobInventoryTopic",
  "subject": "BlobDataManagement/BlobInventory",
  "eventType": "Microsoft.Storage.BlobInventoryPolicyCompleted",
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "data": {
    "scheduleDateTime": "2021-05-28T03:50:27Z",
    "accountName": "testaccount",
    "ruleName": "Rule_1",
    "policyRunStatus": "Succeeded",
    "policyRunStatusMessage": "Inventory run succeeded, refer manifest file for inventory details.",
    "policyRunId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "manifestBlobUrl": "https://testaccount.blob.core.chinacloudapi.cn/inventory-destination-container/2021/05/26/13-25-36/Rule_1/Rule_1-manifest.json"
  },
  "dataVersion": "1.0",
  "metadataVersion": "1",
  "eventTime": "2021-05-28T15:03:18Z"
}

下表描述了 BlobInventoryPolicyCompleted 事件的架构。

字段 类型​​ 说明
scheduleDateTime string 计划清单规则的时间。
accountName string 存储帐户名称。
ruleName string 规则名称。
policyRunStatus string 清单运行状态。 可能值为 Succeeded、PartiallySucceeded 和 Failed。
policyRunStatusMessage string 清单运行的状态消息。
policyRunId string 清单运行的策略运行 ID。
manifestBlobUrl string 清单运行的清单文件的 Blob URL。

清单输出

每个清单规则会在该规则的指定清单目标容器中生成一组文件。 清单输出在以下路径下生成：https://<accountName>.blob.core.chinacloudapi.cn/<inventory-destination-container>/YYYY/MM/DD/HH-MM-SS/<ruleName其中：

  • accountName 是你的 Azure Blob 存储帐户名称。
  • inventory-destination-container 是在清单规则中指定的目标容器。
  • YYYY/MM/DD/HH-MM-SS 是清单开始运行的时间。
  • ruleName 是清单规则名称。

清单文件

规则的每个清单运行会生成以下文件：

  • 清单文件：规则的清单运行会生成 CSV 或 Apache Parquet 格式的文件。 每个此类文件包含匹配的对象及其元数据。

    重要

    从 2023 年 10 月开始，如果对象计数较大，清单运行将生成多个文件。 若要了解详细信息，请参阅多个清单文件输出常见问题解答。

    Apache Parquet 格式的报告按照下面的格式显示日期：timestamp_millis [number of milliseconds since 1970-01-01 00:00:00 UTC]。 对于 CSV 格式的文件，第一行始终是架构行。 下图显示了在 Microsoft Excel 中打开的清单 CSV 文件。

    在 Microsoft Excel 中打开的清单 CSV 文件的屏幕截图

    重要

    清单文件中的 Blob 路径可能不按任何特定的顺序显示。

  • 校验和文件：校验和文件包含 manifest.json 文件内容的 MD5 校验和。 校验和文件的名称为 <ruleName>-manifest.checksum。 生成了检验和文件即表示清单规则运行已完成。

  • 清单文件：manifest.json 文件包含针对该规则生成的清单文件的详细信息。 该文件的名称为 <ruleName>-manifest.json。 此文件还会捕获用户提供的规则定义以及该规则的清单的路径。 以下 JSON 演示了一个示例 manifest.json 文件的内容。

    {
"destinationContainer" : "inventory-destination-container",
"endpoint" : "https://testaccount.blob.core.chinacloudapi.cn",
"files" : [
  {
    "blob" : "2021/05/26/13-25-36/Rule_1/Rule_1.csv",
    "size" : 12710092
  }
],
"inventoryCompletionTime" : "2021-05-26T13:35:56Z",
"inventoryStartTime" : "2021-05-26T13:25:36Z",
"ruleDefinition" : {
  "filters" : {
    "blobTypes" : [ "blockBlob" ],
    "includeBlobVersions" : false,
    "includeSnapshots" : false,
    "prefixMatch" : [ "penner-test-container-100003" ]
  },
  "format" : "csv",
  "objectType" : "blob",
  "schedule" : "daily",
  "schemaFields" : [
    "Name",
    "Creation-Time",
    "BlobType",
    "Content-Length",
    "LastAccessTime",
    "Last-Modified",
    "Metadata",
    "AccessTier"
  ]
},
"ruleName" : "Rule_1",
"status" : "Succeeded",
"summary" : {
  "objectCount" : 110000,
  "totalObjectSize" : 23789775
},
"version" : "1.0"
}

    此文件是在运行开始时创建的。 此文件的“status”字段设置为“Pending”，直到运行完成。 运行完成后，该字段将设置为完成状态（例如“Succeeded”或“Failed”）。

功能支持

启用 Data Lake Storage Gen2、网络文件系统 (NFS) 3.0 协议或 SSH 文件传输协议 (SFTP) 可能会影响对此功能的支持。 如果已启用这些功能中的某一项，请参阅 Azure 存储帐户中的 Blob 存储功能支持，以评估对此功能的支持。

已知问题和限制

本部分介绍了 Azure 存储 blob 清单功能的限制和已知问题。

清单作业在某些情况下需要更长时间才能完成

在以下情况下，清单作业可能需要更长的时间：

  • 添加了大量新数据

  • 第一次运行一个规则或一组规则

    与后续清单运行相比，这次清单运行可能需要更长的时间。

  • 库存运行正在处理启用了分层命名空间的帐户中的大量数据

    对于具有数亿个 blob 的已启用分层命名空间的帐户，清单作业可能需要一天以上才能完成。 有时，清单作业会失败，并且不会创建清单文件。 如果某个作业未成功完成，请检查后续作业以确定它们是否已完成，然后再联系支持人员。

  • 没有针对特定日期以可追溯方式生成报表的选项。

清单作业无法将报表写入具有对象复制策略的容器

对象复制策略可能会阻止清单作业将清单报告写入目标容器。 其他一些方案可能会将报表存档，或者在报表完成了一部分时将报表设为不可变，这可能会导致清单作业失败。

清单和不可变存储

如果在帐户上启用了对版本级不可变性的支持，或者在库存策略中定义的目标容器上启用了对版本级不可变性的支持，则无法在该帐户中配置库存策略。

报表可能会排除具有分层命名空间的帐户中的软删除 blob

如果在启用软删除的情况下删除容器或目录，则该容器或目录及其所有内容会被标记为软删除。 但是，即使你将策略的 includeDeleted 字段设置为 true，清单报表中也只会显示容器或目录（报告为零长度 blob），而不会显示该容器或目录中的软删除 blob。 这可能会导致你在 Azure 门户中获取的容量指标中显示的内容与清单报表中报告的内容之间存在差异。

只有显式删除的 blob 才会出现在报表中。 因此，若要获取所有软删除 blob（目录和所有子 blob）的完整列表，工作负荷应先删除目录中的每个 blob，然后再删除目录本身。

后续步骤