Versionsverwaltung für Azure Storage
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 erforderlicheSignedVersion (sv)
Parameter gibt die Dienstversion an, die zum Autorisieren der mit der SAS gestellten Anforderung verwendet werden soll. Wenn derapi-version
Header nicht angegeben ist, gibt der Wert desSignedVersion (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 einenx-ms-version
Header angeben. Alle Anforderungen an Blob Storage, die keine Shared Access Signature verwenden, müssen einenx-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
, sig
sp
, st
, se
, tn
, spk
, , srk
, und erk
epk
werden alle mithilfe der angegebenen Version interpretiert.
REST-Protokollparameter wie rscc
, rscd
, rsce
, rscl
und 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-05
und 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.