Get Blob Service Stats

Article
11/07/2023

The Get Blob Service Stats operation retrieves statistics that are related to replication for Azure Blob Storage. The operation is available only on the secondary location endpoint when read-access geo-redundant replication is enabled for the storage account.

Request

You can construct the Get Blob Service Stats request as follows. We recommend that you use HTTPS. Replace myaccount with the name of your storage account, and note that the -secondary suffix is required:

Method	Request URI	HTTP version
GET	`https://myaccount-secondary.blob.core.windows.net/?restype=service&comp=stats`	HTTP/1.1

Note

The URI must always include a slash (/) to separate the host name from the path and query portions. In the case of this operation, the path portion of the URI is empty.

URI parameters

You can specify the following additional parameters on the request URI:

Parameter	Description
`Timeout`	Optional. The `timeout` parameter is expressed in seconds.

Request headers

The following table describes required and optional request headers.

Request header	Description
`Authorization`	Required. Specifies the authorization scheme, account name, and signature. For more information, see Authorize requests to Azure Storage.
`Date or x-ms-date`	Required. Specifies the Coordinated Universal Time (UTC) for the request. For more information, see Authorize requests to Azure Storage.
`x-ms-version`	Required for all authorized requests. Specifies the version of the operation to use for this request. For more information, see Versioning for the Azure Storage services.
`x-ms-client-request-id`	Optional. Provides a client-generated, opaque value with a 1-kibibyte (KiB) character limit that's recorded in the logs when logging is configured. We highly recommend that you use this header to correlate client-side activities with requests that the server receives. For more information, see Monitor Azure Blob Storage.

Request body

None.

Response

The response includes an HTTP status code, a set of response headers, and a response body

Status code

A successful operation returns status code 200 (OK). When an operation is called on a secondary location endpoint that's not enabled for a secondary read, it returns an HTTP status code of 403 with an InsufficientAccountPermissions error.

Response headers

The response for this operation includes the following headers. The response also includes additional standard HTTP headers. All standard headers conform to the HTTP/1.1 protocol specification.

Response header	Description
`x-ms-request-id`	Uniquely identifies the request that was made, and you can use it to troubleshoot the request. For more information, see Troubleshoot API operations.
`x-ms-version`	Specifies the version of the operation that's used for the response. For more information, see Versioning for the Azure Storage services.
`Date`	A UTC date/time value that's generated by the service, which indicates the time when the response was initiated.
`x-ms-client-request-id`	Can be used to troubleshoot requests and their corresponding responses. The value of this header is equal to the value of the `x-ms-client-request-id` header if it's present in the request and the value no more than 1,024 visible ASCII characters. If the `x-ms-client-request-id` header isn't present in the request, this header isn't present in the response.

Response body

The format of the response body is as follows:

<?xml version="1.0" encoding="utf-8"?>  
<StorageServiceStats>  
  <GeoReplication>        
      <Status>live|bootstrap|unavailable</Status>  
      <LastSyncTime>sync-time|<empty></LastSyncTime>  
  </GeoReplication>  
</StorageServiceStats>

The elements of the response body are described in the following table:

Response header Description

Status The status of the secondary location. Possible values are:

- live: Indicates that the secondary location is active and operational.
- bootstrap: Indicates that the initial synchronization from the primary location to the secondary location is in progress. This ordinarily occurs when replication is first enabled.
- unavailable: Indicates that the secondary location is temporarily unavailable.

LastSyncTime A GMT date/time value, to the second. All primary writes that precede this value are guaranteed to be available for read operations at the secondary. Primary writes after this point in time might or might not be available for reads.

The value might be empty if LastSyncTime is unavailable. This can happen if the replication status is bootstrap or unavailable.

Although geo-replication is continuously enabled, the LastSyncTime result might reflect a cached value from the service, which is refreshed every few minutes.

Response header	Description
`Status`	The status of the secondary location. Possible values are: - `live`: Indicates that the secondary location is active and operational. - `bootstrap`: Indicates that the initial synchronization from the primary location to the secondary location is in progress. This ordinarily occurs when replication is first enabled. - unavailable: Indicates that the secondary location is temporarily unavailable.
`LastSyncTime`	A GMT date/time value, to the second. All primary writes that precede this value are guaranteed to be available for read operations at the secondary. Primary writes after this point in time might or might not be available for reads. The value might be empty if `LastSyncTime` is unavailable. This can happen if the replication status is `bootstrap` or `unavailable`. Although geo-replication is continuously enabled, the `LastSyncTime` result might reflect a cached value from the service, which is refreshed every few minutes.

Authorization

Authorization is required when calling any data access operation in Azure Storage. You can authorize the Get Blob Service Stats operation as described below.

