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 nos 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 partir de 11 de maio de 2026, a versão mais recente totalmente implementada do serviço Armazenamento do Azure é 2026-04-06, suportada pelos mais recentes pacotes SDK Armazenamento do Azure GA. 2026-06-06 é também amplamente implementado, e ambos são suportados pelas versões beta mais recentes dos SDKs de Armazenamento.

Se a tabela indicar que um x-ms-version está habilitado em uma região, todos os anteriores x-ms-versions também serão habilitados. Tentar usar uma versão de serviço que não esteja totalmente implantada na região da sua conta de armazenamento pode gerar um erro de incompatibilidade de versão x-ms.

O padrão x-ms-version usado pelos SDKs do plano de dados do Armazenamento do Azure pode ser encontrado nos logs de alterações na tabela a seguir:

Os SDKs de armazenamento do plano de dados não executam versões GA para os outros feeds de pacotes oficiais até que o padrão x-ms-version para a versão em questão tenha implantação completa em todas as regiões. Portanto, a versão mais recente do SDK do GA dos gerenciadores de pacotes oficiais pode ser usada com segurança em qualquer região.

A versão mais recente dos serviços de armazenamento Azure é 2026-02-06, e recomendamos que a utilize 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 de 2026-06-06 inclui as seguintes funcionalidades:

• Suporte para mensagem estruturada para Criar Ficheiro.

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

A forma como você especifica a versão dos serviços de armazenamento a ser usada 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 do Microsoft Entra: Para autorizar uma solicitação com o Microsoft Entra ID, passe o cabeçalho x-ms-version na solicitação com uma versão de serviço de 2017-11-09 ou superior. Para obter mais informações, consulte operações de armazenamento de chamadas com tokens OAuth em Autorizar com o 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 cabeçalho x-ms-version na solicitação. Ao usar o Armazenamento de Blob do Azure, você pode especificar a versão padrão para todas as solicitações chamando Definir Propriedades do Serviço de Blob.

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

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

Autorizar solicitações usando o Microsoft Entra ID, Shared Key ou Shared Key Lite

Para autorizar uma solicitação com o Microsoft Entra ID, Shared Key ou Shared Key Lite, especifique o cabeçalho x-ms-version na solicitação. O valor do cabeçalho da 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 de x-ms-version válido, o serviço de armazenamento usará a versão especificada. Todas as solicitações para o Armazenamento de Tabela do Azure e o Armazenamento de Filas do Azure que não usam uma assinatura de acesso compartilhado devem especificar um cabeçalho x-ms-version. 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 esteja definida, conforme descrito no próximo parágrafo.

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

Autorizar solicitações usando uma assinatura de acesso compartilhado

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

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

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

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

Os parâmetros do protocolo REST como rscc, rscd, rsce, rscl, e 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 SignedVersion será usada.

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

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 parâmetro SignedVersion é definido como versão 2014-02-14 ou posterior.

Exemplo 1

A solicitação de exemplo 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

A solicitação de exemplo a seguir chama List 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.

Pedidos através 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 contra a qual são feitas.

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 for definida usando Definir Propriedades do Serviço de Blob, o serviço usará a versão mais antiga possível para processar a solicitação. Se o contêiner foi tornado público usando a operação set Container ACL 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 Blob

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

Problemas conhecidos

Esta seção detalha problemas conhecidos para as APIs REST de Armazenamento do Azure.

InvalidHeaderValue mensagem de erro

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

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> 

Recomenda-se o uso de uma versão anterior da API REST para tentar resolver o problema. Se o problema persistir, ou se a recomendação não for viável, abra um ticket de suporte para discutir outras opções.

Consulte também

• Serviços de armazenamento REST
• Práticas recomendadas de controle de versão
• Suporte de versão do protocolo para versões de biblioteca de cliente .NET