Überblick über die XML API

Dieses Dokument bietet eine Übersicht über die Cloud Storage XML API und richtet sich an Softwareentwickler. Es wird angenommen, dass Sie mit RESTful-Diensten und Webprogrammierung vertraut sind und Anwendungen erstellen können, die über HTTP-Anfragen arbeiten. Falls das nicht auf Sie zutrifft, haben Sie folgende Möglichkeiten:

• Wenn Sie Cloud Storage noch nicht kennen, sollten Sie zuerst die Kurzanleitung zur Cloud Console oder die Kurzanleitung für gsutil lesen. Diese Anleitungen zeigen die Grundlagen für die Verwendung von Cloud Storage, ohne die API direkt verwenden zu müssen.

• Wenn Sie in bestimmten Programmiersprachen arbeiten, können Sie die Cloud Storage-Clientbibliotheken verwenden.

• Als Entwickler von mobilen oder Web-Apps können Sie die Firebase SDKs für Cloud Storage verwenden.

• Wenn Sie kein Softwareentwickler sind und Ihre personenbezogenen Daten in der Cloud speichern und für andere freigeben möchten, können Sie Google Drive verwenden.

Übersicht

Die Cloud Storage XML API ist eine RESTful-Oberfläche, mit der Sie Cloud Storage-Daten programmatisch verwalten können. Als eine RESTful API werden Methodeninformationen und Extraktionsinformationen verwendet, um die auszuführenden Vorgänge zu definieren:

• Informationen zur Methode

  Sie geben die Methodeninformationen mit Standard-HTTP-Methoden wie DELETE, GET, HEAD und PUT an.

• Informationen zur Kennzeichnung

  Sie geben die Bereichsinformationen mit einem öffentlich zugänglichen Endpunkt (URI) und verschiedenen Bereichsparametern an. Bei der XML API sind die primären Parameter die Bucket- und Objektnamen. Sie können Ihre Vorgänge zusätzlich mit HTTP-Headern und Abfragestringparametern eingrenzen.

Sie verwenden HTTP-Methoden, um Vorgänge für die Ressource durchzuführen, die Sie im Bereich angeben. Eine Liste der in der XML API verfügbaren Vorgänge finden Sie unter XML API-Anfragemethoden.

Der Zugriff auf Cloud Storage über die XML API ist nützlich, wenn Sie Tools und Bibliotheken verwenden, die zwischen verschiedenen Speicheranbietern funktionieren, oder wenn Sie von einem anderen Speicheranbieter zu Cloud Storage migrieren. Im anderen Fall müssen Sie nur ein paar einfache Änderungen an Ihren vorhandenen Tools und Bibliotheken vornehmen, um Anfragen an Cloud Storage zu senden. Weitere Informationen zur Migration zu Cloud Storage finden Sie unter Von Amazon S3 zu Google Cloud Storage migrieren.

Anfragen

Hinweis :Wir empfehlen, beim Lesen oder Schreiben von Daten in Cloud Storage HTTPS zu verwenden, damit Ihre Daten während der Übertragung verschlüsselt werden. Cloud Storage verschlüsselt Ihre Daten automatisch, bevor sie auf das Laufwerk geschrieben werden. Weitere Informationen finden Sie unter Verschlüsselung.

Die XML API von Cloud Storage bietet eine Weboberfläche zum Senden von HTTP-Anfragen und Verarbeiten von HTTP-Antworten. Die API ist mit den HTTP/1.1-, HTTP/2- und HTTP/3-Protokollen kompatibel. Bei jeder Anfrage wird eine Standard-HTTP-Methode implementiert. Neben diesen Methoden können Sie verschiedene HTTP-Anfrage-Header verwenden.

Authentication

Alle Anfragen an Cloud Storage müssen authentifiziert werden, mit Ausnahme von Anfragen an anonym zugängliche Objekte oder Buckets. Ausführliche Informationen zum Festlegen der Autorisierungsheader für Cloud Storage-Anfragen finden Sie unter Authentifizierung.

Endpunkte

Wichtig: Wenn Sie Inhalte über einen Browser bereitstellen möchten, beachten Sie, dass die XML API Inhalte vom gleichen Ursprung wie den Anfrageendpunkt bereitstellt. Wenn Sie Inhalte von einem nur einmal vorkommenden Ursprung bereitstellen müssen, sollten Sie die JSON API oder authentifizierte Browserdownloads verwenden.

Die meisten Cloud Storage XML API-Anfragen verwenden für den Zugriff auf Buckets und Objekte den folgenden URI:

storage.googleapis.com

Dazu können Sie dem URI einen Bucket und ein Objekt hinzufügen. Die resultierende URL kann in zwei Formen vorliegen:

BUCKET_NAME.storage.googleapis.com/OBJECT_NAME
storage.googleapis.com/BUCKET_NAME/OBJECT_NAME

Sie können den Cloud Storage-URI mit ungesicherten Anfragen (HTTP) und sicheren Anfragen (HTTPS) verwenden, die eine SSL-Verschlüsselung (Secure Sockets Layer) verwenden.

Weitere Endpunkte wie dedizierte Upload- und Download-Endpunkte für die XML API finden Sie unter Anfrageendpunkte.

Header und Abfragestringparameter