Azure Storage supports using Microsoft Entra ID to authorize requests to blob data. With Microsoft Entra ID, you can use Azure role-based access control (Azure RBAC) to grant permissions to a security principal. The security principal may be a user, group, application service principal, or Azure managed identity. The security principal is authenticated by Microsoft Entra ID to return an OAuth 2.0 token. The token can then be used to authorize a request against the Blob service.

To learn more about authorization using Microsoft Entra ID, see Authorize access to blobs using Microsoft Entra ID.

Permissions

Listed below are the RBAC action necessary for a Microsoft Entra user, group, or service principal to call the Get Blob Service Stats operation, and the least privileged built-in Azure RBAC role that includes this action:

Azure RBAC action: Microsoft.Storage/storageAccounts/blobServices/read
Least privileged built-in role: Storage Account Contributor

To learn more about assigning roles using Azure RBAC, see Assign an Azure role for access to blob data.

A shared access signature (SAS) provides secure delegated access to resources in a storage account. With a SAS, you have granular control over how a client can access data. You can specify what resource the client may access, what permissions they have to those resources, and how long the SAS is valid.

The Get Blob Service Stats operation supports authorization using an account SAS.

When Shared Key access is disallowed for the storage account, an account SAS token will not be permitted on a request to Blob Storage. To learn more, see Understand how disallowing Shared Key affects SAS tokens.

Account SAS

An account SAS is secured with the storage account key. An account SAS delegates access to resources in one or more of the storage services. All of the operations available via a service or user delegation SAS are also available via an account SAS.

The following table indicates the signed resource type and signed permissions to specify when delegating access:

Operation	Signed service	Signed resource type	Signed permission
Get Blob Service Stats	Blob (b)	Service (s)	Read (r)

To learn more about the account SAS, see Create an account SAS.

Remarks

With geo-redundant replication, Azure Storage maintains your data durably in two locations that are hundreds of miles apart. In both locations, Azure Storage constantly maintains multiple healthy replicas of your data.

A geo-redundant pair includes:

A Primary location: The location where you read, create, update, or delete data. The primary location exists in the region that you choose when you create an account via the Azure classic portal (for example, North Central US).
A Secondary location: The location to which your data is replicated. The secondary location resides in a region that's automatically geographically paired with the primary region. Read-only access is available from the secondary location if read-access geo-redundant replication is enabled for your storage account. For more information about read-access geo-redundant replication, see Data redundancy.

The location where you read, create, update, or delete data is the primary storage account location. The primary location exists in the region you choose at the time you create an account via the Azure Management Azure classic portal, for example, North Central US. The location to which your data is replicated is the secondary location. The secondary location resides in a region that is automatically geographically paired with the primary region. Read-only access is available from the secondary location, if read-access geo-redundant replication is enabled for your storage account. For more details about read-access geo-redundant replication, see Data redundancy.

To construct a request for a read operation against the secondary endpoint, append -secondary to the account name in the URI that you use to read from Blob Storage. For example, a secondary URI for the Get Blob operation will be similar to https://myaccount-secondary.blob.core.windows.net/mycontainer/myblob.

Billing

Pricing requests can originate from clients that use Blob Storage APIs, either directly through the Blob Storage REST API, or from an Azure Storage client library. These requests accrue charges per transaction. The type of transaction affects how the account is charged. For example, read transactions accrue to a different billing category than write transactions. The following table shows the billing category for Get Blob Service Stats requests based on the storage account type:

Operation	Storage account type	Billing category
Get Blob Service Stats	Premium block blob Standard general-purpose v2	Other operations
Get Blob Service Stats	Standard general-purpose v1	Read operations

To learn about pricing for the specified billing category, see Azure Blob Storage Pricing.

Sample request and response

Here is a sample request for the Get Blob Service Stats operation:

GET http://myaccount-secondary.blob.core.windows.net/?restype=service&comp=stats HTTP/1.1

The request is sent with the following headers:

x-ms-version: 2013-08-15  
x-ms-date: Wed, 23 Oct 2013 22:08:44 GMT  
Authorization: SharedKey myaccount:CY1OP3O3jGFpYFbTCBimLn0Xov0vt0khH/E5Gy0fXvg=

The status code and response headers are returned as follows:

HTTP/1.1 200 OK  
Content-Type: application/xml  
Date: Wed, 23 Oct 2013 22:08:54 GMT  
x-ms-version: 2013-08-15  
x-ms-request-id: cb939a31-0cc6-49bb-9fe5-3327691f2a30  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0

The response includes the following XML body:

<?xml version="1.0" encoding="utf-8"?>  
<StorageServiceStats>  
  <GeoReplication>  
      <Status>live</Status>  
      <LastSyncTime> Wed, 23 Oct 2013 22:05:54 GMT</LastSyncTime>        
  </GeoReplication>  
</StorageServiceStats>