Versionsverwaltung für Azure Storage

  • Artikel

Azure Storage unterstützt mehrere Versionen. Um eine Anforderung für die Speicherdienste zu stellen, müssen Sie die Version angeben, die Sie für diesen Vorgang verwenden möchten, es sei denn, die Anforderung ist anonym.

Die aktuelle Version der Azure-Speicherdienste ist 2024-11-04, und wir empfehlen, sie nach Möglichkeit zu verwenden. Eine Liste aller anderen unterstützten Versionen und Informationen zur Verwendung der einzelnen Versionen finden Sie unter Vorherigen Azure Storage-Dienstversionen.

Die Dienstversion 2024-11-04 enthält die folgenden Features:

  • Unterstützung für die tokenbasierte Authentifizierung für alle Datenebenen-APIs im Dateidienst. Weitere Informationen finden Sie unter Autorisieren mit microsoft Entra ID.
  • Unterstützung für kostenpflichtige Premium-Dateifreigabekonten. Dieses Feature kann mit der Share- erstellen und Share-Eigenschaften-APIs festlegen.
  • Unterstützung für das Binärformat beim Abrufen und Festlegen von Dateiberechtigungen im Dateidienst. Weitere Informationen finden Sie unter Create Permission und Get Permission

Angeben von Dienstversionen in Anforderungen

Wie Sie die Version der für eine Anforderung zu verwendenden Speicherdienste angeben, bezieht sich auf die Autorisierung dieser Anforderung. In den folgenden Abschnitten werden Autorisierungsoptionen und die Angabe der Dienstversion für die einzelnen Abschnitte beschrieben.

  • Anforderungen, die ein OAuth 2.0-Token von Microsoft Entraverwenden: 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 Anrufspeichervorgänge mit OAuth-Token in Autorisieren mit Microsoft Entra ID.

  • Anforderungen, die gemeinsam genutzten Schlüssel oder Shared Key Liteverwenden: Um eine Anforderung mit freigegebenem Schlüssel oder Shared Key Lite zu autorisieren, übergeben Sie den x-ms-version Header an die Anforderung. Im Fall von Azure Blob Storage können Sie die Standardversion für alle Anforderungen angeben, indem Sie Set Blob Service Propertiesaufrufen.

  • Anforderungen, die eine FREIGEGEBENe Zugriffssignatur (Shared Access Signature, SAS)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 verwendet werden soll, um die anforderung zu autorisieren, die mit der SAS vorgenommen wurde. 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 Zugriffverwenden: Bei anonymen Zugriff auf Blob Storage wird keine Version übergeben. Die Heuristiken zum Bestimmen der version, die für die Anforderung verwendet werden soll, werden in den nächsten Abschnitten beschrieben.

Autorisieren von Anforderungen mithilfe der Microsoft Entra-ID, des freigegebenen Schlüssels oder des freigegebenen Schlüssels Lite

Um eine Anforderung mit Microsoft Entra ID, freigegebenem Schlüssel 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 JJJJ-MM-DD angegeben werden. Zum Beispiel:

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

Die folgenden Regeln beschreiben, wie diese Anforderungen ausgewertet werden, um zu bestimmen, welche Version für die Verarbeitung 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 freigegebene Zugriffssignatur verwenden, müssen einen x-ms-version Header angeben. Alle Anforderungen an Blob Storage, die keine Freigegebene Zugriffssignatur 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 nicht über einen x-ms-version Header verfügt, der Kontobesitzer jedoch eine Standardversion festgelegt hat, indem die Vorgang "Blob-Diensteigenschaften festlegen" Vorgang verwendet wird, wird die angegebene Standardversion als Version für die Anforderung verwendet.

Autorisieren von Anforderungen mithilfe einer freigegebenen Zugriffssignatur

Eine freigegebene Zugriffssignatur (Shared Access Signature, SAS), 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 wird, 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 eine Anforderung mithilfe der SAS sendet. Autorisierungsparameter wie si, sr, sp, sig, st, se, tn, spk, srk, epkund erk werden mit der angegebenen Version interpretiert.

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

Der parameter api-version ist nicht Teil des Zeichenfolgen-zu-Anmelden-Headers, wie in Create a service SASbeschrieben.

In der folgenden Tabelle wird das Versionsverwaltungsschema erläutert, das vom Dienst für die 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 Version, die für das Protokollverhalten verwendet wird
Nicht angegeben Im parameter sv angegebene Version Im parameter sv angegebene Version
Beliebige gültige Speicherdienste-Version im Format XXXX-XX-XX Im parameter sv angegebene Version Gültige Speicherdiensteversion XXXX-XX-XX

Beispiel 1

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

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 mit Version 2015-04-05 und führt den Vorgang mit Version 2015-04-05 aus.

Beispiel 2

Die folgende Beispielanforderung ruft List Blobs mit sv=2015-04-05 und mit dem parameter api-version auf.

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 mit Version 2015-04-05 und führt den Vorgang mit Version 2012-02-12 aus.

Anmerkung

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

Anfragen über anonymen Zugriff

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

Für allgemeine Speicherkonten

Wenn eine anonyme Anforderung an ein allgemeines Speicherkonto nicht den x-ms-version-Header angibt und die Standardversion für den Dienst nicht mithilfe von Set Blob Service Propertiesfestgelegt wurde, verwendet der Dienst die früheste version, um die Anforderung zu verarbeiten. Wenn der Container jedoch mit einer Set Container ACL Operation veröffentlicht wurde, die 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 nicht den x-ms-version-Header angibt und die Standardversion für den Dienst nicht mithilfe von Set Blob Service Propertiesfestgelegt wurde, verwendet der Dienst die früheste version, um die Anforderung zu verarbeiten. Für ein Blob Storage-Konto ist die früheste mö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 sieht ähnlich wie im folgenden Beispiel aus:

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 wird. Wenn das Problem weiterhin besteht oder die Empfehlung nicht möglich ist, ein Supportticket öffnen, um weitere Optionen zu besprechen.

Siehe auch