Lote de Blobs

  • Artigo

A Blob Batch operação permite que várias chamadas à API sejam inseridas em uma única solicitação HTTP. Essa API dá suporte a dois tipos de sub-solicitações: Definir Camada de Blob para blobs de blocos e Excluir Blob. A resposta retornada pelo servidor para uma solicitação em lote contém os resultados de cada sub-solicitação no lote. A solicitação e a resposta em lote usam a sintaxe da especificação de OData processamento em lote, com modificações na semântica. Essa API está disponível a partir da versão 2018-11-09.

Solicitação

Você pode construir a solicitação da Blob Batch seguinte maneira. HTTPS é recomendado. Substitua myaccount pelo nome da sua conta de armazenamento.

Método URI da solicitação Versão HTTP
POST https://myaccount.blob.core.windows.net/?comp=batch

https://myaccount.blob.core.windows.net/containername?restype=container&comp=batch		 HTTP/1.1

Parâmetros do URI

Você pode especificar os seguintes parâmetros adicionais no URI de solicitação.

Parâmetro Descrição
timeout Opcional. O parâmetro de tempo limite é expresso em segundos, com um valor máximo de 120 segundos. Para obter mais informações, consulte Configurando tempos limite para operações de Armazenamento de Blobs.
restype Opcional, versão 2020-04-08 e posterior. O único valor com suporte para o restype parâmetro é container. Quando esse parâmetro é especificado, o URI deve incluir o nome do contêiner. Todas as sub-solicitações devem ter como escopo o mesmo contêiner.

Cabeçalhos da solicitação

A tabela a seguir descreve os cabeçalhos de solicitação obrigatórios e opcionais.

Cabeçalho da solicitação Descrição
Authorization Obrigatórios. Especifica o esquema de autorização, o nome da conta de armazenamento e a assinatura. Para saber mais, confira Autorizar solicitações para o Armazenamento do Azure.
Date ou x-ms-date Obrigatórios. Especifica o UTC (Tempo Universal Coordenado) para a solicitação. Para saber mais, confira Autorizar solicitações para o Armazenamento do Azure.
x-ms-version Necessário para todas as solicitações autorizadas. Especifica a versão da operação a ser usada para esta solicitação. Esta versão será usada para todas as sub-solicitações. Para obter mais informações, consulte Controle de versão para os Serviços de Armazenamento do Azure.
Content-Length Obrigatórios. O comprimento da solicitação.
Content-Type Obrigatórios. O valor desse cabeçalho deve ser multipart/mixed, com um limite de lote. Valor de cabeçalho de exemplo: multipart/mixed; boundary=batch_a81786c8-e301-4e42-a729-a32ca24ae252.
x-ms-client-request-id Opcional. Fornece um valor opaco gerado pelo cliente com um limite de caracteres kib (1 kibibyte) que é registrado nos logs quando o registro em log é configurado. É altamente recomendável que você use esse cabeçalho para correlacionar atividades do lado do cliente com solicitações recebidas pelo servidor. Para obter mais informações, consulte Monitorar Armazenamento de Blobs do Azure.

Corpo da solicitação

O corpo da solicitação de um lote de blobs contém uma lista de todas as sub-solicitações. O formato usa a sintaxe da especificação de OData lote, com modificações na semântica.

O corpo da solicitação começa com um limite de lote, seguido por dois cabeçalhos obrigatórios: o Content-Type cabeçalho com o valor application/httpe o Content-Transfer-Encoding cabeçalho com o valor binary. Isso é seguido por um cabeçalho opcional Content-ID , com um valor de cadeia de caracteres para acompanhar cada uma das sub-solicitações. A resposta contém o Content-ID cabeçalho para cada resposta de sub-solicitação correspondente a ser usada para acompanhamento.

Esses cabeçalhos de solicitação são seguidos por uma linha vazia obrigatória e, em seguida, a definição para cada sub-solicitação. O corpo de cada sub-solicitação é uma solicitação HTTP completa com um verbo, URL, cabeçalhos e corpo necessários para a solicitação. Observe as seguintes advertências:

  • As sub-solicitações não devem ter o x-ms-version header. Todas as sub-solicitações são executadas com a versão de solicitação em lote de nível superior.
  • A URL de sub-solicitação deve ter apenas o caminho da URL (sem o host).
  • Cada solicitação em lote dá suporte a um máximo de 256 sub-solicitações.
  • Todas as sub-solicitações devem ser do mesmo tipo de solicitação.
  • Cada sub-solicitação é autorizada separadamente, com as informações fornecidas na sub-solicitação.
  • Cada linha no corpo da solicitação deve terminar com \r\n caracteres.

Solicitação de exemplo

POST http://account.blob.core.windows.net/?comp=batch HTTP/1.1 
Content-Type: multipart/mixed; boundary=batch_357de4f7-6d0b-4e02-8cd2-6361411a9525 
x-ms-version: 2018-11-09 
Authorization: SharedKey account:QvaoYDQ+0VcaA/hKFjUmQmIxXv2RT3XwwTsOTHL39HI=
Host: 127.0.0.1:10000 
Content-Length: 1569 

