Versionsverwaltung für Azure Storage

  • Artikel

Azure Storage unterstützt mehrere Versionen. Um eine Anforderung für die Speicherdienste auszuführen, müssen Sie die Version angeben, die Sie für den Vorgang verwenden möchten (es sei denn, die Anforderung ist anonym).

Die aktuelle Version der Azure-Speicherdienste lautet 2023-11-03. Es wird empfohlen, sie nach Möglichkeit zu verwenden. Eine Liste aller anderen unterstützten Versionen und Informationen zur Verwendung der einzelnen Versionen finden Sie unter Vorherige Azure Storage-Dienstversionen.

Die Dienstversion 2023-11-03 enthält die folgenden Features:

  • Keine.

Angeben von Dienstversionen in Anforderungen

Wie Sie die Version der Speicherdienste angeben, die für eine Anforderung verwendet werden sollen, hängt davon ab, wie diese Anforderung autorisiert wird. In den folgenden Abschnitten werden Autorisierungsoptionen und die Angabe der Dienstversion beschrieben.

  • Anforderungen, die ein OAuth 2.0-Token von Microsoft Entra verwenden: Um eine Anforderung mit Microsoft Entra ID zu autorisieren, übergeben Sie den x-ms-version Header für die Anforderung mit einer Dienstversion von 2017-11-09 oder höher. Weitere Informationen finden Sie unter Aufrufen von Speichervorgängen mit OAuth-Token unter Autorisieren mit Microsoft Entra ID.

  • Anforderungen, die Shared Key oder Shared Key Lite verwenden: Um eine Anforderung mit Shared Key oder Shared Key Lite zu autorisieren, übergeben Sie den x-ms-version Header für die Anforderung. Bei Azure Blob Storage können Sie die Standardversion für alle Anforderungen angeben, indem Sie Set Blob Service Properties aufrufen.

  • Anforderungen, die eine SAS (Shared Access Signature) verwenden: Sie können zwei Versionsverwaltungsoptionen für eine Freigegebene Zugriffssignatur angeben. Der optionale api-version Header gibt an, welche Dienstversion zum Ausführen des API-Vorgangs verwendet werden soll. Der erforderliche SignedVersion (sv) Parameter gibt die Dienstversion an, die zum Autorisieren der mit der SAS gestellten Anforderung verwendet werden soll. Wenn der api-version Header nicht angegeben ist, gibt der Wert des SignedVersion (sv) Parameters auch die Version an, die zum Ausführen des API-Vorgangs verwendet werden soll.

  • Anforderungen, die anonymen Zugriff verwenden: Bei anonymem Zugriff auf Blob Storage wird keine Version übergeben. Die Heuristiken zum Bestimmen, welche Version für die Anforderung verwendet werden soll, werden in den nächsten Abschnitten beschrieben.

Autorisieren von Anforderungen mithilfe von Microsoft Entra ID, Shared Key oder Shared Key Lite

Um eine Anforderung mit Microsoft Entra ID, Shared Key oder Shared Key Lite zu autorisieren, geben Sie den x-ms-version Header für die Anforderung an. Der Wert des x-ms-version-Anforderungsheaders muss im Format YYYY-MM-DD angegeben werden. Beispiel:

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

Die folgenden Regeln beschreiben, wie diese Anforderungen ausgewertet werden, um zu bestimmen, welche Version zum Verarbeiten der Anforderung verwendet werden soll.

  • Wenn eine Anforderung über einen gültigen x-ms-version-Header verfügt, verwendet der Speicherdienst die angegebene Version. Alle Anforderungen an Azure Table Storage und Azure Queue Storage, die keine Shared Access Signature verwenden, müssen einen x-ms-version Header angeben. Alle Anforderungen an Blob Storage, die keine Shared Access Signature verwenden, müssen einen x-ms-version Header angeben, es sei denn, die Standardversion wurde festgelegt, wie im nächsten Absatz beschrieben.

  • Wenn eine Anforderung an Blob Storage keinen Header aufweist x-ms-version , aber der Kontobesitzer mithilfe des Vorgangs Blobdiensteigenschaften festlegen eine Standardversion festgelegt hat, wird die angegebene Standardversion als Version für die Anforderung verwendet.

Autorisieren von Anforderungen mithilfe einer Freigegebenen Zugriffssignatur

