Creare abbonamenti Cloud Storage

Questo documento descrive come creare una sottoscrizione Cloud Storage. Puoi utilizzare la console Google Cloud , Google Cloud CLI, la libreria client o l'API Pub/Sub per creare una sottoscrizione Cloud Storage.

Prima di iniziare

Prima di leggere questo documento, assicurati di conoscere quanto segue:

Ruoli e autorizzazioni richiesti

Per ottenere le autorizzazioni necessarie per creare un abbonamento Cloud Storage, chiedi all'amministratore di concederti il ruolo IAM Pub/Sub Editor (roles/pubsub.editor) nel progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene le autorizzazioni necessarie per creare un abbonamento Cloud Storage. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per creare un abbonamento a Cloud Storage sono necessarie le seguenti autorizzazioni:

  • pubsub.subscriptions.create sul progetto
  • pubsub.topics.attachSubscription sull'argomento

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Abbonamenti tra progetti

Se crei una sottoscrizione in un progetto per un argomento in un altro progetto, devi disporre dell'autorizzazione pubsub.subscriptions.create sul progetto in cui stai creando la sottoscrizione e dell'autorizzazione pubsub.topics.attachSubscription sull'argomento.

Concedi ruoli IAM al account di servizio

Pub/Sub utilizza un account di servizio Identity and Access Management (IAM) per accedere alle risorse Google Cloud . Per impostazione predefinita, utilizza il service agent Pub/Sub (service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com).

Per consentire a Pub/Sub di scrivere in Cloud Storage, il service account richiede i seguenti ruoli:

  • Creatore oggetti Storage (roles/storage.objectCreator)
  • Storage Legacy Bucket Reader (roles/storage.legacyBucketReader)

Puoi concedere le autorizzazioni al account di servizio per il progetto o per il bucket Cloud Storage, nel seguente modo:

Progetto

  1. Nella console Google Cloud , vai alla pagina Bucket.

    Vai a Bucket

  2. Seleziona Includi concessioni di ruoli fornite da Google.

  3. Trova la riga del account di servizio Cloud Pub/Sub e fai clic su Modifica entità.

  4. Fai clic su Aggiungi un altro ruolo e seleziona il ruolo Creatore oggetti Storage. Ripeti questo passaggio per il ruolo Storage Legacy Bucket Reader.

Per maggiori informazioni, consulta Concedi un ruolo IAM utilizzando la console.

Bucket Cloud Storage

  1. Nella Google Cloud console, vai a Bucket.

    Vai a Bucket

  2. Fai clic sul nome del bucket Cloud Storage a cui vuoi concedere l'autorizzazione.

  3. Nella pagina Dettagli bucket, fai clic sulla scheda Autorizzazioni.

  4. Nel riquadro Autorizzazioni, fai clic sulla scheda Visualizza per entità.

  5. Fai clic su Concedi l'accesso.

  6. Nel campo Nuove entità, inserisci l'identificatore del account di servizio nel seguente formato:

    service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com.

  7. Nell'elenco Assegna i ruoli, seleziona Creatore oggetti Storage.

  8. Fai clic su Aggiungi un altro ruolo e seleziona Storage Legacy Bucket Reader.

  9. Fai clic su Salva. All'entità vengono concessi i ruoli sulla risorsa.

Utilizzo di un account di servizio personalizzato

Se concedi i ruoli Storage Object Creator e Storage Legacy Bucket Reader al account di servizio Cloud Pub/Sub, qualsiasi utente con l'autorizzazione per creare un abbonamento nel tuo progetto può scrivere nel bucket Cloud Storage. Se vuoi fornire autorizzazioni più granulari, configura un service account gestito dall'utente.

Per configurare un service account gestito dall'utente per scrivere in Cloud Storage sono necessarie le seguenti autorizzazioni:

  • Il account di servizio gestito dall'utente deve disporre dei ruoli Storage Object Creator e Storage Legacy Bucket Reader.

  • Il account di servizio Cloud Pub/Sub deve disporre dell'autorizzazione iam.serviceAccounts.getAccessToken sul service account gestito dall'utente.

  • L'utente che crea l'abbonamento deve disporre dell'autorizzazione iam.serviceAccounts.actAs sul account di servizio gestito dall'utente.