Die Cloud Storage XML API unterstützt HTTP-Anfrageheader. Außerdem werden mehrere Erweiterungsheader für die Erweiterung unterstützt, die das Präfix x-goog- haben. Die Anforderungen an den Header der Anfrage variieren je nach Art der Anfrage. Einige häufig verwendete Anfrageheader:

Anfrage-Header	Beschreibung	Nutzung
Authorization	Der Authentifizierungsstring für Anfragen.	Erforderlich für alle authentifizierten Anfragen.
Content-Length	Die Größe des Anfragetexts (ohne Header) in Byte.	Erforderlich für alle PUT- und POST-Anfragen, außer bei aufgeteilten Übertragungen.
Content-Type	Der MIME-Typ des Anfragetexts, z. B. application/xml oder text/html.	Empfohlen für Anfragen, die einen Entitätstext enthalten.
Date	Datum und Uhrzeit der Anfrage.	Erforderlich für alle Anfragen.
Host	Der URI für die Anfrage.	Erforderlich für alle Anfragen.
x-goog-project-id	Die ID des Projekts, das Sie verwenden möchten.	Erforderlich zum Erstellen von Buckets oder Auflisten von Buckets, außer wenn Sie die XML API für die Interoperabilität verwenden, z. B. zur Kompatibilität mit Amazon S3. Weitere Informationen finden Sie unter Von Amazon S3 zu Google Cloud Storage migrieren.

Die Cloud Storage XML API unterstützt außerdem eine Vielzahl von Abfragestringparametern, mit denen Sie Ihre Anfragen eingrenzen können. Hängen Sie Abfragestringparameter an den HTTP-Pfadabschnitt der Anfrage mit der folgenden Syntax an:

PATH_TO_OBJECT/?PARAMETER=VALUE&PARAMETER=VALUE...

Eine vollständige Liste der XML API-Header und Abfragestringparameter finden Sie unter HTTP-Header und Abfragestringparameter.

Beispielanfrage

Im folgenden Beispiel sehen Sie eine typische authentifizierte Cloud Storage-Anfrage. Diese Anfrage ruft eine Liste von Objekten ab, die in einem Bucket mit dem Namen travel-maps gespeichert sind. Die Anfrage begrenzt die Liste der Objekte auf die Objekte mit dem Präfix /europe/france.

GET /?prefix=/europe/france/ HTTP/1.1
Host: travel-maps.storage.googleapis.com
Date: Wed, 17 Feb 2010 15:31:56 -0800
Content-Length: 0
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg

Antworten

Die Cloud Storage XML API gibt Standard-HTTP-Antwort-Header und mehrere benutzerdefinierte Antwortheader zurück. Die Antwortheader variieren je nach ausgeführten Vorgang. Einige häufig verwendete Antwortheader:

Antwort-Header	Beschreibung
Cache-Control	Die Cache-Steuerungseinstellung für die Antwort.
Content-Length	Die Größe des Antworttexts (ohne Header) in Byte.
Content-Type	Der MIME-Typ des Antworttexts, z. B. application/xml oder text/html.
Date	Datum und Uhrzeit der Antwort.
ETag	Ein HTTP 1.1-Entitäts-Tag, mit dem Sie ermitteln können

Ob ein Objekt geändert wurde.

Die Antworten können auch einen Statuscode enthalten. Cloud Storage verwendet Standard-HTTP-Statuscodes. Eine Fehlerantwort enthält ein XML-Dokument im Antworttext, das Informationen zu den Fehlerbedingungen enthält. Eine Liste der von der XML API verwendeten Statuscodes finden Sie unter HTTP-Status- und -Fehlercodes.

Im folgenden Beispiel wird eine typische Cloud Storage-Antwort dargestellt. Dieses Beispiel ist eine Antwort auf eine Anfrage zum Auflisten der Inhalte von Buckets. Der Bucket-Name lautet travel-maps und die Anfrage wird eingeschränkt, sodass nur Objekte mit dem Präfix /europe/france/ in der Liste zurückgegeben werden.

HTTP/1.1 200 OK
Content-Length: 4061
Content-Type: application/xml
Date: Wed, 17 Feb 2010 23:31:57 GMT
Cache-Control: private, max-age=0

<?xml version='1.0' encoding='utf-8'?>
<ListBucketResult xmlns='http://doc.storage.googleapis.com/2010-03-01'>
  <Name>travel-maps</Name>
  <Prefix>/europe/france/</Prefix>
  <Marker></Marker>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>europe/france/cannes.jpg</Key>
    <LastModified>2010-02-17T22:11:12.487Z</LastModified>
    <ETag>"53fc311c15eda0a031809982ccf92aac"</ETag>
    <Size>5061631</Size>
    <StorageClass>STANDARD</StorageClass>
    <Owner>
      <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID>
      <DisplayName></DisplayName>
    </Owner>
  </Contents>
  <Contents>
    <Key>europe/france/paris.jpg</Key>
    <LastModified>2010-02-17T22:09:57.457Z</LastModified>
    <ETag>"53fc311c15eda0a031809982ccf92aac"</ETag>
    <Size>5061631</Size>
    <StorageClass>STANDARD</StorageClass>
    <Owner>
      <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID>
      <DisplayName></DisplayName>
    </Owner>
  </Contents>
</ListBucketResult>