crea sottoscrizioni Cloud Storage

Questo documento descrive come creare un abbonamento a Cloud Storage. Puoi utilizzare la console Google Cloud, Google Cloud CLI, la libreria client oppure l'API Pub/Sub per creare un abbonamento a Cloud Storage.

Prima di iniziare

Prima di leggere questo documento, assicurati di acquisire familiarità con 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 relativi ai messaggi.

Ruoli e autorizzazioni richiesti

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

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

• Hai bisogno anche di autorizzazioni a livello di risorsa se le tue sottoscrizioni e gli argomenti in progetti diversi, come discusso più avanti in questa sezione.

• Per creare una sottoscrizione Cloud Storage, L'account di servizio Pub/Sub deve disporre dell'autorizzazione per scrivere un bucket Cloud Storage specifico e leggere i metadati del bucket. Per ulteriori informazioni informazioni su come concedere queste autorizzazioni, consulta le di questo documento.

Per ottenere le autorizzazioni necessarie per creare abbonamenti a Cloud Storage, chiedi all'amministratore di concederti Ruolo IAM dell'editor Pub/Sub (roles/pubsub.editor) nel progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.

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

Potresti anche riuscire a ottenere queste autorizzazioni con ruoli personalizzati e altri ruoli predefiniti.

Se hai bisogno di creare Cloud Storage sottoscrizioni in un progetto associate a un argomento in un altro chiedi all'amministratore dell'argomento di concederti anche l'editor Pub/Sub (roles/pubsub.editor) nell'argomento.

assegna ruoli di Cloud Storage all'account di servizio Pub/Sub

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

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

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

• Se devi concedere ruoli a livello di progetto, puoi concedere il ruolo Amministratore Storage (roles/storage.admin) per il progetto che contiene nel bucket Cloud Storage. Concedi questo ruolo ai Account di servizio Pub/Sub.

Per ulteriori informazioni su IAM di Cloud Storage, consulta Gestione di identità e accessi di Cloud Storage.

Proprietà delle sottoscrizioni Cloud Storage

Quando configuri un abbonamento a Cloud Storage, devi specificare le proprietà comuni a tutti i tipi di abbonamento e alcune altre Proprietà specifiche dell'abbonamento a Cloud Storage.

Proprietà delle sottoscrizioni comuni

Scopri di più sulle proprietà di abbonamento comuni che puoi impostare per tutte le sottoscrizioni.

Nome bucket

Prima di creare un bucket Cloud Storage, deve esistere già un bucket abbonamento a 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 disattivata.

Per creare un bucket Cloud Storage, consulta Crea bucket.

Prefisso, suffisso e data/ora del nome file

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

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

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

• <UTC-date-time> è una stringa personalizzabile generata automaticamente in base all'ora viene creato l'oggetto.

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

• <file-suffix> è il suffisso del nome file personalizzato. Questo campo è facoltativo. La 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 di il suffisso del nome file è _archive, il nome di un 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 è nel formato: <UTC-date-time>_<uuid>.

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

• È possibile modificare la modalità di visualizzazione di data e ora nel nome file:

  • Matcher data/ora obbligatori che puoi utilizzare solo una volta: year (YYYY o YY), mese (MM), giorno (DD), ora (hh), minuto (mm), secondo (ss). Ad esempio, YY-YYYY o MMM non è valido.

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

  • Se il formato data/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/ora nome file è YYYY-MM-DDThh_mm_ss-, il nome di un oggetto di esempio è prod_2023-09-25T04_10_00-uNiQuE_archive.

Batch di file

Le sottoscrizioni Cloud Storage ti consentono di decidere quando creare un nuovo file di output archiviato come oggetto in Cloud Storage di sincronizzare la directory di una VM con un bucket. Pub/Sub scrive un file di output quando uno dei sono soddisfatte le condizioni di raggruppamento specificate. Di seguito sono riportati i Condizioni di raggruppamento in batch di Cloud Storage:

• Durata massima batch di archiviazione. Questa impostazione è obbligatoria. La La sottoscrizione Cloud Storage scrive un nuovo file di output se viene superato il valore specificato per la durata massima. In caso contrario specifica 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 impostazione è facoltativa. La La sottoscrizione Cloud Storage scrive un nuovo file di output se è stato superato il valore massimo di byte specificato. Di seguito sono riportate le valori per i byte massimi:

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

Ad esempio, puoi configurare una durata massima di 6 minuti e per un massimo di 2 GB. Se al quarto minuto il file di output raggiunge di 2 GB, Pub/Sub finalizza il file precedente e inizia scrivere in un nuovo file.

Una sottoscrizione Cloud Storage potrebbe scrivere su più file in un a un bucket Cloud Storage contemporaneamente. Se hai configurato di creare un nuovo file ogni 6 minuti, potresti osservare più file Cloud Storage creati ogni 6 minuti.

In alcune situazioni, Pub/Sub potrebbe iniziare a scrivere in un nuovo prima dell'ora configurata dalle condizioni di raggruppamento dei file. Un file potrebbe anche superare il valore Max byte se la sottoscrizione riceve messaggi di dimensioni maggiori del valore "Max byte".

Formato file

Quando crei una sottoscrizione Cloud Storage, puoi specificare il formato dei file di output da archiviare bucket Cloud Storage come Text o Avro.

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

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

  • Scrivi metadati: questa opzione 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 nell'oggetto Avro di output, mentre tutte le altre proprietà dei messaggi diverse dai dati (ad esempio, una order_key, se presente) vengono aggiunte come voci nella mappa attributes.

    Se la funzionalità di scrittura dei metadati è disabilitata, solo il payload del messaggio viene scritto nell'oggetto Avro di output. Ecco lo schema Avro per i messaggi di output con i metadati di scrittura disabilitati:

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

    Ecco lo schema Avro per i messaggi di output con i 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 schema dell'argomento Pub/Sub a cui l'abbonamento è allegato quando scrivi file Avro.

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

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

    • Se sono abilitate le opzioni Utilizza schema argomento e Scrivi metadati, lo schema dell'argomento deve avere un oggetto Record nella directory principale. Pub/Sub espanderà 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());
    }
  }
}

Monitora abbonamenti

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

Puoi anche monitorare le sottoscrizioni all'interno di Pub/Sub.

Passaggi successivi

• Risolvi i problemi relativi a un abbonamento a Cloud Storage.

• Scopri di più su Cloud Storage.

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