Quando crei la sottoscrizione, specifica il account di servizio gestito dall'utente come service account di sottoscrizione.

Proprietà della sottoscrizione Cloud Storage

Gli abbonamenti Cloud Storage supportano tutte le proprietà comuni degli abbonamenti. Le sezioni seguenti descrivono le proprietà specifiche degli abbonamenti Cloud Storage.

Nome bucket

Un bucket Cloud Storage deve già esistere prima di creare una sottoscrizione Cloud Storage.

I messaggi vengono inviati in batch e archiviati nel bucket Cloud Storage. Un singolo batch o file viene archiviato come oggetto nel bucket.

Il bucket Cloud Storage deve avere Pagamenti a carico del richiedente disabilitato.

Per creare un bucket Cloud Storage, consulta Crea bucket.

Prefisso, suffisso e data/ora del nome file

I file Cloud Storage di output generati dall'abbonamento a Cloud Storage vengono archiviati come oggetti nel bucket Cloud Storage. Il nome dell'oggetto archiviato nel bucket Cloud Storage ha il seguente formato: <file-prefix><UTC-date-time>_<uuid><file-suffix>.

Il seguente elenco include i dettagli del formato del file e i campi che puoi personalizzare:

  • <file-prefix> è il prefisso personalizzato del nome file. Questo è un campo facoltativo.

  • <UTC-date-time> è una stringa personalizzabile generata automaticamente in base all'ora di creazione dell'oggetto.

  • <uuid> è una stringa casuale generata automaticamente per l'oggetto.

  • <file-suffix> è il suffisso personalizzato del nome file. Questo è un campo facoltativo. Il suffisso del nome file non può terminare con "/".

  • Puoi modificare il prefisso e il suffisso del nome file:

    • Ad esempio, se il valore del prefisso del nome file è prod_ e il valore del suffisso del nome file è _archive, un nome oggetto di esempio è prod_2023-09-25T04:10:00+00:00_uN1QuE_archive.

    • Se non specifichi il prefisso e il suffisso del nome file, il nome dell'oggetto archiviato nel bucket Cloud Storage ha il formato: <UTC-date-time>_<uuid>.

    • I requisiti di denominazione degli oggetti Cloud Storage si applicano anche al prefisso e al suffisso del nome file. Per maggiori informazioni, consulta Informazioni sugli oggetti Cloud Storage.

  • Puoi modificare la modalità di visualizzazione della data e dell'ora nel nome file:

    • Corrispondenze di data e ora obbligatorie che puoi utilizzare una sola volta: anno (YYYY o YY), mese (MM), giorno (DD), ora (hh), minuto (mm), secondo (ss). Ad esempio, YY-YYYY o MMM non sono validi.

    • Corrispondenze facoltative che puoi utilizzare una sola volta: separatore di data e ora (T) e offset del fuso orario (Z o +00:00).

    • Elementi facoltativi che puoi utilizzare più volte: trattino (-), trattino basso (_), due punti (:) e barra (/).

    • Ad esempio, se il valore del formato data e ora del nome file è YYYY-MM-DD/hh_mm_ssZ, un nome oggetto di esempio è prod_2023-09-25/04_10_00Z_uNiQuE_archive.

    • Se il formato data e ora del nome file termina con un carattere che non è un matcher, questo carattere sostituirà il separatore tra <UTC-date-time> e <uuid>. Ad esempio, se il valore del formato data e ora del nome file è YYYY-MM-DDThh_mm_ss-, un nome oggetto di esempio è prod_2023-09-25T04_10_00-uNiQuE_archive.

Batch di file

