Endpoint di richiesta

Questa pagina spiega 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, scritta come URL.

Nota: gli URL di Cloud Storage descritti in questa pagina sono soggetti a modifiche.

Richieste API tipiche

API JSON

Quando effettui richieste API JSON direttamente a Cloud Storage, utilizza i seguenti endpoint:

• Per le richieste API JSON generali, esclusi i caricamenti di oggetti, utilizza il seguente endpoint, sostituendo PATH_TO_RESOURCE con il valore appropriato:

  https://storage.googleapis.com/storage/v1/PATH_TO_RESOURCE

• Per i caricamenti di oggetti API JSON, utilizza il seguente endpoint, sostituendo BUCKET_NAME con il valore appropriato:

  https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o

• Per le richieste in batch, utilizza il seguente endpoint, sostituendo PATH_TO_RESOURCE con il valore appropriato:

  https://storage.googleapis.com/batch/storage/v1/PATH_TO_RESOURCE

• (Facoltativo) Per i download di oggetti API JSON, puoi utilizzare il seguente endpoint, sostituendo BUCKET_NAME e OBJECT_NAME con i valori appropriati:

  https://storage.googleapis.com/download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?alt=media

Gli endpoint API JSON accettano solo richieste HTTPS.

Nota: un endpoint https://www.googleapis.com è supportato anche per l' API JSON e viene restituito nel campo dei metadati selfLink per un oggetto, ma https://storage.googleapis.com è l'endpoint preferito per prestazioni e disponibilità migliori. Allo stesso modo, un endpoint https://content-storage.googleapis.com è supportato per i download e viene restituito nel campo dei metadati mediaLink per un oggetto, ma non è consigliato per l'uso.

API XML

Importante: se intendi pubblicare contenuti tramite un browser, tieni presente che l' API XML pubblica contenuti dalla stessa origine dell'endpoint della richiesta. Se devi pubblicare contenuti da un'origine univoca, valuta la possibilità di utilizzare l'API JSON o i download autenticati dal browser.

Quando effettui richieste API XML direttamente a Cloud Storage, utilizza l'endpoint con hosting virtuale o con percorso, sostituendo BUCKET_NAME e OBJECT_NAME con i valori appropriati:

• Endpoint con hosting virtuale:

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

• Endpoint con percorso:

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

Nota: gli endpoint con hosting virtuale non possono essere utilizzati per accedere ai bucket con nome di dominio. Utilizza invece gli endpoint con percorso o un reindirizzamento.

Gli endpoint API XML supportano la crittografia SSL (Secure Sockets Layer), il che significa che puoi utilizzare HTTP o HTTPS. È consigliabile utilizzare HTTPS, soprattutto se esegui l'autenticazione in Cloud Storage utilizzando OAuth 2.0.

gRPC

Puoi utilizzare gRPC, un framework RPC universale open source ad alte prestazioni sviluppato da Google, per interagire con Cloud Storage. I client gRPC si connettono a un endpoint di servizio. Per Google Cloud servizi come Cloud Storage, in genere si tratta di un indirizzo DNS nel googleapis.com dominio (ad esempio, storage.googleapis.com) e utilizza porte sicure standard come 443. L'utilizzo di gRPC può migliorare le prestazioni e le funzionalità di streaming efficienti.

Per utilizzare gRPC per interagire con Cloud Storage, devi abilitarlo su Librerie client di Cloud.

Abilita gRPC in una libreria client utilizzando uno dei seguenti linguaggi supportati:

• Libreria client C++

• Libreria client Java

• Libreria client Go

Per le connessioni tramite un proxy, consulta l'argomento Risoluzione dei problemi per le best practice.

Codifica delle parti del percorso dell'URL

Oltre alle considerazioni generali per la denominazione dei bucket e la denominazione degli oggetti, per garantire la compatibilità tra gli strumenti di 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 GETAPI JSON per l'oggetto denominato foo??bar nel bucket example-bucket, l'URL della richiesta deve 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 dalle librerie client, come le librerie client di Cloud Storage, quindi puoi passare 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 in RFC 3986.

Google Cloud Endpoint della console

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