Eine SAS (Shared Access Signature), die mit Version 2014-02-14 oder höher generiert wird, unterstützt zwei Versionsverwaltungsoptionen:

  • Der api-version Abfrageparameter definiert die REST-Protokollversion, die für die Verarbeitung einer Anforderung verwendet werden soll, die mithilfe der SAS erfolgt.

  • Der SignedVersion (sv) Abfrageparameter definiert die SAS-Version, die für die Autorisierung verwendet werden soll.

Der SignedVersion Abfrageparameter wird für die Autorisierung verwendet, wenn ein Client mithilfe der SAS eine Anforderung ausgibt. Autorisierungsparameter wie si, , sr, sigsp, st, se, tn, spk, , srk, und erkepkwerden alle mithilfe der angegebenen Version interpretiert.

REST-Protokollparameter wie rscc, rscd, rsce, rsclund rsct werden mithilfe der Version erzwungen, die api-version im Parameterheader bereitgestellt wird. Wenn der api-version Header nicht angegeben wird, wird die Dienstversion verwendet, für SignedVersion die bereitgestellt wird.

Der api-version Parameter ist nicht Teil der Zeichenfolgen-to-Sign im Autorisierungsheader, wie unter Erstellen einer Dienst-SAS beschrieben.

In der folgenden Tabelle wird das Versionsverwaltungsschema erläutert, das vom Dienst zur Autorisierung und zum Aufrufen des REST-Protokolls verwendet wird, wenn der SignedVersion Parameter auf Version 2014-02-14 oder höher festgelegt ist.

Wert des api-version-Parameters Für die Autorisierung verwendete Version Für das Protokollverhalten verwendete Version
Nicht angegeben Im sv-Parameter angegebene Version Im sv-Parameter angegebene Version
Beliebige gültige Speicherdienstversion im Format XXXX-XX-XX Im sv-Parameter angegebene Version Gültige Speicherdienstversion XXXX-XX-XX

Beispiel 1

Die folgende Beispielanforderung ruft Listenblobs mit sv=2015-04-05und ohne den -Parameter auf api-version .

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

In diesem Fall authentifiziert und autorisiert der Dienst die Anforderung mithilfe von Version 2015-04-05, und er führt den Vorgang mithilfe von Version 2015-04-05 aus.

Beispiel 2

Die folgende Beispielanforderung ruft Listenblobs mit sv=2015-04-05 und mit dem -Parameter auf 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

Hier autorisiert der Dienst die Anforderung mithilfe der Version 2015-04-05, und er führt den Vorgang mit Version 2012-02-12 aus.

Hinweis

Die .NET Storage-Clientbibliothek legt die REST-Protokollversion (im api-version Parameter) immer auf die Version fest, auf der sie basiert.

Anfragen über anonymen Zugriff

Anforderungen, die über anonymen Zugriff erfolgen, werden je nach Art des Speicherkontos, für das sie gesendet werden, unterschiedlich behandelt.

Für allgemeine Speicherkonten

Wenn eine anonyme Anforderung an ein universelles Speicherkonto den Header nicht angibt x-ms-version und die Standardversion für den Dienst nicht mithilfe von Set Blob Service Properties festgelegt wurde, verwendet der Dienst die frühestmögliche Version, um die Anforderung zu verarbeiten. Wenn der Container jedoch mit einem Set Container ACL-Vorgang öffentlich gemacht wurde, der mit Version 2009-09-19 oder höher ausgeführt wurde, wird die Anforderung mit Version 2009-09-19 verarbeitet.

Für Blob Storage-Konten

Wenn eine anonyme Anforderung an ein Blob Storage-Konto den x-ms-version Header nicht angibt und die Standardversion für den Dienst nicht mithilfe von Set Blob Service Properties festgelegt wurde, verwendet der Dienst die frühestmögliche Version, um die Anforderung zu verarbeiten. Für ein Blob Storage-Konto ist die frühestmögliche Version 2014-02-14.

Bekannte Probleme

In diesem Abschnitt werden bekannte Probleme für die Azure Storage-REST-APIs beschrieben.

InvalidHeaderValue Fehlermeldung

In seltenen Szenarien können Anwendungen, die direkte REST-API-Aufrufe ausführen, eine InvalidHeaderValue Fehlermeldung erhalten. Der Fehler ähnelt dem folgenden Beispiel:

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>

Es wird empfohlen, eine frühere REST-API-Version zu verwenden, um festzustellen, ob das Problem behoben ist. Wenn das Problem weiterhin besteht oder die Empfehlung nicht möglich ist, öffnen Sie ein Supportticket , um weitere Optionen zu besprechen.

Weitere Informationen