Gli abbonamenti a Cloud Storage ti consentono di decidere quando creare un nuovo file di output archiviato come oggetto nel bucket Cloud Storage. Pub/Sub scrive un file di output quando viene soddisfatta una delle condizioni di batch specificate. Di seguito sono riportate le condizioni di batching di Cloud Storage:

  • Durata massima batch di archiviazione. Questa è un'impostazione obbligatoria. Pub/Sub scrive un nuovo file di output se viene superato il valore specificato per la durata massima. La durata viene misurata dal momento in cui Pub/Sub inizia a scrivere in un nuovo file fino al momento in cui il file viene finalizzato. Ad esempio, se imposti la durata massima su 5 minuti, Pub/Sub finalizza il file al massimo 5 minuti dopo che ha iniziato a scriverlo. È possibile creare un nuovo file prima che sia trascorso il tempo massimo. Se non specifichi il valore, viene applicato un valore predefinito di 5 minuti. Di seguito sono riportati i valori applicabili per la durata massima:

    • Valore minimo = 1 minuto
    • Valore predefinito = 5 minuti
    • Valore massimo = 10 minuti

  • Byte massimi batch di archiviazione. Questa è un'impostazione facoltativa. L'abbonamento Cloud Storage scrive un nuovo file di output se viene superato il valore specificato di byte massimi. Di seguito sono riportati i valori applicabili per i byte massimi:

    • Valore minimo = 1 kB
    • Valore massimo = 10 GB

  • Messaggi massimi batch di archiviazione. Questa è un'impostazione facoltativa. L'abbonamento Cloud Storage scrive un nuovo file di output se viene superato il numero massimo di messaggi specificato. Di seguito sono riportati i valori applicabili per il numero massimo di messaggi:

    • Valore minimo = 1000

Ad esempio, puoi configurare la durata massima come 6 minuti e i byte massimi come 2 GB. Se al quarto minuto il file di output raggiunge una dimensione di 2 GB, Pub/Sub finalizza il file precedente e inizia a scrivere in un nuovo file.

Una sottoscrizione Cloud Storage potrebbe scrivere in più file in un bucket Cloud Storage contemporaneamente. Se hai configurato l'abbonamento in modo da creare un nuovo file ogni 6 minuti, potresti notare la creazione di più file Cloud Storage ogni 6 minuti.

In alcune situazioni, Pub/Sub potrebbe iniziare a scrivere in un nuovo file prima dell'ora configurata dalle condizioni di raggruppamento dei file. Un file potrebbe superare il valore Max bytes anche se l'abbonamento riceve messaggi più grandi del valore Max bytes.

Formato file

Quando crei un abbonamento Cloud Storage, puoi specificare il formato dei file di output da archiviare in un bucket Cloud Storage come Testo o Avro.

  • Testo: i messaggi vengono memorizzati come testo normale. Un carattere di nuova riga separa un messaggio dal messaggio precedente nel file. Vengono archiviati solo i payload dei messaggi, non gli attributi o altri metadati.

  • Avro: i messaggi vengono archiviati nel formato binario Apache Avro. Quando selezioni Avro, puoi attivare le seguenti proprietà aggiuntive:

    • Scrivi metadati: questa opzione ti consente di memorizzare i metadati del messaggio insieme al messaggio. I metadati come i campi subscription_name, message_id, publish_time e attributes vengono scritti nei campi di primo livello nell'oggetto Avro di output, mentre tutte le altre proprietà del messaggio diverse dai dati (ad esempio, una chiave di ordinamento, se presente) vengono aggiunte come voci nella mappa attributes.

      Se l'opzione Scrivi metadati è disattivata, nell'oggetto Avro di output viene scritto solo il payload del messaggio. Ecco lo schema Avro per i messaggi di output con l'opzione Scrivi metadati disattivata:

      {
  "type": "record",
  "namespace": "com.google.pubsub",
  "name": "PubsubMessage",
  "fields": [
    { "name": "data", "type": "bytes" }
  ]
}

      Ecco lo schema Avro per i messaggi di output con l'opzione Scrivi metadati abilitata:

      {
  "type": "record",
  "namespace": "com.google.pubsub",
  "name": "PubsubMessageWithMetadata",
  "fields": [
    { "name": "subscription_name", "type": "string" },
    { "name": "message_id", "type": "string"  },
    { "name": "publish_time", "type": {
        "type": "long",
        "logicalType": "timestamp-micros"
      }
    },
    { "name": "attributes", "type": { "type": "map", "values": "string" } },
    { "name": "data", "type": "bytes" }
  ]
}

    • Utilizza schema argomento: questa opzione consente a Pub/Sub di utilizzare lo schema dell'argomento Pub/Sub a cui è collegata la sottoscrizione durante la scrittura dei file Avro.

      Quando utilizzi questa opzione, ricorda di controllare i seguenti requisiti aggiuntivi:

      • Lo schema dell'argomento deve essere nel formato Apache Avro.

      • Se sono abilitate sia l'opzione Usa schema dell'argomento sia l'opzione Scrivi metadati, lo schema dell'argomento deve avere un oggetto Record alla radice. Pub/Sub espanderà l'elenco dei campi del record per includere i campi dei metadati. Di conseguenza, il record non può contenere campi con lo stesso nome dei campi dei metadati (subscription_name, message_id, publish_time o attributes).

