Anfrageendpunkte

Auf dieser Seite werden die verschiedenen Anfrageendpunkte (URIs) erläutert, mit denen Sie auf Cloud Storage zugreifen können. Cloud Storage unterstützt HTTP/1.1-, HTTP/2- und HTTP/3-Protokolle. Ein Endpunkt ist der Standort, an den auf Cloud Storage zugegriffen werden kann, in Form einer URL.

Typische API-Anfragen

JSON API

Verwenden Sie die folgenden Endpunkte, wenn Sie JSON API-Anfragen direkt an Cloud Storage senden:

Verwenden Sie für allgemeine JSON API-Anfragen mit Ausnahme von Objektuploads den folgenden Endpunkt. Ersetzen Sie dabei PATH_TO_RESOURCE durch den entsprechenden Wert:
```
https://storage.googleapis.com/storage/v1/PATH_TO_RESOURCE
```
Verwenden Sie für Objektuploads über die JSON API folgenden Endpunkt. Ersetzen Sie BUCKET_NAME dabei durch den entsprechenden Wert:
```
https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o
```
Verwenden Sie für Batchanfragen den folgenden Endpunkt. Ersetzen Sie dabei PATH_TO_RESOURCE durch den entsprechenden Wert:
```
https://storage.googleapis.com/batch/storage/v1/PATH_TO_RESOURCE
```
Optional können Sie für JSON API-Objektdownloads den folgenden Endpunkt verwenden und dabei BUCKET_NAME und OBJECT_NAME durch die entsprechenden Werte ersetzen:
```
https://storage.googleapis.com/download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?alt=media
```

JSON API-Endpunkte akzeptieren ausschließlich HTTPS-Anfragen.

XML API

Wenn XML API-Anfragen direkt in Cloud Storage gestellt werden, verwenden Sie die Endpunkt-URL im Stil Virtuell gehostet oder im Pfadstil. Ersetzen Sie dabei BUCKET_NAME und OBJECT_NAME durch die entsprechenden Werte:

Endpunkt des virtuellen gehosteten Stils:

https://BUCKET_NAME.storage.googleapis.com/OBJECT_NAME

Endpunkt im Pfadstil:

https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME

XML API-Endpunkte unterstützen die Verschlüsselung mit Secure Socket Layer (SSL), das heißt, Sie können entweder HTTP oder HTTPS verwenden. HTTPS wird empfohlen, insbesondere wenn die Authentifizierung für Cloud Storage mit OAuth 2.0 erfolgt.

Informationen zu Verbindungen über einen Proxy finden Sie unter Fehlerbehebung.

URL-Pfadteile codieren

Zusätzlich zu den allgemeinen Überlegungen zur Bucket-Benennung und zur Objektbenennung sollten Sie aus Gründen der Kompatibilität mit Cloud Storage-Tools die folgenden Zeichen codieren, wenn sie im Objektnamen oder im Abfragestring eines Anfrage-URL vorkommen:

!, #, $, &, ', (, ), *, +, ,, /, :, ;, =, ?, @, [, ] und Leerzeichen.

Wenn Sie beispielsweise eine JSON API-GET-Anfrage für das Objekt foo??bar im Bucket example-bucket senden, sollte der Anfrage-URL so aussehen:

GET https://storage.googleapis.com/storage/v1/b/example-bucket/o/foo%3f%3fbar

Beachten Sie, dass nicht alle aufgelisteten Zeichen in jedem Szenario codiert sein müssen. Darüber hinaus wird die Codierung in der Regel von Clientbibliotheken wie den Cloud Storage-Clientbibliotheken für Sie übernommen, sodass Sie bei Verwendung solcher Tools den Namen des Rohobjekts übergeben können.

Weitere Informationen zur Verwendung der Prozentcodierung finden Sie in RFC 3986 im Abschnitt 3.3 Pfad.

Google Cloud Console-Endpunkte

In der Google Cloud Console greifen Sie über die folgenden URLs auf verschiedene Ressourcen zu:

Ressource	URL
Bucket-Liste für ein Projekt	`https://console.cloud.google.com/storage/browser?project=PROJECT_ID`
Objektliste für einen Bucket	`https://console.cloud.google.com/storage/browser/BUCKET_NAME`
Details zu einem Objekt	`https://console.cloud.google.com/storage/browser/_details/BUCKET_NAME/OBJECT_NAME`
Daten für ein Objekt	Siehe Authentifizierte Browserdownloads

gcloud endpoints

gcloud storage-Befehle verwenden JSON API-Endpunkte. Die Endpunktnutzung wird in Ihrem Namen von der gcloud CLI verwaltet.

Endpunkte der Clientbibliothek

