Controle de versão para o Armazenamento do Azure

O Armazenamento do Azure dá suporte a várias versões. Para fazer uma solicitação aos serviços de armazenamento, você deve especificar a versão que deseja usar para essa operação, a menos que a solicitação seja anônima.

A versão atual dos serviços de armazenamento do Azure é 2023-11-03 e recomendamos que você os use sempre que possível. Para obter uma lista de todas as outras versões com suporte e para obter informações sobre como usar cada versão, consulte Versões anteriores do serviço de Armazenamento do Azure.

A versão de serviço 2023-11-03 inclui os seguintes recursos:

  • Nenhum.

Especificar versões de serviço em solicitações

A forma como você especifica a versão dos serviços de armazenamento a serem usados para uma solicitação está relacionada à forma como essa solicitação é autorizada. As seções a seguir descrevem as opções de autorização e como a versão do serviço é especificada para cada uma.

  • Solicitações que usam um token OAuth 2.0 de Microsoft Entra: para autorizar uma solicitação com Microsoft Entra ID, passe o x-ms-version cabeçalho na solicitação com uma versão de serviço de 2017-11-09 ou superior. Para obter mais informações, consulte Chamar operações de armazenamento com tokens OAuth em Autorizar com Microsoft Entra ID.

  • Solicitações que usam Chave Compartilhada ou Chave Compartilhada Lite: para autorizar uma solicitação com Chave Compartilhada ou Chave Compartilhada Lite, passe o x-ms-version cabeçalho na solicitação. No caso de Armazenamento de Blobs do Azure, você pode especificar a versão padrão para todas as solicitações chamando Definir Propriedades do Serviço Blob.

  • Solicitações que usam uma SAS (assinatura de acesso compartilhado): você pode especificar duas opções de controle de versão em uma assinatura de acesso compartilhado. O cabeçalho opcional api-version indica qual versão de serviço usar para executar a operação de API. O parâmetro necessário SignedVersion (sv) especifica a versão do serviço a ser usada para autorizar a solicitação feita com a SAS. Se o api-version cabeçalho não for especificado, o valor do SignedVersion (sv) parâmetro também indicará a versão a ser usada para executar a operação de API.

  • Solicitações que usam acesso anônimo: no caso de acesso anônimo no Armazenamento de Blobs, nenhuma versão é passada. A heurística para determinar qual versão usar para a solicitação é descrita nas próximas seções.

Autorizar solicitações usando Microsoft Entra ID, Chave Compartilhada ou Chave Compartilhada Lite

Para autorizar uma solicitação com Microsoft Entra ID, Chave Compartilhada ou Chave Compartilhada Lite, especifique o x-ms-version cabeçalho na solicitação. O valor do cabeçalho de solicitação x-ms-version deve ser especificado no formato AAAA-MM-DD. Por exemplo:

Request Headers:  
x-ms-version: 2020-04-08

As regras a seguir descrevem como essas solicitações são avaliadas para determinar qual versão usar para processar a solicitação.

  • Se uma solicitação tiver um cabeçalho x-ms-version válido, o serviço de armazenamento usará a versão especificada. Todas as solicitações para o Armazenamento de Tabelas do Azure e o Armazenamento de Filas do Azure que não usam uma assinatura de acesso compartilhado devem especificar um x-ms-version cabeçalho. Todas as solicitações para o Armazenamento de Blobs que não usam uma assinatura de acesso compartilhado devem especificar um x-ms-version cabeçalho, a menos que a versão padrão tenha sido definida, conforme descrito no parágrafo seguinte.

  • Se uma solicitação para o Armazenamento de Blobs não tiver um x-ms-version cabeçalho, mas o proprietário da conta tiver definido uma versão padrão usando a operação Definir Propriedades do Serviço blob , a versão padrão especificada será usada como a versão da solicitação.

Autorizar solicitações usando uma assinatura de acesso compartilhado

Uma SAS (assinatura de acesso compartilhado) gerada usando a versão 2014-02-14 ou posterior dá suporte a duas opções de controle de versão:

  • O api-version parâmetro de consulta define a versão do protocolo REST a ser usada para processar uma solicitação feita usando a SAS.

  • O SignedVersion (sv) parâmetro de consulta define a versão sas a ser usada para autorização.

O SignedVersion parâmetro de consulta é usado para autorização quando um cliente faz uma solicitação usando a SAS. Parâmetros de autorização como si, , sr, sp, sigst, se, tn, spk, srk, epk, e erk são interpretados usando a versão especificada.