Service account

Hai a disposizione le seguenti opzioni per scrivere messaggi in un bucket Cloud Storage:

  • Configura un service account personalizzato in modo che solo gli utenti che dispongono dell'autorizzazione iam.serviceAccounts.actAs sul account di servizio possano creare un abbonamento che scrive nel bucket. Un ruolo di esempio che include l'autorizzazione iam.serviceAccounts.actAs è il ruolo Utente service account (roles/iam.serviceAccountUser).

  • Utilizza l'agente di servizio Pub/Sub predefinito che consente a qualsiasi utente con la possibilità di creare sottoscrizioni nel progetto di creare una sottoscrizione che scrive nel bucket. Il service agent Pub/Sub è l'impostazione predefinita quando non specifichi un account di servizio personalizzato.

Crea una sottoscrizione Cloud Storage

Console

  1. Nella console Google Cloud , vai alla pagina Sottoscrizioni.

    Vai ad Abbonamenti

  2. Fai clic su Crea sottoscrizione.

  3. Per il campo ID sottoscrizione, inserisci un nome.

    Per informazioni su come denominare un abbonamento, consulta le linee guida per denominare un argomento o un abbonamento.

  4. Scegli o crea un argomento dal menu a discesa.

    La sottoscrizione riceve i messaggi dall'argomento.

    Per informazioni su come creare un argomento, vedi Creare e gestire argomenti.

  5. Seleziona Tipo di consegna come Scrivi in Cloud Storage.

  6. Per il bucket Cloud Storage, fai clic su Sfoglia.

    • Puoi selezionare un bucket esistente da qualsiasi progetto appropriato.

    • Puoi anche fare clic sull'icona di creazione e seguire le istruzioni sullo schermo per creare un nuovo bucket.

      Dopo aver creato il bucket, selezionalo per l'abbonamento a Cloud Storage.

      Per saperne di più su come creare un bucket, consulta Crea bucket.

    Quando specifichi il bucket, Pub/Sub verifica le autorizzazioni appropriate sul bucket per il service agent Pub/Sub. Se si verificano problemi di autorizzazioni, viene visualizzato un messaggio simile al seguente: Unable to verify if the Pub/Sub service agent has write permissions on this bucket. You may be lacking permissions to view or set permissions.

  7. Se si verificano problemi di autorizzazione, fai clic su Imposta autorizzazione e segui le istruzioni sullo schermo.

    In alternativa, segui le istruzioni riportate in Assegna ruoli Cloud Storage all'agente di servizio Pub/Sub.

  8. Per Formato file, seleziona Testo o Avro.

    Se selezioni Avro, puoi anche specificare facoltativamente se vuoi archiviare i metadati dei messaggi nell'output.

    Per ulteriori informazioni sulle due opzioni, inclusa l'opzione dei metadati dei messaggi per il formato Avro, vedi Formato file.

  9. (Facoltativo) Puoi specificare il prefisso, il suffisso e la data/ora del nome file per tutti i file da scrivere nel bucket Cloud Storage. Un file viene archiviato come oggetto nel bucket.

    Per ulteriori informazioni su come impostare il prefisso, il suffisso e la data e l'ora del file, vedi Prefisso, suffisso e data e ora del nome file.

  10. Per il raggruppamento dei file, specifica un tempo massimo da trascorrere prima di creare un nuovo file.

    Se vuoi, puoi anche impostare le dimensioni massime dei file o il numero massimo di messaggi per i file.

    Per saperne di più su entrambe le opzioni di batch di file, vedi Batch di file.

  11. Ti consigliamo vivamente di attivare la coda di messaggi non recapitabili per gestire gli errori dei messaggi.

    Per saperne di più, consulta la sezione Argomento lettera morta.

  12. Puoi mantenere le altre impostazioni predefinite e fare clic su Crea.