Cloud Storage-Clientbibliotheken verwalten Anfrageendpunkte automatisch. Optional können Sie den Anfrageendpunkt manuell festlegen. Dies kann nützlich sein, wenn Sie einen bestimmten Endpunkt verwenden möchten oder zum Testen, z. B. wenn Sie einen lokalen Emulator verwenden möchten:

C++

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage C++ API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

namespace g = ::google::cloud;
namespace gcs = ::google::cloud::storage;
[](std::string const& bucket_name, std::string const& object_name) {
  // NOTE: the CLOUD_STORAGE_EMULATOR_HOST environment variable overrides any
  //     value provided here.
  auto client = gcs::Client(g::Options{}.set<gcs::RestEndpointOption>(
      "https://storage.googleapis.com"));
  PerformSomeOperations(client, bucket_name, object_name);
}

C#

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage C# API.


using Google.Cloud.Storage.V1;
using System;

public class SetClientEndpointSample
{
    public StorageClient SetClientEndpoint(string endpoint) => new StorageClientBuilder
    {
        BaseUri = endpoint
    }.Build();
}

Go

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Go API.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/storage"
	"google.golang.org/api/option"
)

// setClientEndpoint sets the request endpoint.
func setClientEndpoint(w io.Writer, customEndpoint string, opts ...option.ClientOption) error {
	// customEndpoint := "https://my-custom-endpoint.example.com/storage/v1/"
	// opts := []option.ClientOption{}
	ctx := context.Background()

	// Add the custom endpoint option to any other desired options passed to storage.NewClient.
	opts = append(opts, option.WithEndpoint(customEndpoint))
	client, err := storage.NewClient(ctx, opts...)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

	// Use the client as per your custom endpoint, for example, attempt to get a bucket's metadata.
	client.Bucket("bucket-name").Attrs(ctx)
	return nil
}

Java

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Java API.


import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class SetClientEndpoint {

  public static void setClientEndpoint(String projectId, String endpoint) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The endpoint you wish to target
    // String endpoint = "https://storage.googleapis.com"

    Storage storage =
        StorageOptions.newBuilder().setProjectId(projectId).setHost(endpoint).build().getService();

    System.out.println(
        "Storage Client initialized with endpoint " + storage.getOptions().getHost());
  }
}

Node.js

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Node.js API.

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The custom endpoint to which requests should be made
// const apiEndpoint = 'https://yourcustomendpoint.com';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage({
  apiEndpoint: apiEndpoint,
  useAuthWithCustomEndpoint: true,
});

console.log(`Client initiated with endpoint: ${storage.apiEndpoint}.`);

PHP

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage PHP API.

use Google\Cloud\Storage\StorageClient;

/**
 * Sets a custom endpoint for storage client.
 *
 * @param string $projectId The ID of your Google Cloud Platform project.
 *        (e.g. 'my-project-id')
 * @param string $endpoint The endpoint for storage client to target.
 *        (e.g. 'https://storage.googleapis.com')
 */
function set_client_endpoint(
    string $projectId,
    string $endpoint
): void {
    $storage = new StorageClient([
        'projectId' => $projectId,
        'apiEndpoint' => $endpoint,
    ]);

    // fetching apiEndpoint and baseUri from StorageClient is excluded for brevity
    # ...
    print('Storage Client initialized.' . PHP_EOL);
}

Python

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Python API.


from google.cloud import storage


def set_client_endpoint(api_endpoint):
    """Initiates client with specified endpoint."""
    # api_endpoint = 'https://storage.googleapis.com'

    storage_client = storage.Client(client_options={'api_endpoint': api_endpoint})

    print(f"client initiated with endpoint: {storage_client._connection.API_BASE_URL}")

    return storage_client

Ruby

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Ruby API.

# api_endpoint = "https://storage.googleapis.com"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new(
  endpoint: api_endpoint
)

puts "Client initiated with endpoint #{storage.service.service.root_url}"

Benutzerdefinierte Domains

Wenn Sie eine eigene Domain haben, können Sie deren URIs einem oder mehreren Google Cloud-Diensten zuordnen, einschließlich Cloud Storage-Buckets. Der Begriff Bucket-gebundener Hostname wird manchmal verwendet, um diesen Cloud Storage-Anfrageendpunkt zu beschreiben. Zum Verbinden einer benutzerdefinierten Domain mit einem Cloud Storage-Bucket erstellen Sie eine A- oder CNAME-Weiterleitung in Ihrem DNS-Eintrag.

`A`-Einträge

Wenn Sie eine benutzerdefinierte Domain mit einem Cloud Storage-Bucket verbinden, sollten Sie in der Regel einen A-Eintrag verwenden.

A-Datensätze unterstützen HTTPS-Anfragen.
Mit A-Einträgen kann Traffic von einem einzelnen Hostnamen an mehrere Buckets sowie an andere Google Cloud-Dienste gesendet werden.
Datensätze vom Typ A geben keine Einschränkungen für den Bucket-Namen an.

