Partilhar via

Controlo de versões do Armazenamento do Azure

  • Artigo

O Armazenamento do Azure suporta várias versões. Para fazer um pedido aos serviços de armazenamento, tem de especificar a versão que pretende utilizar para essa operação, a menos que o pedido seja anónimo.

A versão atual dos serviços de armazenamento do Azure é 2024-08-04 e recomendamos que a utilize sempre que possível. Para obter uma lista de todas as outras versões suportadas e para obter informações sobre como utilizar cada versão, veja Versões anteriores do serviço de Armazenamento do Azure.

A versão de serviço 2024-08-04 inclui as seguintes funcionalidades:

Especificar versões de serviço nos pedidos

A forma como especifica a versão dos serviços de armazenamento a utilizar para um pedido está relacionada com a forma como esse pedido é autorizado. As secções seguintes descrevem as opções de autorização e como a versão do serviço é especificada para cada uma.

  • Pedidos que utilizam um token OAuth 2.0 da Microsoft Entra: para autorizar um pedido com o Microsoft Entra ID, transmita o x-ms-version cabeçalho no pedido com uma versão de serviço de 2017-11-09 ou superior. Para obter mais informações, veja Operações de armazenamento de chamadas com tokens OAuth em Autorizar com o Microsoft Entra ID.

  • Pedidos que utilizam a Chave Partilhada ou a Chave Partilhada Lite: para autorizar um pedido com a Chave Partilhada ou a Chave Partilhada Lite, transmita o x-ms-version cabeçalho no pedido. No caso do Armazenamento de Blobs do Azure, pode especificar a versão predefinida para todos os pedidos ao chamar Definir Propriedades do Serviço Blob.

  • Pedidos que utilizam uma assinatura de acesso partilhado (SAS): pode especificar duas opções de controlo de versões numa assinatura de acesso partilhado. O cabeçalho opcional api-version indica que versão de serviço utilizar para executar a operação de API. O parâmetro necessário SignedVersion (sv) especifica a versão do serviço a utilizar para autorizar o pedido feito com a SAS. Se o api-version cabeçalho não for especificado, o valor do SignedVersion (sv) parâmetro também indica a versão a utilizar para executar a operação de API.

  • Pedidos que utilizam acesso anónimo: no caso de acesso anónimo ao Armazenamento de Blobs, não é transmitida nenhuma versão. A heurística para determinar qual a versão a utilizar para o pedido são descritas nas secções seguintes.

Autorizar pedidos com o Microsoft Entra ID, a Chave Partilhada ou a Chave Partilhada Lite

Para autorizar um pedido com o Microsoft Entra ID, a Chave Partilhada ou a Chave Partilhada Lite, especifique o x-ms-version cabeçalho no pedido. O x-ms-version valor do cabeçalho do pedido tem de ser especificado no formato AAAA-MM-DD. Por exemplo:

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

As seguintes regras descrevem como estes pedidos são avaliados para determinar qual a versão a utilizar para processar o pedido.

  • Se um pedido tiver um cabeçalho válido x-ms-version , o serviço de armazenamento utiliza a versão especificada. Todos os pedidos para o Armazenamento de Tabelas do Azure e o Armazenamento de Filas do Azure que não utilizem uma assinatura de acesso partilhado têm de especificar um x-ms-version cabeçalho. Todos os pedidos ao Armazenamento de Blobs que não utilizem uma assinatura de acesso partilhado têm de especificar um x-ms-version cabeçalho, a menos que a versão predefinida tenha sido definida, conforme descrito no parágrafo seguinte.

  • Se um pedido ao Armazenamento de Blobs não tiver um x-ms-version cabeçalho, mas o proprietário da conta tiver definido uma versão predefinida com a operação Definir Propriedades do Serviço Blob , a versão predefinida especificada é utilizada como a versão do pedido.

Autorizar pedidos com uma assinatura de acesso partilhado

Uma assinatura de acesso partilhado (SAS) gerada com a versão 2014-02-14 ou posterior suporta duas opções de controlo de versões:

  • O api-version parâmetro de consulta define a versão do protocolo REST a utilizar para processar um pedido feito com a SAS.

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

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

Os parâmetros do protocolo REST, como rscc, rscd, rsce, rscle rsct são impostos com a versão fornecida no cabeçalho do api-version parâmetro. Se o api-version cabeçalho não for especificado, é utilizada a versão de serviço fornecida SignedVersion .

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

A tabela seguinte explica o esquema de controlo de versões utilizado pelo serviço para autorização e para chamar o protocolo REST quando o SignedVersion parâmetro está definido para a versão 2014-02-14 ou posterior.

Valor do parâmetro api-version Versão utilizada para autorização Versão utilizada 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 seguinte pedido de exemplo 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

Neste caso, o serviço autentica e autoriza o pedido com a versão 2015-04-05 e executa a operação com a versão 2015-04-05.

Exemplo 2

O seguinte pedido de exemplo 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 o pedido com a versão 2015-04-05 e executa a operação com a versão 2012-02-12.

Nota

A biblioteca de cliente de Armazenamento .NET define sempre a versão do protocolo REST (no api-version parâmetro) para a versão em que se baseia.

Pedidos através de acesso anónimo

Os pedidos efetuados através de acesso anónimo são processados de forma diferente, consoante o tipo de conta de armazenamento em que são feitos.

Para contas de armazenamento para fins gerais

Se um pedido anónimo para uma conta de armazenamento para fins gerais não especificar o x-ms-version cabeçalho e a versão predefinida do serviço não tiver sido definida com Definir Propriedades do Serviço blob, o serviço utiliza a versão mais antiga possível para processar o pedido. No entanto, se o contentor tiver sido tornado público com uma operação Set Container ACL que foi executada com a versão 2009-09-19 ou posterior, o pedido é processado com a versão 2009-09-19.

Para contas de Armazenamento de Blobs

Se um pedido anónimo para uma conta de Armazenamento de Blobs não especificar o x-ms-version cabeçalho e a versão predefinida do serviço não tiver sido definida com Definir Propriedades do Serviço Blob, o serviço utiliza a versão mais antiga possível para processar o pedido. Para uma conta de Armazenamento de Blobs, a versão mais antiga possível é 2014-02-14.

Problemas conhecidos

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

InvalidHeaderValue mensagem de erro

Em cenários raros, as aplicações 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>

Recomenda-se que utilize 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 pedido de suporte para discutir mais opções.

Ver também