--batch_357de4f7-6d0b-4e02-8cd2-6361411a9525 
Content-Type: application/http 
Content-Transfer-Encoding: binary 
Content-ID: 0 

DELETE /container0/blob0 HTTP/1.1 
x-ms-date: Thu, 14 Jun 2018 16:46:54 GMT 
Authorization: SharedKey account:G4jjBXA7LI/RnWKIOQ8i9xH4p76pAQ+4Fs4R1VxasaE= 
Content-Length: 0 

--batch_357de4f7-6d0b-4e02-8cd2-6361411a9525 
Content-Type: application/http 
Content-Transfer-Encoding: binary 
Content-ID: 1 

DELETE /container1/blob1 HTTP/1.1 
x-ms-date: Thu, 14 Jun 2018 16:46:54 GMT 
Authorization: SharedKey account:IvCoYDQ+0VcaA/hKFjUmQmIxXv2RT3XwwTsOTHL39HI= 
Content-Length: 0 

--batch_357de4f7-6d0b-4e02-8cd2-6361411a9525 
Content-Type: application/http 
Content-Transfer-Encoding: binary 
Content-ID: 2 

DELETE /container2/blob2 HTTP/1.1 
x-ms-date: Thu, 14 Jun 2018 16:46:54 GMT 
Authorization: SharedKey account:S37N2JTjcmOQVLHLbDmp2johz+KpTJvKhbVc4M7+UqI= 
Content-Length: 0 

--batch_357de4f7-6d0b-4e02-8cd2-6361411a9525--

Resposta

A resposta inclui um código de status HTTP e um conjunto de cabeçalhos de resposta para a solicitação em lote de nível superior. A resposta também inclui informações de resposta para todas as suas sub-solicitações.

Corpo da resposta

A resposta em lote é uma multipart/mixed resposta, que contém a resposta para cada sub-solicitação. A resposta é agrupada. Cada sub-resposta começa com o Content-Type: application/http cabeçalho . O Content-ID cabeçalho segue, se ele foi fornecido na solicitação. Isso é seguido pela resposta HTTP status código e cabeçalhos de resposta para cada sub-solicitação.

Para obter informações sobre os cabeçalhos retornados por cada sub-solicitação, consulte a documentação das operações Excluir Blob e Definir Camada de Blob .

Resposta de exemplo

HTTP/1.1 202 Accepted 
Transfer-Encoding: chunked 
Content-Type: multipart/mixed; boundary=batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed 
x-ms-request-id: 778fdc83-801e-0000-62ff-033467000000 
x-ms-version: 2018-11-09 

409
--batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed 
Content-Type: application/http 
Content-ID: 0 

HTTP/1.1 202 Accepted 
x-ms-delete-type-permanent: true
x-ms-request-id: 778fdc83-801e-0000-62ff-0334671e284f 
x-ms-version: 2018-11-09 

--batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed 
Content-Type: application/http 
Content-ID: 1 

HTTP/1.1 202 Accepted 
x-ms-delete-type-permanent: true
x-ms-request-id: 778fdc83-801e-0000-62ff-0334671e2851 
x-ms-version: 2018-11-09 

--batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed 
Content-Type: application/http 
Content-ID: 2 

HTTP/1.1 404 The specified blob does not exist. 
x-ms-error-code: BlobNotFound 
x-ms-request-id: 778fdc83-801e-0000-62ff-0334671e2852 
x-ms-version: 2018-11-09 
Content-Length: 216 
Content-Type: application/xml 

<?xml version="1.0" encoding="utf-8"?> 
<Error><Code>BlobNotFound</Code><Message>The specified blob does not exist. 
RequestId:778fdc83-801e-0000-62ff-0334671e2852 
Time:2018-06-14T16:46:54.6040685Z</Message></Error> 
--batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed-- 
0

Código de status

Se a solicitação em lote estiver bem formada e autorizada, a operação retornará status código 202 (Aceito). Cada sub-solicitação tem sua própria resposta, dependendo do resultado da operação. O status de sub-solicitação é retornado no corpo da resposta.

Para obter mais informações, consulte Status e códigos de erro.

Cabeçalhos de resposta

A resposta para esta operação inclui os cabeçalhos a seguir. A resposta também pode incluir cabeçalhos HTTP padrão adicionais. Todos os cabeçalhos padrão estão em conformidade com a especificação do protocolo HTTP/1.1.

Autorização

Quando restype=container for omitido, você deverá autorizar a solicitação em lote pai usando uma chave compartilhada. Você pode usar a chave de acesso da conta, uma assinatura de acesso compartilhado da conta ou o Azure Active Directory. Detalhes para mecanismos de autorização específicos mostrados abaixo.

