Compartilhar via


Controle de versão do 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 5 de junho de 2025, a versão mais recente totalmente implantada do serviço de Armazenamento do Azure é 2025-11-05. 2025-07-05 e 2025-05-05 também são amplamente implantados, conforme indicado na tabela a seguir. Todas as versões são de qualidade GA.

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. A tentativa de usar uma versão de serviço que não está totalmente implantada na região da conta de armazenamento pode gerar um erro de incompatibilidade x-ms-version.

x-ms-version Disponibilidade de região Suporte ao SDK
2025-05-05 Ásia-Leste
ÁsiaSudeste
Austrália
austráliac2
australiaeast
Austrália Sudeste
Áustria
Bélgica
Brasil
Brasil Sul
canadacentral
Canadá Oriental
Chile
Dinamarca
Europa Norte
Europa Ocidental
França
Frances
alemão
alemanhawc
ÍndiaCentral
Índia Sul
Índia Oeste
Indonésia
Israel
israel
Italiano
japaneast
Japão Ocidental
jioinc
jioinw
koreacentral
Coreia do Sul
Malásia
Malásia
México
Nova Zelândia
Noruega
Noruega
Polônia
qatarc
sul-africano
África do Sul
Espanha
Suécia
Suécia
Suíça
Suíça
Taiwan
Taiwan
UAEC
UAEN
uksouth
ukwest
uscentral
USConceuap
Leste
useast2
Useast2Euap
norte dos EUA
sul dos EUA
ussouth2
dos EUASUDESTE
ussoutheast3
ussoutheast5
sudoeste dos EUA
Oeste dos EUA
uswest2
uswest3
uswestcentral
Última GA
2025-07-05 Austrália
austráliac2
australiaeast
Áustria
Bélgica
Brasil
Brasil Sul
canadacentral
Canadá Oriental
Chile
Dinamarca
Europa Norte
Europa Ocidental
França
Frances
alemão
alemanhawc
ÍndiaCentral
Índia Sul
Índia Oeste
Indonésia
Israel
israel
Italiano
japaneast
Japão Ocidental
jioinc
jioinw
Coreia do Sul
Malásia
Malásia
México
Nova Zelândia
Noruega
Noruega
Polônia
qatarc
sul-africano
Espanha
Suécia
Suécia
Suíça
Suíça
Taiwan
Taiwan
UAEC
UAEN
uksouth
ukwest
USConceuap
ussouth2
dos EUASUDESTE
ussoutheast3
ussoutheast5
sudoeste dos EUA
uswestcentral
Beta
2025-11-05 Austrália
austráliac2
australiaeast
Bélgica
Brasil
Brasil Sul
Chile
Dinamarca
França
Frances
alemanhawc
ÍndiaCentral
Índia Sul
Índia Oeste
Indonésia
israel
Italiano
japaneast
jioinc
jioinw
Coreia do Sul
Malásia
Malásia
México
Nova Zelândia
Noruega
Polônia
qatarc
Espanha
Suécia
Suécia
Suíça
Suíça
Taiwan
Taiwan
UAEC
UAEN
ukwest
ussouth2
dos EUASUDESTE
ussoutheast3
ussoutheast5
sudoeste dos EUA
uswestcentral
Beta

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:

Serviço Blob ADLS Gen 2 Serviço de arquivos Serviço Fila
.REDE Azure.Storage.Blobs Azure.Storage.Files.DataLake Azure.Storage.Files.Shares Azure.Storage.Queues
Java azure-storage-blob azure-storage-file-datalake Compartilhamento de Arquivos do Azure Storage azure-storage-queue
Pitão azure-storage-blob azure-storage-file-datalake Compartilhamento de Arquivos do Azure Storage azure-storage-queue
JavaScript blob de armazenamento datalake de arquivo de armazenamento compartilhamento de arquivos de armazenamento fila de armazenamento
C++ azure-storage-blobs azure-storage-files-datalake azure-storage-files-shares azure-storage-queues
GoLang azblob azdatalake azfile azqueue

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 distribuiçã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 do Azure é 2025-11-05 e recomendamos que você a 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 2025-11-05 inclui os seguintes recursos:

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

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 a ID do Microsoft Entra, 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 no Authorize with 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 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 api-version opcional indica qual versão de serviço usar para executar a operação de API. O parâmetro SignedVersion (sv) necessário especifica a versão do serviço a ser usada para autorizar a solicitação feita com a 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 de API.

  • Solicitações que usam acesso anônimo: ao utilizar o 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 a ID do Microsoft Entra, a Chave Compartilhada ou a Chave Compartilhada Lite

Para autorizar uma solicitação com a ID do Microsoft Entra, a Chave Compartilhada ou a Chave Compartilhada 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 YYYY-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 Tabelas 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 seja definida, conforme descrito no próximo parágrafo.

  • Se uma solicitação para o Armazenamento de Blobs 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 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 parâmetro de consulta api-version define a versão do protocolo REST a ser usada para processar uma solicitação feita usando a 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 interpretados usando a versão especificada.

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

O parâmetro api-version não faz parte da cadeia de caracteres para entrar no cabeçalho de autorização, conforme descrito em Criar um 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 parâmetro SignedVersion é definido como a versão 2014-02-14 ou posterior.

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

Exemplo 1

As chamadas de solicitação de exemplo a seguir blobs de lista com sv=2015-04-05e sem o parâmetro api-version.

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 blobs de lista com sv=2015-04-05 e com o parâmetro api-version.

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.

Nota

A biblioteca de clientes do Armazenamento .NET sempre define a versão do protocolo REST (no api-version parâmetro) como a versão base.

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.

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 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 Definir ACL de Contêiner usando a versão 2009-09-19 ou posterior, a solicitação será 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 for 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 mensagem de erro InvalidHeaderValue. 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> 

Recomenda-se usar 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 tíquete de suporte para discutir outras opções.

Consulte também