Endpoint di richiesta

Questa pagina descrive i diversi endpoint di richiesta che puoi utilizzare per accedere a Cloud Storage. Cloud Storage supporta i protocolli HTTP/1.1, HTTP/2 e HTTP/3. Un endpoint è la posizione in cui è possibile accedere a Cloud Storage, scritto come URL.

Richieste API tipiche

Per le connessioni tramite un proxy, consulta l'argomento relativo alla risoluzione dei problemi per le pratiche consigliate.

Codifica delle parti del percorso dell'URL

Oltre alle considerazioni generali per la denominazione dei bucket e degli oggetti, per garantire la compatibilità tra gli strumenti Cloud Storage, devi codificare i seguenti caratteri quando vengono visualizzati nel nome dell'oggetto o nella stringa di query di un URL di richiesta:

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

Ad esempio, se invii una richiesta GET dell'API JSON per l'oggetto denominato foo??bar nel bucket example-bucket, l'URL della richiesta dovrebbe essere:

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

Tieni presente che non tutti i caratteri elencati devono essere codificati in ogni scenario. Inoltre, la codifica viene in genere gestita per te dalle librerie client, ad esempio le librerie client di Cloud Storage, in modo da poter trasmettere il nome dell'oggetto non elaborato quando utilizzi questi strumenti.

Per saperne di più sull'utilizzo della codifica percentuale, consulta la sezione 3.3 Percorso della RFC 3986.

Endpoint della consoleGoogle Cloud

Quando utilizzi la console Google Cloud , accedi a risorse diverse utilizzando i seguenti URL:

gcloud endpoints

I comandi gcloud storage utilizzano gli endpoint dell'API JSON. L'utilizzo dell'endpoint è gestito per tuo conto da gcloud CLI.

Endpoint della libreria client

Le librerie client di Cloud Storage gestiscono automaticamente gli endpoint delle richieste. (Facoltativo) Puoi impostare manualmente l'endpoint della richiesta. Ciò può essere utile quando vuoi utilizzare un endpoint specifico o per i test, ad esempio quando vuoi utilizzare un emulatore locale:

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}"

Domini personalizzati

Se possiedi un tuo dominio, puoi mappare i relativi URI a uno o più serviziGoogle Cloud , inclusi i bucket Cloud Storage. Il termine nome host associato al bucket viene talvolta utilizzato per descrivere questo endpoint di richiesta Cloud Storage. Per connettere un dominio personalizzato a un bucket Cloud Storage, crea un reindirizzamento A o CNAME nel record DNS.

A record

Quando colleghi un dominio personalizzato a un bucket Cloud Storage, in genere devi utilizzare un record A.

• A record supportano le richieste HTTPS.
• I record A possono essere utilizzati per inviare il traffico proveniente da un singolo nome host a più bucket e ad altri servizi Google Cloud .
• I record A non impongono restrizioni al nome del bucket.

Lo svantaggio dell'utilizzo dei record A è che richiedono una configurazione aggiuntiva e l'utilizzo di risorse Google Cloud aggiuntive. Consulta Configurazione del bilanciatore del carico e del certificato SSL per una guida all'utilizzo di domini personalizzati con record A.

CNAME record

Quando colleghi un dominio personalizzato a un bucket Cloud Storage, puoi utilizzare un record CNAME, ma tieni presente che questa operazione presenta alcune limitazioni:

• I record CNAME supportano solo le richieste HTTP.
• I record CNAME possono indirizzare il traffico da un determinato nome host a un singolo bucket.
• I record CNAME richiedono che il nome host e il nome del bucket associato corrispondano e devi convalidare il nome del bucket.
• I record CNAME possono essere utilizzati solo per i sottodomini, ad esempio www.mydomain.com, non per i domini di primo livello come mydomain.com.

Quando utilizzi i record CNAME, la parte del nome host del record CNAME deve essere impostata su:

c.storage.googleapis.com.

Ad esempio, supponiamo che il tuo dominio sia example.com e che tu voglia rendere disponibili ai tuoi clienti mappe di viaggio. Puoi creare un bucket in Cloud Storage chiamato travel-maps.example.com e poi creare un record CNAME in DNS che reindirizza le richieste da travel-maps.example.com all'URI Cloud Storage. A questo scopo, pubblica il seguente record CNAME nel DNS:

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

In questo modo, i tuoi clienti possono utilizzare il seguente URL per accedere a una mappa di Parigi:

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

Il servizio di registrazione del dominio dovrebbe consentirti di amministrare il tuo dominio, inclusa l'aggiunta di un record di risorse CNAME. Ad esempio, se utilizzi Cloud DNS, le istruzioni per aggiungere record di risorse sono disponibili nella pagina Aggiungere, modificare ed eliminare record.

Download autenticati dal browser

I download autenticati dal browser utilizzano l'autenticazione basata sui cookie. L'autenticazione basata sui cookie chiede agli utenti di accedere al proprio account utente per stabilire la propria identità. L'account specificato deve disporre dell'autorizzazione appropriata per scaricare l'oggetto. Ad esempio, se utilizzi Identity and Access Management per controllare l'accesso ai tuoi oggetti, l'account dell'utente deve disporre dell'autorizzazione storage.objects.viewer, che viene concessa nel ruolo Visualizzatore oggetti Storage.

Per scaricare un oggetto utilizzando l'autenticazione basata sui cookie, utilizza il seguente URL, sostituendo BUCKET_NAME e OBJECT_NAME con i valori appropriati:

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

Ad esempio, se hai condiviso un'immagine london.jpg dal tuo bucket example-maps, l'URL sarà:

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

Dopo aver eseguito l'accesso, viene visualizzato il contenuto richiesto. L'URL di questi contenuti inizia con una sequenza alfanumerica e contiene la stringa /download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME

L'utilizzo di HTTPS è obbligatorio quando si eseguono download autenticati del browser; i tentativi di utilizzo del reindirizzamento HTTP a HTTPS.

Accesso agli oggetti pubblici

Tutte le richieste all'URI storage.cloud.google.com richiedono l'autenticazione. Ciò vale anche quando allUsers ha l'autorizzazione per accedere a un oggetto. Se vuoi che gli utenti scarichino oggetti accessibili in modo anonimo senza autenticarsi, utilizza l'endpoint in stile percorso dell'API XML:

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

Per dettagli ed esempi, vedi Accesso ai dati pubblici.

Supporto di mutual TLS

• Richieste API JSON: storage.mtls.googleapis.com

• Download autenticati del browser: storage.mtls.cloud.google.com

Passaggi successivi

• Carica un file su Cloud Storage.
• Scarica un file da Cloud Storage.
• Ospita un sito web statico.
• Scopri le opzioni per controllare l'accesso ai tuoi dati.