Endpoint di richiesta

Questa pagina illustra i diversi endpoint delle richieste 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 modifica.

Richieste API tipiche

API JSON

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

• Per le richieste API JSON generali, escludendo i caricamenti di oggetti, utilizza l'endpoint seguente, 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, usa il seguente endpoint, sostituendo PATH_TO_RESOURCE con il valore appropriato:

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

• Facoltativamente, per i download di oggetti API JSON, puoi usare 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 di un oggetto, ma https://storage.googleapis.com è l'endpoint preferito per migliorare le prestazioni e la disponibilità. Analogamente, un endpoint https://content-storage.googleapis.com è supportato per i download e viene restituito nel campo dei metadati mediaLink per un oggetto, ma non è consigliabile utilizzarlo.

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 l'utilizzo dell'API JSON o dei download dei browser autenticati.

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

• Endpoint di tipo ospitato virtuale:

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

• Endpoint di stile percorso:

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

Nota: non è possibile utilizzare endpoint in stile ospitato virtuale per accedere ai bucket con nome di dominio. Utilizza invece endpoint in stile 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 con OAuth 2.0.

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

Codificare le parti del percorso dell'URL

Oltre alle considerazioni generali relative alla denominazione dei bucket e alla denominazione degli oggetti, per garantire la compatibilità tra gli strumenti di Cloud Storage, devi codificare i seguenti caratteri quando vengono visualizzati nel nome 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 tutti i casi. Inoltre, la codifica viene generalmente gestita automaticamente dalle librerie client, ad esempio le librerie client di Cloud Storage, che ti consentono di passare il nome dell'oggetto non elaborato quando utilizzi questi strumenti.

Per ulteriori informazioni sull'utilizzo della codifica percentuale, consulta la sezione 3.3 Percorso in RFC 3986.

Endpoint della console Google Cloud

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

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

gcloud endpoints

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

Endpoint della libreria client

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

C++

Per maggiori informazioni, consulta la documentazione di riferimento dell'API C++ di Cloud Storage.

Per eseguire l'autenticazione in Cloud Storage, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo 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);
}

C#

Per maggiori informazioni, consulta la documentazione di riferimento dell'API C# di Cloud Storage.

Per eseguire l'autenticazione in Cloud Storage, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

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

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

Go

Per maggiori informazioni, consulta la documentazione di riferimento dell'API Go di Cloud Storage.

Per eseguire l'autenticazione in Cloud Storage, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

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 maggiori informazioni, consulta la documentazione di riferimento dell'API Java di Cloud Storage.

Per eseguire l'autenticazione in Cloud Storage, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

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 maggiori informazioni, consulta la documentazione di riferimento dell'API Node.js di Cloud Storage.

Per eseguire l'autenticazione in Cloud Storage, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

/**
 * 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 maggiori informazioni, consulta la documentazione di riferimento dell'API PHP di Cloud Storage.

Per eseguire l'autenticazione in Cloud Storage, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

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 maggiori informazioni, consulta la documentazione di riferimento dell'API Python di Cloud Storage.

Per eseguire l'autenticazione in Cloud Storage, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

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 maggiori informazioni, consulta la documentazione di riferimento dell'API Ruby di Cloud Storage.

Per eseguire l'autenticazione in Cloud Storage, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

# 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 il dominio, puoi mappare i suoi URI a uno o più servizi Google Cloud, inclusi i bucket Cloud Storage. Il termine nome host associato al bucket viene talvolta utilizzato per descrivere questo endpoint della richiesta di Cloud Storage. Per connettere un dominio personalizzato a un bucket Cloud Storage, devi creare un reindirizzamento A o CNAME nel tuo record DNS.

A record

Quando connetti un dominio personalizzato a un bucket Cloud Storage, solitamente 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, nonché ad altri servizi Google Cloud.
• I record A non pongono restrizioni sul nome del bucket.

Lo svantaggio di utilizzare i 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 dei 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 questo comporta alcune limitazioni:

• I record CNAME supportano solo le richieste HTTP.
• I record CNAME possono indirizzare il traffico solo da un determinato nome host a un singolo bucket.
• I record CNAME richiedono la corrispondenza del nome host e del nome del bucket associato, inoltre devi convalidare il nome del bucket.
• I record CNAME possono essere utilizzati solo per i sottodomini, come 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 come segue:

c.storage.googleapis.com.

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

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

In questo modo, i 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, compresa 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 del browser autenticati

I download autenticati del 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 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 avere l'autorizzazione storage.objects.viewer, concessa nel ruolo Visualizzatore oggetti Storage.

Per scaricare un oggetto utilizzando l'autenticazione basata su cookie, usa 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

Una volta eseguito l'accesso, si aprirà la pagina dei contenuti richiesti. L'URL per questi contenuti inizia con una sequenza alfanumerica e contiene la stringa /download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME

L'utilizzo di HTTPS è richiesto quando si eseguono download autenticati dal browser; si tenta di utilizzare il reindirizzamento HTTP a HTTPS.

Importante: se hai abilitato gli audit log di accesso ai dati per tenere traccia dell'accesso agli oggetti, gli utenti non possono utilizzare download del browser autenticati per accedere agli oggetti, a meno che gli oggetti non siano accessibili pubblicamente o l'accesso non venga eseguito all'interno della console Google Cloud. Per ulteriori informazioni, consulta l'argomento Risoluzione dei problemi.

Accesso agli oggetti pubblici

Tutte le richieste all'URI storage.cloud.google.com richiedono l'autenticazione. Ciò si applica anche se allUsers è autorizzato ad accedere a un oggetto. Se vuoi che gli utenti scarichino oggetti accessibili in modo anonimo senza eseguire l'autenticazione, utilizza l'endpoint di stile del percorso dell'API XML:

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

Per dettagli ed esempi, vedi Accesso ai dati pubblici.

Passaggi successivi

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