Quando restype=container estiver incluído na solicitação, você poderá autorizar a solicitação em lote pai por meio de uma chave compartilhada ou do Azure Active Directory. Você também pode autorizar com uma assinatura de acesso compartilhado assinada por qualquer um desses mecanismos de autorização. Detalhes para mecanismos de autorização específicos mostrados abaixo.

Cada sub-solicitação é autorizada separadamente. Uma sub-solicitação dá suporte aos mesmos mecanismos de autorização aos quais a operação dá suporte quando não faz parte de uma operação em lote.

O Armazenamento do Azure dá suporte ao uso de Microsoft Entra ID para autorizar solicitações para dados de blob. Com Microsoft Entra ID, você pode usar o RBAC (controle de acesso baseado em função) do Azure para conceder permissões a uma entidade de segurança. A entidade de segurança pode ser um usuário, grupo, entidade de serviço de aplicativo ou identidade gerenciada do Azure. A entidade de segurança é autenticada por Microsoft Entra ID para retornar um token OAuth 2.0. Em seguida, o token pode ser usado para autorizar uma solicitação no serviço de Blob.

Para saber mais sobre a autorização usando Microsoft Entra ID, consulte Autorizar o acesso a blobs usando Microsoft Entra ID.

Permissões

Veja abaixo a ação RBAC necessária para que um usuário, grupo ou entidade de serviço Microsoft Entra faça uma Blob Batch solicitação pai e a função RBAC interna do Azure com menos privilégios que inclua esta ação:

Para saber mais sobre como atribuir funções usando o RBAC do Azure, confira Atribuir uma função do Azure para acesso aos dados de blob.

Cobrança

A Blob Batch solicitação REST é contada como uma transação e cada sub-solicitação individual também é contada como uma transação. Para saber mais sobre a cobrança para os sub-requisitos individuais, consulte a documentação das operações Excluir Blob e Definir Camada de Blob .

As solicitações de preços podem ser originadas de clientes que usam APIs de Armazenamento de Blobs, diretamente por meio da API REST do Armazenamento de Blobs ou de uma biblioteca de clientes do Armazenamento do Azure. Essas solicitações acumulam encargos por transação. O tipo de transação afeta a forma como a conta é cobrada. Por exemplo, as transações de leitura se acumulam em uma categoria de cobrança diferente das transações de gravação. A tabela a seguir mostra a categoria de cobrança de uma Blob Batch solicitação pai com base no tipo de conta de armazenamento:

Operação Tipo de conta de armazenamento Categoria de cobrança
Lote de Blobs (Definir Camada de Blob) Blob de blocos Premium
Uso geral v2 Standard		 Outras operações

Para saber mais sobre os preços para a categoria de cobrança especificada, consulte Armazenamento de Blobs do Azure Preços.

Comentários

Um dos benefícios main de usar uma solicitação em lote é a redução no número de conexões que um cliente precisa abrir. Observe as seguintes restrições:

  • Os sub-requisitos com suporte no lote são Set Blob Tier (para blobs de blocos) e Delete Blob.
  • Dá suporte apenas a até 256 sub-solicitações em um único lote. O tamanho do corpo de uma solicitação em lote não pode exceder 4 MB.
  • Uma solicitação em lote vazia falha com o código 400 (Solicitação Incorreta).
  • Não há garantias sobre a ordem de execução das sub-solicitações do lote.
  • A execução de sub-solicitação do lote não é atômica. Cada sub-solicitação é executada de forma independente.
  • Cada sub-solicitação deve ser para um recurso dentro da mesma conta de armazenamento. Uma única solicitação em lote não dá suporte à execução de solicitações de contas de armazenamento diferentes.
  • Não há suporte para um corpo de solicitação aninhado.
  • Se o servidor não analisar o corpo da solicitação, todo o lote falhará e nenhuma solicitação será executada.
  • Observe que a SAS da conta é o único tipo de assinatura de acesso compartilhado com suporte pelo Blob Batch, quando o lote não está usando restype=container.

Escopo de todos os sub-requisitos para um contêiner específico

A partir da versão REST 2020-04-08, a Blob Batch API dá suporte a sub-solicitações de escopo para um contêiner especificado. Quando o URI da solicitação inclui o nome do contêiner e o restype=container parâmetro , cada sub-solicitação deve ser aplicada ao mesmo contêiner. Se o nome do contêiner especificado para uma sub-solicitação não corresponder ao nome do contêiner fornecido no URI, o serviço retornará o código de erro 400 (Solicitação Incorreta).

Todos os mecanismos de autorização com suporte para um contêiner são válidos para uma Blob Batch operação com escopo para o contêiner. Cada sub-solicitação envia um cabeçalho de autorização para o serviço.

Confira também

Autorizar solicitações para o Status do Armazenamento do Azuree códigos de erroCódigos de erro do Armazenamento de BlobsDefinindo tempos limite para operações de Armazenamento de Blobs