Azure Storage blob inventory

Azure Storage blob inventory lists the containers, blobs, blob versions, snapshots, and associated properties in your storage account. The service generates reports daily or weekly in comma-separated values (CSV) or Apache Parquet format.

Use inventory reports to audit the retention, legal hold, or encryption status of your storage account contents. You can also analyze the total size, age, tier distribution, and other attributes of your data.

Blob inventory can simplify business workflows and speed up data processing jobs. It provides scheduled automation of the List Containers and List Blobs APIs. Inventory rules filter report contents by blob type, prefix, or selected blob properties.

Azure Storage blob inventory is available for the following types of storage accounts:

• Standard general-purpose v2
• Premium block blob storage
• Blob storage

Inventory features

Azure Storage blob inventory supports the following features and capabilities.

• Inventory reports for blobs and containers

  You can generate inventory reports for blobs and containers. A report for blobs can contain base blobs, snapshots, content length, blob versions, and their associated properties such as creation time and last modified time. The report doesn't list empty containers. A report for containers describes containers and their associated properties such as immutability policy status and legal hold status.

• Custom schema

  You can choose which fields appear in reports. Choose from a list of supported fields. That list appears later in this article.

• CSV and Apache Parquet output format

  You can generate an inventory report in either CSV or Apache Parquet output format.

• Manifest file and Azure Event Grid event per inventory report

  The service generates a manifest file and an Azure Event Grid event for each inventory report. The article describes these items later.

Enabling inventory reports

Enable blob inventory reports by adding a policy with one or more rules to your storage account. For guidance, see Enable Azure Storage blob inventory reports.

Upgrading an inventory policy

If you configured Azure Storage blob inventory before June 2021, load the policy, make any needed changes, and then save it. When you reload the policy, the service populates the per-rule destination, manifest file, and Azure Event Grid event settings with default values. You can change these values.

• Each rule supports a destination container instead of sharing one destination at the policy level.

• The service generates a manifest file and Azure Event Grid event for each rule instead of for the policy.

Inventory policy

To configure inventory reports, add an inventory policy with one or more rules to a JSON document.

{
  "enabled": true,
  "rules": [
  {
    "enabled": true,
    "name": "inventoryrule1",
    "destination": "inventory-destination-container",
    "definition": {
      "filters": {
        "blobTypes": ["blockBlob"]
      },
      "format": "csv",
      "objectType": "blob",
      "schedule": "daily",
      "schemaFields": ["Name"]
    }
  },
  {
    "enabled": true,
    "name": "inventoryrule2",
    "destination": "inventory-destination-container",
    "definition": {
      "filters": {},
      "format": "csv",
      "objectType": "container",
      "schedule": "weekly",
      "schemaFields": ["Name"]
    }
  }]
}

View the JSON for an inventory policy by selecting the Code view tab in the Blob inventory section of the Azure portal.

Inventory rules

A rule captures the filtering conditions and output parameters for generating an inventory report. Each rule creates an inventory report. Rules can have overlapping prefixes. A blob can appear in more than one inventory depending on rule definitions.

Each rule within the policy has several parameters:

The global Blob inventory enabled flag takes precedence over the enabled parameter in a rule.

Rule definition

Rule filters

Use the following filters to customize a blob inventory report:

View the JSON for inventory rules by selecting the Code view tab in the Blob inventory section of the Azure portal. You specify filters within a rule definition.

{
  "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"
    }
  ]
}

Custom schema fields supported for blob inventory

Field	Blob Storage (default support)	Data Lake Storage
Name (Required)
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
Owner
Group
Permissions
Acl
Snapshot (Available and required when you choose to include snapshots in your report)
Deleted
DeletionId
DeletedTime
RemainingRetentionDays
VersionId (Available and required when you choose to include blob versions in your report)
IsCurrentVersion (Available and required when you choose to include blob versions in your report)
TagCount
Tags
CopyId
CopySource
CopyStatus
CopyProgress
CopyCompletionTime
CopyStatusDescription
ImmutabilityPolicyUntilDate
ImmutabilityPolicyMode
LegalHold
RehydratePriority
ArchiveStatus
EncryptionScope
IncrementalCopy
x-ms-blob-sequence-number