gcloud

  1. Nella console Google Cloud , attiva Cloud Shell.

    Attiva Cloud Shell

    Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell e viene visualizzato un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installata e con valori già impostati per il progetto corrente. L'inizializzazione della sessione può richiedere alcuni secondi.

  2. Per creare una sottoscrizione Cloud Storage, esegui il comando gcloud pubsub subscriptions create. 
    gcloud pubsub subscriptions create SUBSCRIPTION_ID \
    --topic=TOPIC_ID \
    --cloud-storage-bucket=BUCKET_NAME \
    --cloud-storage-file-prefix=CLOUD_STORAGE_FILE_PREFIX \
    --cloud-storage-file-suffix=CLOUD_STORAGE_FILE_SUFFIX \
    --cloud-storage-file-datetime-format=CLOUD_STORAGE_FILE_DATETIME_FORMAT \
    --cloud-storage-max-duration=CLOUD_STORAGE_MAX_DURATION \
    --cloud-storage-max-bytes=CLOUD_STORAGE_MAX_BYTES \
    --cloud-storage-max-messages=CLOUD_STORAGE_MAX_MESSAGES \
    --cloud-storage-output-format=CLOUD_STORAGE_OUTPUT_FORMAT \
    --cloud-storage-write-metadata
    --cloud-storage-use-topic-schema

    Se vuoi utilizzare un account di servizio personalizzato, forniscilo come argomento aggiuntivo:

    gcloud pubsub subscriptions create SUBSCRIPTION_ID \
    --topic=TOPIC_ID \
    --cloud-storage-bucket=BUCKET_NAME \
    --cloud-storage-file-prefix=CLOUD_STORAGE_FILE_PREFIX \
    --cloud-storage-file-suffix=CLOUD_STORAGE_FILE_SUFFIX \
    --cloud-storage-file-datetime-format=CLOUD_STORAGE_FILE_DATETIME_FORMAT \
    --cloud-storage-max-duration=CLOUD_STORAGE_MAX_DURATION \
    --cloud-storage-max-bytes=CLOUD_STORAGE_MAX_BYTES \
    --cloud-storage-max-messages=CLOUD_STORAGE_MAX_MESSAGES \
    --cloud-storage-output-format=CLOUD_STORAGE_OUTPUT_FORMAT \
    --cloud-storage-write-metadata
    --cloud-storage-use-topic-schema
    --cloud-storage-service-account-email=SERVICE_ACCOUNT_NAME

    Nel comando sono obbligatori solo SUBSCRIPTION_ID, il flag --topic e il flag --cloud-storage-bucket. I flag rimanenti sono facoltativi e possono essere omessi.

    Sostituisci quanto segue:

    • SUBSCRIPTION_ID: il nome o l'ID del nuovo abbonamento Cloud Storage.
    • TOPIC_ID: il nome o l'ID dell'argomento.
    • BUCKET_NAME: specifica il nome di un bucket esistente. Ad esempio, prod_bucket. Il nome del bucket non deve includere l'ID progetto. Per creare un bucket, consulta Crea bucket.
    • CLOUD_STORAGE_FILE_PREFIX: specifica il prefisso per il nome file Cloud Storage. Ad esempio, log_events_.
    • CLOUD_STORAGE_FILE_SUFFIX: specifica il suffisso per il nome del file Cloud Storage. Ad esempio, .txt.
    • CLOUD_STORAGE_FILE_DATETIME_FORMAT: Specifica il formato della data e dell'ora per il nome del file Cloud Storage. Ad esempio, YYYY-MM-DD/hh_mm_ssZ.
    • CLOUD_STORAGE_MAX_DURATION: la durata massima che può trascorrere prima che venga creato un nuovo file Cloud Storage. Il valore deve essere compreso tra 1 e 10 metri. Ad esempio, 5m.
    • CLOUD_STORAGE_MAX_BYTES: il numero massimo di byte che possono essere scritti in un file Cloud Storage prima che venga creato un nuovo file. Il valore deve essere compreso tra 1 KB e 10 GB. Ad esempio, 20MB.
    • CLOUD_STORAGE_MAX_MESSAGES: il numero massimo di messaggi che possono essere scritti in un file Cloud Storage prima che venga creato un nuovo file. Il valore deve essere maggiore o uguale a 1000. Ad esempio, 100000.
    • CLOUD_STORAGE_OUTPUT_FORMAT: il formato di output per i dati scritti in Cloud Storage. I valori sono i seguenti:
      • text: I messaggi sono scritti come testo non formattato, separati da un carattere di nuova riga.
      • avro: I messaggi vengono scritti come binario Avro. --cloud-storage-write-metadata e --cloud-storage-use-topic-schema influiscono solo sugli abbonamenti con formato di output avro.
    • SERVICE_ACCOUNT_NAME: specifica il nome dell'account di servizio da utilizzare per scrivere in Cloud Storage.