Der Nachteil bei der Verwendung von A-Einträgen ist, dass dadurch eine zusätzliche Einrichtung und Verwendung zusätzlicher Google Cloud-Ressourcen erforderlich ist. Weitere Informationen zur Verwendung benutzerdefinierter Domains mit A-Einträgen finden Sie unter Load-Balancer und SSL-Zertifikat einrichten.

`CNAME`-Einträge

Beim Verbinden einer benutzerdefinierten Domain mit einem Cloud Storage-Bucket können Sie einen CNAME-Eintrag verwenden. Beachten Sie jedoch, dass dabei bestimmte Einschränkungen gelten:

Datensätze vom Typ CNAME unterstützen nur HTTP-Anfragen.
Datensätze vom Typ CNAME können Traffic nur von einem bestimmten Hostnamen an einen einzelnen Bucket weiterleiten.
Für CNAME-Datensätze müssen der Hostname und der zugehörige Bucket-Name übereinstimmen, und Sie müssen den Bucket-Namen validieren.
CNAME-Einträge können nur für Subdomains wie www.mydomain.com und nicht für Top-Level-Domains wie mydomain.com verwendet werden.

Wenn Sie CNAME-Einträge verwenden, muss der Hostname Ihres CNAME-Eintrags auf Folgendes festgelegt sein:

c.storage.googleapis.com.

Beispiel: Ihre Domain ist example.com und Sie möchten Ihren Kunden Reisekarten zur Verfügung stellen. In diesem Fall können Sie in Cloud Storage einen Bucket namens travel-maps.example.com erstellen und dann im DNS einen CNAME-Eintrag anlegen, der Anfragen von travel-maps.example.com an den Cloud Storage-URI weiterleitet. Dazu veröffentlichen Sie den folgenden CNAME-Eintrag im DNS:

NAME                      TYPE     DATA
travel-maps               CNAME    c.storage.googleapis.com.

Dadurch können Ihre Kunden folgende URL nutzen, um auf eine Karte von Paris zuzugreifen:

http://travel-maps.example.com/paris.jpg

Ihr Domainregistrierungsdienst sollte Ihnen die Möglichkeit bieten, Ihre Domain zu verwalten und unter anderem auch einen CNAME-Ressourceneintrag hinzuzufügen. Wenn Sie beispielsweise Cloud DNS verwenden, beachten Sie die Anleitung zum Hinzufügen von Ressourceneinträgen auf der Seite Einträge hinzufügen, ändern und löschen.

Authentifizierte Browserdownloads

Bei authentifizierten Browserdownloads wird eine cookiebasierte Authentifizierung verwendet. Bei der cookiebasierten Authentifizierung werden Nutzer aufgefordert, sich zum Nachweis ihrer Identität bei ihrem Konto anzumelden. Das angegebene Konto muss die entsprechende Berechtigung zum Herunterladen des Objekts haben. Wenn Sie beispielsweise die Identitäts- und Zugriffsverwaltung verwenden, um den Zugriff auf Ihre Objekte zu steuern, sollte das Konto des Nutzers über die Berechtigung storage.objects.viewer verfügen, die in der Rolle Storage-Objekt-Betrachter erteilt wird.

Verwenden Sie die folgende URL, um ein Objekt mithilfe der cookiebasierten Authentifizierung herunterzuladen. Ersetzen Sie BUCKET_NAME und OBJECT_NAME dabei durch die entsprechenden Werte:

https://storage.cloud.google.com/BUCKET_NAME/OBJECT_NAME

Wenn Sie beispielsweise ein Bild namens london.jpg aus Ihrem Bucket example-maps freigeben würden, wäre die URL:

https://storage.cloud.google.com/example-maps/london.jpg

Nach erfolgreicher Anmeldung werden Sie zum gewünschten Inhalt weitergeleitet. Die URL für diesen Inhalt beginnt mit einer alphanumerischen Sequenz und enthält den String /download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME.

Für authentifizierte Browserdownloads muss HTTPS verwendet werden. Bei Verwendung von HTTP erfolgt eine Weiterleitung an HTTPS.

Zugriff auf öffentliche Objekte

Alle Anfragen an den URI storage.cloud.google.com erfordern eine Authentifizierung. Dies gilt auch dann, wenn allUsers berechtigt sind, auf ein Objekt zuzugreifen. Wenn Sie möchten, dass Nutzer anonym zugängliche Objekte ohne Authentifizierung herunterladen, verwenden Sie den Endpunkt des XML API-Pfadstils:

https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME

Weitere Informationen und Beispiele finden Sie unter Auf öffentliche Daten zugreifen.