Versionsverwaltung für Azure Storage

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.

Ab dem 14. Juli 2025 ist 2025-05-05die neueste vollständig bereitgestellte Version des Azure Storage-Diensts . 2025-07-05 wird auch auf breiter Basis eingesetzt, wie in der folgenden Tabelle dargestellt. Alle Versionen sind GA-Qualität.

Wenn in der Tabelle angegeben ist, dass in x-ms-version einer Region aktiviert ist, sind auch alle vorherigen x-ms-versions aktiviert. Wenn Sie versuchen, eine Dienstversion zu verwenden, die in der Region Ihres Speicherkontos nicht vollständig bereitgestellt wurde, wird möglicherweise ein x-ms-version-Mismatch-Fehler generiert.

Die Standardeinstellung x-ms-version , die von den SDKs der Azure Storage-Datenebene verwendet wird, finden Sie in den Änderungsprotokollen in der folgenden Tabelle:

Die Storage SDKs auf Datenebene führen keine GA-Releases für die anderen offiziellen Paketfeeds aus, bis der Standard x-ms-version für die betreffende Version in allen Regionen vollständig eingeführt wurde. Daher kann die neueste GA SDK-Version von den offiziellen Paketmanagern sicher in jeder Region verwendet werden.

Die neueste Version der Azure-Speicherdienste ist der 05.11.2025, und 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 Vorherigen Azure Storage-Dienstversionen.

Die Serviceversion vom 05.11.2025 umfasst die folgenden Funktionen:

• Die folgenden APIs geben nun und x-ms-copy-source-status-codezurückx-ms-copy-source-error-code. Weitere Informationen finden Sie unter Status- und Fehlercodes.
  • Copy Blob
  • Blob aus URL kopieren
  • Put Blob From URL
  • Block von URL setzen
  • Seite von URL einfügen
  • Inkrementelles Kopieren von Blobs
  • Block von URL anhängen
  • Bereich von URL einfügen
  • Copy File

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. Wenn Sie Azure Blob Storage verwenden, können Sie die Standardversion für alle Anforderungen angeben, indem Sie Set Blob Service Properties aufrufen.

• 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 Zugriff verwenden: Bei der Verwendung des anonymen Zugriffs für 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. For example:

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 Shared Access Signature verwenden, müssen einen x-ms-version Header angeben, es sei denn, die Standardversion ist festgelegt, wie im nächsten Absatz beschrieben.

• Wenn eine Anforderung an Blob Storage keinen x-ms-version Header enthält, der Kontobesitzer jedoch mithilfe des Vorgangs Set Blob Service Properties eine Standardversion festlegt, 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 im Parameterheader angegebenen api-version Version erzwungen. Wenn der api-version Header nicht angegeben ist, wird die bereitgestellte SignedVersion Dienstversion verwendet.

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.

Example 1

The following sample request calls List Blobs with sv=2015-04-05, and without the api-version parameter.

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.

Example 2

The following sample request calls List Blobs with sv=2015-04-05 and with the api-version parameter.

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.

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.

Universelle Speicherkonten

Wenn eine anonyme Anforderung an ein universelles Speicherkonto den x-ms-version Header nicht angibt und die Standardversion für den Dienst nicht mithilfe von Set Blob Service Properties festgelegt wird, verwendet der Dienst die frühestmögliche Version, um die Anforderung zu verarbeiten. Wenn der Container mit dem Set Container ACL-Vorgang mit Version 2009-09-19 oder höher öffentlich gemacht 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 Blob-Diensteigenschaften festlegen festgelegt wird, verwendet der Dienst die frühestmögliche Version, um die Anforderung zu verarbeiten. Für ein Blob Storage-Konto ist die früheste mögliche Version 2014-02-14.

Known issues

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 zu versuchen, das Problem zu beheben. Wenn das Problem weiterhin besteht oder die Empfehlung nicht umsetzbar ist, öffnen Sie bitte ein Support-Ticket , um weitere Optionen zu besprechen.

See also

• -REST-
• bewährte Methoden für die Versionsverwaltung
• Protokollversionsunterstützung für .NET-Clientbibliotheksversionen