C++

Prima di provare questo esempio, segui le istruzioni di configurazione di C++ nella guida rapida di Pub/Sub per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub C++.

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

namespace pubsub = ::google::cloud::pubsub;
namespace pubsub_admin = ::google::cloud::pubsub_admin;
[](pubsub_admin::SubscriptionAdminClient client,
   std::string const& project_id, std::string const& topic_id,
   std::string const& subscription_id, std::string const& bucket) {
  google::pubsub::v1::Subscription request;
  request.set_name(
      pubsub::Subscription(project_id, subscription_id).FullName());
  request.set_topic(pubsub::Topic(project_id, topic_id).FullName());
  request.mutable_cloud_storage_config()->set_bucket(bucket);
  auto sub = client.CreateSubscription(request);
  if (!sub) {
    if (sub.status().code() == google::cloud::StatusCode::kAlreadyExists) {
      std::cout << "The subscription already exists\n";
      return;
    }
    throw std::move(sub).status();
  }

  std::cout << "The subscription was successfully created: "
            << sub->DebugString() << "\n";
}

C#

Prima di provare questo esempio, segui le istruzioni di configurazione di C# nella guida rapida di Pub/Sub per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub C#.

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


using Google.Cloud.PubSub.V1;
using Google.Protobuf.WellKnownTypes;
using System;

public class CreateCloudStorageSubscriptionSample
{
    public Subscription CreateCloudStorageSubscription(string projectId, string topicId, string subscriptionId,
        string bucket, string filenamePrefix, string filenameSuffix, TimeSpan maxDuration)
    {
        SubscriberServiceApiClient subscriber = SubscriberServiceApiClient.Create();
        TopicName topicName = TopicName.FromProjectTopic(projectId, topicId);
        SubscriptionName subscriptionName = SubscriptionName.FromProjectSubscription(projectId, subscriptionId);

        var subscriptionRequest = new Subscription
        {
            SubscriptionName = subscriptionName,
            TopicAsTopicName = topicName,
            CloudStorageConfig = new CloudStorageConfig
            {
                Bucket = bucket,
                FilenamePrefix = filenamePrefix,
                FilenameSuffix = filenameSuffix,
                MaxDuration = Duration.FromTimeSpan(maxDuration)
            }
        };
        var subscription = subscriber.CreateSubscription(subscriptionRequest);
        return subscription;
    }
}

Go

Prima di provare questo esempio, segui le istruzioni di configurazione di Go nella guida rapida di Pub/Sub per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Go.

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

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/pubsub/v2"
	"cloud.google.com/go/pubsub/v2/apiv1/pubsubpb"
	"google.golang.org/protobuf/types/known/durationpb"
)

