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

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:

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:

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);
}

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

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

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
}

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());
  }
}

/**
 * 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}.`);

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);
}

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

# 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.

Unterstützung für gegenseitiges TLS

• JSON API-Anfragen: storage.mtls.googleapis.com

• Authentifizierte Browserdownloads: storage.mtls.cloud.google.com

Nächste Schritte

• Datei in Cloud Storage hochladen
• Datei aus Cloud Storage herunterladen
• Statische Website hosten
• Zugriff auf Daten steuern