¹ Disabled by default. Optionally enable access time tracking.

Custom schema fields supported for container inventory

Field	Blob Storage (default support)	Data Lake Storage
Name (Required)
Last-Modified
ETag
LeaseStatus
LeaseState
LeaseDuration
Metadata
PublicAccess
DefaultEncryptionScope
DenyEncryptionScopeOverride
HasImmutabilityPolicy
HasLegalHold
ImmutableStorageWithVersioningEnabled
Deleted (Appears only if include deleted containers is selected)
Version (Appears only if include deleted containers is selected)
DeletedTime (Appears only if include deleted containers is selected)
RemainingRetentionDays (Appears only if include deleted containers is selected)

Inventory run

If you configure a rule to run daily, it runs every day. If you configure a rule to run weekly, it runs each Sunday in UTC.

An inventory run can take up to six days before it fails. To learn about factors that affect run time, see Blob inventory performance characteristics.

Runs don't overlap, so a run must complete before another run of the same rule can begin. For example, if the previous day's run of a daily rule is still in progress, the service doesn't initiate a new run that day. Weekly rules run each Sunday regardless of whether a previous run succeeds or fails. If a run doesn't complete successfully, check subsequent runs before contacting support. Run performance can vary, so a subsequent run might complete successfully.

Inventory policies are read or written in full. Partial updates aren't supported. Inventory rules are evaluated daily. If you change a rule definition after the service evaluates the policy for that day, the service evaluates your updates the following day.

Inventory completed event

The BlobInventoryPolicyCompleted event is generated when the inventory run completes for a rule. This event also occurs if the inventory run fails with a user error before it starts to run. For example, an invalid policy or a missing destination container triggers the event. The following JSON shows an example BlobInventoryPolicyCompleted event.

{
  "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.windows.net/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"
}

The following table describes the schema of the BlobInventoryPolicyCompleted event.

Inventory output

Each inventory rule creates a set of files in the specified inventory destination container for that rule. The inventory output is available at the following path: https://<accountName>.blob.core.windows.net/<inventory-destination-container>/YYYY/MM/DD/HH-MM-SS/<ruleName> where:

• accountName is your Azure Blob Storage account name.
• inventory-destination-container is the destination container you specified in the inventory rule.
• YYYY/MM/DD/HH-MM-SS is the time when the inventory started.
• ruleName is the inventory rule name.

Inventory files

Each inventory run for a rule generates the following files:

• Inventory file: An inventory run for a rule generates a CSV or Apache Parquet formatted file. Each such file contains matched objects and their metadata.

  Important

  Inventory runs produce multiple files if the object count is large. To learn more, see Multiple inventory file output FAQ.

  Reports in the Apache Parquet format present dates in the following format: timestamp_millis [number of milliseconds since 1970-01-01 00:00:00 UTC]. For a CSV formatted file, the first row is always the schema row. The following image shows an inventory CSV file opened in Microsoft Excel.

  

  Important

  The blob paths that appear in an inventory file might not appear in any particular order.

• Checksum file: A checksum file contains the MD5 checksum of the contents of the manifest.json file. The name of the checksum file is <ruleName>-manifest.checksum. Generation of the checksum file marks the completion of an inventory rule run.

• Manifest file: A manifest.json file contains the details of the inventory files generated for that rule. The name of the file is <ruleName>-manifest.json. This file also captures the rule definition and the path to the inventory for that rule. The following JSON shows the contents of a sample manifest.json file.

  {
  "destinationContainer" : "inventory-destination-container",
  "endpoint" : "https://testaccount.blob.core.windows.net",
  "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"
  }
  

  This file is created when the run begins. The status field of this file is set to Pending until the run completes. After the run completes, this field is set to a completion status (for example: Succeeded or Failed).