// createCloudStorageSubscription creates a Pub/Sub subscription that exports messages to Cloud Storage.
func createCloudStorageSubscription(w io.Writer, projectID, topic, subscription, bucket string) error {
	// projectID := "my-project-id"
	// topic := "projects/my-project-id/topics/my-topic"
	// subscription := "projects/my-project/subscriptions/my-sub"
	// bucket := "my-bucket" // bucket must not have the gs:// prefix
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %w", err)
	}
	defer client.Close()

	sub, err := client.SubscriptionAdminClient.CreateSubscription(ctx, &pubsubpb.Subscription{
		Name:  subscription,
		Topic: topic,
		CloudStorageConfig: &pubsubpb.CloudStorageConfig{
			Bucket:         bucket,
			FilenamePrefix: "log_events_",
			FilenameSuffix: ".avro",
			OutputFormat: &pubsubpb.CloudStorageConfig_AvroConfig_{
				AvroConfig: &pubsubpb.CloudStorageConfig_AvroConfig{
					WriteMetadata: true,
				},
			},
			MaxDuration: durationpb.New(1 * time.Minute),
			MaxBytes:    1e8,
		},
	})
	if err != nil {
		return fmt.Errorf("failed to create cloud storage sub: %w", err)
	}
	fmt.Fprintf(w, "Created Cloud Storage subscription: %v\n", sub)

	return nil
}

Java

Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida di Pub/Sub per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Java.

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

import com.google.cloud.pubsub.v1.SubscriptionAdminClient;
import com.google.protobuf.Duration;
import com.google.pubsub.v1.CloudStorageConfig;
import com.google.pubsub.v1.ProjectSubscriptionName;
import com.google.pubsub.v1.ProjectTopicName;
import com.google.pubsub.v1.Subscription;
import java.io.IOException;

public class CreateCloudStorageSubscriptionExample {
  public static void main(String... args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String topicId = "your-topic-id";
    String subscriptionId = "your-subscription-id";
    String bucket = "your-bucket";
    String filenamePrefix = "log_events_";
    String filenameSuffix = ".text";
    Duration maxDuration = Duration.newBuilder().setSeconds(300).build();

    createCloudStorageSubscription(
        projectId, topicId, subscriptionId, bucket, filenamePrefix, filenameSuffix, maxDuration);
  }

  public static void createCloudStorageSubscription(
      String projectId,
      String topicId,
      String subscriptionId,
      String bucket,
      String filenamePrefix,
      String filenameSuffix,
      Duration maxDuration)
      throws IOException {
    try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {

      ProjectTopicName topicName = ProjectTopicName.of(projectId, topicId);
      ProjectSubscriptionName subscriptionName =
          ProjectSubscriptionName.of(projectId, subscriptionId);

      CloudStorageConfig cloudStorageConfig =
          CloudStorageConfig.newBuilder()
              .setBucket(bucket)
              .setFilenamePrefix(filenamePrefix)
              .setFilenameSuffix(filenameSuffix)
              .setMaxDuration(maxDuration)
              .build();

      Subscription subscription =
          subscriptionAdminClient.createSubscription(
              Subscription.newBuilder()
                  .setName(subscriptionName.toString())
                  .setTopic(topicName.toString())
                  .setCloudStorageConfig(cloudStorageConfig)
                  .build());

      System.out.println("Created a CloudStorage subscription: " + subscription.getAllFields());
    }
  }
}

Node.js

Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella guida rapida di Pub/Sub per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Node.js.

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

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicName = 'YOUR_TOPIC_NAME';
// const subscriptionName = 'YOUR_SUBSCRIPTION_NAME';
// const bucket = 'YOUR_BUCKET_ID';
// const filenamePrefix = 'YOUR_FILENAME_PREFIX';
// const filenameSuffix = 'YOUR_FILENAME_SUFFIX';
// const maxDuration = 60;

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

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function createCloudStorageSubscription(
  topicName,
  subscriptionName,
  bucket,
  filenamePrefix,
  filenameSuffix,
  maxDuration,
) {
  const options = {
    cloudStorageConfig: {
      bucket,
      filenamePrefix,
      filenameSuffix,
      maxDuration: {
        seconds: maxDuration,
      },
    },
  };

  await pubSubClient
    .topic(topicName)
    .createSubscription(subscriptionName, options);

  console.log(
    `Created subscription ${subscriptionName} with a cloud storage configuration.`,
  );
}