Risorsa	URL
Elenco di bucket per un progetto	https://console.cloud.google.com/storage/browser?project=PROJECT_ID
Elenco di oggetti per un bucket	https://console.cloud.google.com/storage/browser/BUCKET_NAME
Dettagli di un oggetto	https://console.cloud.google.com/storage/browser/_details/BUCKET_NAME/OBJECT_NAME
Dati per un oggetto	Vedi Download autenticati dal browser

gcloud endpoints

gcloud storage comandi utilizzano gli endpoint API JSON. L'utilizzo degli endpoint viene gestito per tuo conto dall'interfaccia a riga di comando gcloud.

Endpoint della libreria client

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

C++

Per saperne di più, consulta la documentazione di riferimento dell'APIC++ di Cloud Storage.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

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#

Per saperne di più, consulta la documentazione di riferimento dell'C# API di Cloud Storage.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

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

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

Go

Per saperne di più, consulta la documentazione di riferimento dell' API Go di Cloud Storage.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

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

Per saperne di più, consulta la documentazione di riferimento dell'API Java Cloud Storage.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

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

Per saperne di più, consulta la documentazione di riferimento dell'Node.js API di Cloud Storage.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

/**
 * 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

Per saperne di più, consulta la documentazione di riferimento dell'API PHP Cloud Storage.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

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

Per saperne di più, consulta la documentazione di riferimento dell' API Python di Cloud Storage.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

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

Per saperne di più, consulta la documentazione di riferimento dell'API Cloud Storage Ruby.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie 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}"

Rust

use google_cloud_storage::client::Storage;
use google_cloud_storage::client::StorageControl;

pub async fn sample(bucket_id: &str) -> anyhow::Result<()> {
    const NAME: &str = "hello-world.txt";
    let client = Storage::builder()
        .with_endpoint("https://www.googleapis.com")
        .build()
        .await?;
    // Use the `Storage` client as usual:
    let reader = client
        .read_object(format!("projects/_/buckets/{bucket_id}"), NAME)
        .send()
        .await?;
    println!("Object highlights: {:?}", reader.object());

    let control = StorageControl::builder()
        .with_endpoint("https://www.googleapis.com")
        .build()
        .await?;
    // Use the `StorageControl` client as usual:
    let bucket = control
        .get_bucket()
        .set_name(format!("projects/_/buckets/{bucket_id}"))
        .send()
        .await?;
    println!("Bucket {bucket_id} metadata is {bucket:?}");

    Ok(())
}

Domini personalizzati

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

Record A

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

• I record A 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 Google Cloud servizi.
• I record A non impongono restrizioni sul nome del bucket.

Lo svantaggio dell'utilizzo dei record A è che richiedono una configurazione aggiuntiva e l'utilizzo di risorse aggiuntive Google Cloud . Per una guida all'utilizzo dei domini personalizzati con i record A, vedi Configurare il bilanciatore del carico e il certificato SSL.

Record CNAME

Quando connetti 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.

Supponiamo, ad esempio, che il tuo dominio sia example.com e che tu voglia rendere disponibili le mappe di viaggio ai tuoi clienti. Puoi creare un bucket in Cloud Storage denominato travel-maps.example.com e poi creare un record CNAME nel DNS che reindirizzi le richieste da travel-maps.example.com all'URI di Cloud Storage. Per farlo, 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 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 Aggiungi, modifica ed elimina record.

Download autenticati dal browser

I download autenticati dal browser utilizzano l'autenticazione basata su cookie. L'autenticazione basata su cookie chiede agli utenti di accedere al proprio account utente per stabilire la propria identità. L'account specificato deve avere l'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 avere l'autorizzazione storage.objects.viewer, concessa nel ruolo Visualizzatore oggetti Storage.

Per scaricare un oggetto utilizzando l'autenticazione basata su 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 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 ha il formato https://ALPHANUMERIC_SEQUENCE-apidata.googleusercontent.com/download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME.

Quando esegui download autenticati dal browser, è necessario utilizzare HTTPS; i tentativi di utilizzare HTTP vengono reindirizzati a HTTPS.

Accesso agli oggetti pubblici

Tutte le richieste all'URI storage.cloud.google.com richiedono l'autenticazione. Questo 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 con 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

Mutual TLS (mTLS) è un protocollo standard di settore per l'autenticazione reciproca tra un client e un server. Cloud Storage supporta i seguenti endpoint mTLS:

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

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

• Download autenticati dal 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.