Pricing and billing

Pricing for inventory is based on the number of blobs and containers that you scan during the billing period. The Azure Blob Storage pricing page shows the price per one million objects scanned. For example, if the price to scan one million objects is $0.003, your account contains three million objects, and you produce four reports in a month, then your bill would be 4 * 3 * $0.003 = $0.036.

After you create inventory files, you incur additional standard data storage and operations charges for storing, reading, and writing the inventory-generated files in the account.

If a rule contains a prefix that overlaps with a prefix of any other rule, the same blob can appear in more than one inventory report. In this case, you pay for both instances. For example, assume that the prefixMatch element of one rule is set to ["inventory-blob-1", "inventory-blob-2"], and the prefixMatch element of another rule is set to ["inventory-blob-10", "inventory-blob-20"]. An object named inventory-blob-200 appears in both inventory reports.

Snapshots and versions of a blob also count towards billing even if you set includeSnapshots and includeBlobVersions filters to false. Those filter values don't affect billing. You can use them only to filter what appears in the report.

For more information about pricing for Azure Storage blob inventory, see Azure Blob Storage pricing.

Feature support

Support for this feature might be impacted by enabling Data Lake Storage Gen2, Network File System (NFS) 3.0 protocol, or the SSH File Transfer Protocol (SFTP). If you've enabled any of these capabilities, see Blob Storage feature support in Azure Storage accounts to assess support for this feature.

Known issues and limitations

This section describes limitations and known issues of the Azure Storage blob inventory feature.

Inventory report object count and data size shouldn't be compared to billing

An inventory report doesn't include metadata, system logs, and properties, so don't compare it to the billed object count and data size for the storage account.

Inventory jobs take longer to complete in certain cases

An inventory job can take longer in these cases:

• You add a large amount of new data.

• You run a rule or set of rules for the first time.

  The inventory run might take longer than subsequent runs.

• An inventory run processes a large amount of data in hierarchical namespace-enabled accounts.

  An inventory job might take more than one day to complete for hierarchical namespace-enabled accounts that have hundreds of millions of blobs. Sometimes the inventory job fails and doesn't create an inventory file. If a job doesn't complete successfully, check subsequent jobs to see if they're complete before contacting support.

• There's no option to generate a report retrospectively for a particular date.

Inventory jobs can't write reports to containers that have an object replication policy

An object replication policy can prevent an inventory job from writing inventory reports to the destination container. Some other scenarios can archive the reports or make the reports immutable when they're partially completed, which can cause inventory jobs to fail.

Inventory and immutable storage

You can't configure an inventory policy in the account if support for version-level immutability is enabled on that account, or if support for version-level immutability is enabled on the destination container that you define in the inventory policy.

Reports might exclude soft-deleted blobs in accounts that have a hierarchical namespace

If you delete a container or directory when soft delete is enabled, the service marks it and all its contents as soft-deleted. However, only the container or directory, reported as a zero-length blob, appears in an inventory report. The report doesn't include soft-deleted child blobs even if you set the policy's includeDeleted field to true. This behavior can create a difference between capacity metrics in the Azure portal and the inventory report.

Only blobs that you explicitly delete appear in reports. To obtain a complete listing of all soft-deleted blobs (directory and all child blobs), workloads should delete each blob in a directory before deleting the directory itself.

Handle duplicates in blob inventory

Blob Inventory operates on a distributed system, which means that in rare cases, duplicate blob entries might appear in your reports.

If your use case requires unique blob entries when you postprocess an inventory report, use the Name field to return only unique blobs.

If your report includes blob versions, use both the Name and Version ID fields together to identify and return only the unique blobs and versions.

Next steps

• Enable Azure Storage blob inventory reports
• Calculate the count and total size of blobs per container
• Tutorial: Analyze blob inventory reports
• Manage the Azure Blob Storage lifecycle
• Blob inventory FAQ