Creare abbonamenti Cloud Storage

Questo documento descrive come creare un abbonamento a 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:

• Come funziona un abbonamento a Cloud Storage.
• Come funziona Cloud Storage e come creare e gestire i bucket Cloud Storage.
• Come configurare un argomento messaggi non recapitabili per gestire gli errori dei messaggi.

Ruoli e autorizzazioni richiesti

Di seguito è riportato un elenco di linee guida relative a ruoli e autorizzazioni:

• Per creare un abbonamento, devi configurare il controllo dell'accesso a livello di progetto.

• Sono inoltre necessarie autorizzazioni a livello di risorsa se le iscrizioni e gli argomenti si trovano in progetti diversi, come spiegato più avanti in questa sezione.

• Per creare un abbonamento Cloud Storage, l'account di servizio Pub/Sub deve disporre dell'autorizzazione per scrivere nel bucket Cloud Storage specifico e per leggere i metadati del bucket. Per ulteriori informazioni su come concedere queste autorizzazioni, consulta la sezione successiva di questo documento.

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

Questo ruolo predefinito contiene le autorizzazioni necessarie per creare abbonamenti Cloud Storage. Per visualizzare le autorizzazioni esatte richieste, espandi la sezione Autorizzazioni richieste:

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

Se devi creare abbonamenti Cloud Storage in un progetto associati a un argomento in un altro progetto, chiedi all'amministratore dell'argomento di concederti anche il ruolo IAM Editor Pub/Sub(roles/pubsub.editor) per l'argomento.

Assegna i ruoli Cloud Storage all'account di servizio Pub/Sub

Alcuni servizi Google Cloud dispongono di account di servizio gestiti da Google Cloud che consentono ai servizi di accedere alle tue risorse. Questi account di servizio sono noti come agenti di servizio. Pub/Sub crea e gestisce un account di servizio per ogni progetto nel formatoservice-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com.

Per creare un abbonamento Cloud Storage, l'account di servizio Pub/Sub deve disporre dell'autorizzazione per scrivere nel bucket Cloud Storage specifico e leggere i metadati del bucket. Scegli una delle seguenti procedure:

• Concedi le autorizzazioni a livello di bucket. Al bucket Cloud Storage specifico, concedi all'account di servizio Pub/Sub il ruolo Creatore oggetti Storage (roles/storage.objectCreator) e il ruolo Lettore di bucket legacy Storage (roles/storage.legacyBucketReader).

• Se devi concedere i ruoli a livello di progetto, puoi concedere il ruolo Amministratore archiviazione (roles/storage.admin) al progetto contenente il bucket Cloud Storage. Concedi questo ruolo all'account di servizio Pub/Sub.

Per ulteriori informazioni su Cloud Storage IAM, consulta Identity and Access Management (IAM) di Cloud Storage.

Proprietà dell'abbonamento a Cloud Storage

Quando configuri un abbonamento a Cloud Storage, devi specificare le proprietà comuni a tutti i tipi di abbonamento e alcune proprietà aggiuntive specifiche per l'abbonamento a Cloud Storage.

Proprietà comuni degli abbonamenti

Scopri le proprietà comuni degli abbonamenti che puoi impostare su tutti gli abbonamenti.

Nome bucket

Prima di creare un abbonamento Cloud Storage, deve già esistere un bucket 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 la funzionalità Pagamento a carico del richiedente disabilitata.

Per creare un bucket Cloud Storage, consulta Creare bucket.

Prefisso, suffisso e data e ora del nome file

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

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

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

• <UTC-date-time> è una stringa generata automaticamente personalizzabile in base al momento della creazione dell'oggetto.

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

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

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

  • Ad esempio, se il valore del prefisso del nome del file è prod_ e il valore del suffisso del nome del file è _archive, un nome di 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 memorizzato nel bucket Cloud Storage ha il seguente formato: <UTC-date-time>_<uuid>.

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

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

  • Confronti datetime obbligatori 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.

  • Confronti facoltativi che puoi utilizzare una sola volta: separatore data/ora (T) e differenza di 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 del file è YYYY-MM-DD/hh_mm_ssZ, un nome di oggetto di esempio è prod_2023-09-25/04_10_00Z_uNiQuE_archive.

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

Raggruppamento di file

Le iscrizioni 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 raggruppamento specificate. Di seguito sono riportate le condizioni di raggruppamento di Cloud Storage:

• Durata massima del batch di archiviazione. Questa è un'impostazione obbligatoria. L'abbonamento Cloud Storage scrive un nuovo file di output se viene superato il valore specificato per la durata massima. Se non lo specifichi, 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 GiB

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

  • Valore minimo = 1000

Ad esempio, puoi configurare la durata massima come 6 minuti e il numero massimo di byte come 2 GB. Se al quarto minuto il file di output raggiunge le dimensioni di 2 GB, Pub/Sub completa il file precedente e inizia a scrivere in un nuovo file.

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

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

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 in testo normale. Un carattere di a capo 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 in formato binario Apache Avro. Quando selezioni Avro, puoi attivare le seguenti proprietà aggiuntive:

  • Scrivi metadati: questa opzione ti consente di archiviare 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 dell'oggetto Avro di output, mentre tutte le altre proprietà del messaggio diverse dai dati (ad esempio, un valore ordering_key, se presente) vengono aggiunte come voci nella mappa attributes.

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

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

    Ecco lo schema Avro per i messaggi di output con metadati di scrittura abilitati:

    {
      "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 è associata la sottoscrizione durante la scrittura dei file Avro.

    Quando utilizzi questa opzione, ricordati di verificare i seguenti requisiti aggiuntivi:

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

    • Se sono abilitati sia Utilizza schema dell'argomento sia Scrivi metadati, lo schema dell'argomento deve avere un oggetto Record alla radice. Pub/Sub espande l'elenco dei campi del record in modo da 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).

Crea una sottoscrizione Cloud Storage

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

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

	"cloud.google.com/go/pubsub"
)

// createCloudStorageSubscription creates a Pub/Sub subscription that exports messages to Cloud Storage.
func createCloudStorageSubscription(w io.Writer, projectID, subID string, topic *pubsub.Topic, bucket string) error {
	// projectID := "my-project-id"
	// subID := "my-sub"
	// topic of type https://godoc.org/cloud.google.com/go/pubsub#Topic
	// note bucket should not have the gs:// prefix
	// bucket := "my-bucket"
	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.CreateSubscription(ctx, subID, pubsub.SubscriptionConfig{
		Topic: topic,
		CloudStorageConfig: pubsub.CloudStorageConfig{
			Bucket:         bucket,
			FilenamePrefix: "log_events_",
			FilenameSuffix: ".avro",
			OutputFormat:   &pubsub.CloudStorageOutputFormatAvroConfig{WriteMetadata: true},
			MaxDuration:    1 * time.Minute,
			MaxBytes:       1e8,
		},
	})
	if err != nil {
		return fmt.Errorf("client.CreateSubscription: %w", err)
	}
	fmt.Fprintf(w, "Created Cloud Storage subscription: %v\n", sub)

	return nil
}

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

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 monitoraggio per Pub/Sub.

Puoi anche monitorare le iscrizioni dall'interno di Pub/Sub.

Passaggi successivi

• Risolvi i problemi relativi a un abbonamento Cloud Storage.

• Scopri di più su Cloud Storage.

• Controlla i prezzi di Pub/Sub, incluso l'abbonamento a Cloud Storage.