Lote de Blobs

Artigo
05/15/2024

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 Microsoft Entra. 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 Microsoft Entra. 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.

Importante

A Microsoft recomenda usar Microsoft Entra ID com identidades gerenciadas para autorizar solicitações para o Armazenamento do Azure. Microsoft Entra ID fornece segurança superior e facilidade de uso em comparação com a autorização de Chave Compartilhada.

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, um grupo, uma entidade de serviço de aplicativo ou uma 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, identidade gerenciada ou entidade de serviço Microsoft Entra faça uma Blob Batch solicitação pai e a função rbac interna do Azure com privilégios mínimos que inclua esta ação:

Ação rbac do Azure:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write
Função interna com privilégios mínimos:Colaborador de Dados de Blob de Armazenamento

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.

Uma SAS (assinatura de acesso compartilhado) fornece acesso delegado seguro aos recursos em uma conta de armazenamento. Com uma SAS, você tem controle granular sobre como um cliente pode acessar dados. Você pode especificar qual recurso o cliente pode acessar, quais permissões eles têm para esses recursos e por quanto tempo a SAS é válida.

A Blob Batch solicitação pai dá suporte a assinaturas de acesso compartilhado para os seguintes cenários:

Quando restype=container é omitido: há suporte para SAS de conta
Quando restype=container está incluído na solicitação: SAS de delegação de usuário, SAS de serviço e SAS de conta têm suporte

Como prática recomendada de segurança, recomendamos que você use Microsoft Entra credenciais em vez da chave de conta de armazenamento, que pode ser comprometida com mais facilidade. Se o design do aplicativo exigir assinaturas de acesso compartilhado, use Microsoft Entra credenciais para criar uma SAS de delegação de usuário, quando possível.

Quando o acesso à Chave Compartilhada não for permitido para a conta de armazenamento, um token SAS de serviço ou um token SAS da conta não será permitido em uma solicitação para o Armazenamento de Blobs. Para saber mais, confira Entender como a não permissão da Chave Compartilhada afeta os tokens SAS.

SAS de delegação do usuário

Uma SAS de delegação de usuário é protegida com Microsoft Entra credenciais e também pelas permissões especificadas para a SAS.

Uma Blob Batch solicitação pai usando um token SAS delegado a um contêiner ou recurso de blob requer a permissão Gravar (w) como parte do token SAS de delegação do usuário.

Para saber mais sobre a SAS de delegação de usuário, consulte Create uma SAS de delegação de usuário.

SAS de serviço

Uma SAS de serviço é protegida com a chave da conta de armazenamento. Uma SAS de serviço delega acesso a um recurso em um único serviço de Armazenamento do Azure, como o armazenamento de blobs.

Uma Blob Batch solicitação pai usando um token SAS delegado a um contêiner ou recurso de blob requer a permissão Gravar (w) como parte do token SAS de serviço.

Para saber mais sobre a SAS de serviço, consulte Create uma SAS de serviço.

SAS de Conta

Uma SAS de conta é protegida com a chave da conta de armazenamento. Uma SAS de conta delega acesso a recursos em um ou mais dos serviços de armazenamento. Todas as operações disponíveis através de uma SAS de serviço ou de delegação do usuário também estão disponíveis por meio de uma SAS de conta.

A tabela a seguir indica o tipo de recurso assinado e as permissões assinadas a serem especificadas ao delegar acesso:

Operação	Serviço assinado	Tipo de recurso assinado	Permissão assinada
Lote de Blobs (solicitação pai)	Blob (b)	Objeto (o)	Gravação (w)

Para saber mais sobre a SAS da conta, consulte Create uma SAS de conta.

A Blob Batch solicitação pai dá suporte à autorização de Chave Compartilhada. A autorização com chaves de conta não é recomendada para a maioria dos cenários, pois é menos segura.

A Microsoft recomenda não permitir a autorização de Chave Compartilhada para a conta de armazenamento quando possível. Para obter mais informações, consulte Impedir autorização com chave compartilhada.

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 das sub-solicitações 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 da categoria de cobrança especificada, confira Preços Armazenamento de Blobs do Azure.

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:

As sub-solicitações com suporte no lote são Set Blob Tier (para blobs de blocos) e Delete Blob.
Só dá suporte 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 de lote.
A execução da sub-solicitação de 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.

Definir o escopo de todas as sub-solicitações 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 códigos de erro e Status do Armazenamento do Azure Códigos de erro do Armazenamento de Blobs Definindo tempos limite para operações de Armazenamento de Blobs

Compartilhar via