Node.js

Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella guida rapida di Pub/Sub per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Node.js.

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

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicName = 'YOUR_TOPIC_NAME';
// const subscriptionName = 'YOUR_SUBSCRIPTION_NAME';
// const bucket = 'YOUR_BUCKET_ID';
// const filenamePrefix = 'YOUR_FILENAME_PREFIX';
// const filenameSuffix = 'YOUR_FILENAME_SUFFIX';
// const maxDuration = 60;

// Imports the Google Cloud client library
import {CreateSubscriptionOptions, PubSub} from '@google-cloud/pubsub';

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function createCloudStorageSubscription(
  topicName: string,
  subscriptionName: string,
  bucket: string,
  filenamePrefix: string,
  filenameSuffix: string,
  maxDuration: number,
) {
  const options: CreateSubscriptionOptions = {
    cloudStorageConfig: {
      bucket,
      filenamePrefix,
      filenameSuffix,
      maxDuration: {
        seconds: maxDuration,
      },
    },
  };

  await pubSubClient
    .topic(topicName)
    .createSubscription(subscriptionName, options);

  console.log(
    `Created subscription ${subscriptionName} with a cloud storage configuration.`,
  );
}

PHP

Prima di provare questo esempio, segui le istruzioni di configurazione di PHP nella guida rapida di Pub/Sub per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub PHP.

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

use Google\Cloud\PubSub\PubSubClient;

/**
 * Creates a Pub/Sub GCS subscription.
 *
 * @param string $projectId  The Google project ID.
 * @param string $topicName  The Pub/Sub topic name.
 * @param string $subscriptionName  The Pub/Sub subscription name.
 * @param string $bucket The Cloud Storage bucket name without any prefix like "gs://".
 */
function create_cloud_storage_subscription($projectId, $topicName, $subscriptionName, $bucket)
{
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);
    $topic = $pubsub->topic($topicName);
    $subscription = $topic->subscription($subscriptionName);
    $config = ['bucket' => $bucket];
    $subscription->create([
        'cloudStorageConfig' => $config
    ]);

    printf('Subscription created: %s' . PHP_EOL, $subscription->name());
}

Python

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di Pub/Sub per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Python.

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

from google.cloud import pubsub_v1
from google.protobuf import duration_pb2

# TODO(developer)
# project_id = "your-project-id"
# topic_id = "your-topic-id"
# subscription_id = "your-subscription-id"
# bucket = "my-bucket"

filename_prefix = "log_events_"
filename_suffix = ".avro"
# Either CloudStorageConfig.AvroConfig or CloudStorageConfig.TextConfig
# defaults to TextConfig
avro_config = pubsub_v1.types.CloudStorageConfig.AvroConfig(write_metadata=True)

publisher = pubsub_v1.PublisherClient()
subscriber = pubsub_v1.SubscriberClient()
topic_path = publisher.topic_path(project_id, topic_id)
subscription_path = subscriber.subscription_path(project_id, subscription_id)
max_duration = duration_pb2.Duration()
max_duration.FromSeconds(300)

cloudstorage_config = pubsub_v1.types.CloudStorageConfig(
    bucket=bucket,
    filename_prefix=filename_prefix,
    filename_suffix=filename_suffix,
    avro_config=avro_config,
    # Min 1 minutes, max 10 minutes
    max_duration=max_duration,
    # Min 1 KB, max 10 GiB
    max_bytes=10000000,
)

# Wrap the subscriber in a 'with' block to automatically call close() to
# close the underlying gRPC channel when done.
with subscriber:
    subscription = subscriber.create_subscription(
        request={
            "name": subscription_path,
            "topic": topic_path,
            "cloud_storage_config": cloudstorage_config,
        }
    )

print(f"CloudStorage subscription created: {subscription}.")
print(f"Bucket for subscription is: {bucket}")
print(f"Prefix is: {filename_prefix}")
print(f"Suffix is: {filename_suffix}")

Monitorare una sottoscrizione Cloud Storage

Cloud Monitoring fornisce una serie di metriche per monitorare gli abbonamenti.

Per un elenco di tutte le metriche disponibili relative a Pub/Sub e le relative descrizioni, consulta la documentazione di Monitoring per Pub/Sub.

Puoi anche monitorare gli abbonamenti all'interno di Pub/Sub.

Passaggi successivi