Parâmetros de protocolo REST como rscc, rscd, rsce, rscle rsct são impostos usando a versão fornecida no cabeçalho do api-version parâmetro. Se o api-version cabeçalho não for especificado, a versão de serviço fornecida para SignedVersion será usada.

O api-version parâmetro não faz parte da cadeia de caracteres para entrar no cabeçalho de autorização, conforme descrito em Criar uma SAS de serviço.

A tabela a seguir explica o esquema de controle de versão usado pelo serviço para autorização e para chamar o protocolo REST quando o SignedVersion parâmetro for definido como versão 2014-02-14 ou posterior.

Valor do parâmetro api-version Versão usada para autorização Versão usada para o comportamento do protocolo
Não especificado Versão especificada no sv parâmetro Versão especificada no sv parâmetro
Qualquer versão válida dos serviços de armazenamento no formato XXXX-XX-XX Versão especificada no sv parâmetro Versão válida dos serviços de armazenamento XXXX-XX-XX

Exemplo 1

O exemplo de solicitação a seguir chama Listar Blobs com sv=2015-04-05e sem o api-version parâmetro .

https://myaccount.blob.core.windows.net/mycontainer?restype=container&comp=list&sv=2015-04-05&si=readpolicy&sig=a39 %2BYozJhGp6miujGymjRpN8tsrQfLo9Z3i8IRyIpnQ%3d

Nesse caso, o serviço autentica e autoriza a solicitação usando a versão 2015-04-05 e executa a operação usando a versão 2015-04-05.

Exemplo 2

O exemplo de solicitação a seguir chama Listar Blobs com sv=2015-04-05 e com o api-version parâmetro .

https://myaccount.blob.core.windows.net/mycontainer?restype=container&comp=list&sv=2015-04-05&si=readpolicy&sig=a39 %2BYozJhGp6miujGymjRpN8tsrQfLo9Z3i8IRyIpnQ%3d&api-version=2012-02-12

Aqui, o serviço autoriza a solicitação usando a versão 2015-04-05 e executa a operação usando a versão 2012-02-12.

Observação

A biblioteca de clientes do Armazenamento do .NET sempre define a versão do protocolo REST (no api-version parâmetro) para a versão na qual ela se baseia.

Solicitações por meio de acesso anônimo

As solicitações feitas por meio de acesso anônimo são tratadas de forma diferente, dependendo do tipo de conta de armazenamento em que são feitas.

Para contas de armazenamento de uso geral

Se uma solicitação anônima para uma conta de armazenamento de uso geral não especificar o x-ms-version cabeçalho e a versão padrão do serviço não tiver sido definida usando Definir Propriedades do Serviço Blob, o serviço usará a versão mais antiga possível para processar a solicitação. No entanto, se o contêiner foi tornado público com uma operação set container ACL que foi executada usando a versão 2009-09-19 ou posterior, a solicitação é processada usando a versão 2009-09-19.

Para contas de Armazenamento de Blobs

Se uma solicitação anônima para uma conta de Armazenamento de Blobs não especificar o x-ms-version cabeçalho e a versão padrão do serviço não tiver sido definida usando Definir Propriedades do Serviço Blob, o serviço usará a versão mais antiga possível para processar a solicitação. Para uma conta de Armazenamento de Blobs, a versão mais antiga possível é 2014-02-14.

Problemas conhecidos

Esta seção detalha os problemas conhecidos das APIs REST do Armazenamento do Azure.

InvalidHeaderValue mensagem de erro

Em cenários raros, aplicativos que fazem chamadas diretas à API REST podem receber uma InvalidHeaderValue mensagem de erro. O erro é semelhante ao seguinte exemplo:

HTTP/1.1 400 The value for one of the HTTP headers is not in the correct format.
Content-Length: 328
Content-Type: application/xml
Server: Microsoft-HTTPAPI/2.0
x-ms-request-id: <REMOVED>
Date: Fri, 19 May 2023 17:10:33 GMT
 
<?xml version="1.0" encoding="utf-8"?><Error><Code>InvalidHeaderValue</Code><Message>The value for one of the HTTP headers is not in the correct format.
RequestId:<REMOVED>
Time:2023-05-19T17:10:34.2972651Z</Message><HeaderName>x-ms-version</HeaderName><HeaderValue>yyyy-mm-dd</HeaderValue></Error> 

É recomendável que você use uma versão anterior da API REST para ver se o problema é resolvido. Se o problema persistir ou se a recomendação não for viável, abra um tíquete de suporte para discutir outras opções.

Confira também