Crea suscripciones a Cloud Storage

En este documento, se describe cómo crear una suscripción a Cloud Storage. Puedes usar la consola de Google Cloud , Google Cloud CLI, la biblioteca cliente o la API de Pub/Sub para crear una suscripción a Cloud Storage.

Antes de comenzar

Antes de leer este documento, asegúrate de estar familiarizado con lo siguiente:

Roles y permisos requeridos

Para obtener los permisos que necesitas para crear una suscripción de Cloud Storage, pídele a tu administrador que te otorgue el rol de IAM Editor de Pub/Sub (roles/pubsub.editor) en el proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene los permisos necesarios para crear una suscripción a Cloud Storage. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para crear una suscripción a Cloud Storage:

  • pubsub.subscriptions.create en el proyecto
  • pubsub.topics.attachSubscription sobre el tema

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Suscripciones entre proyectos

Si creas una suscripción en un proyecto para un tema en otro proyecto, debes tener el permiso pubsub.subscriptions.create en el proyecto en el que creas la suscripción y el permiso pubsub.topics.attachSubscription en el tema.

Otorga roles de IAM a la cuenta de servicio

Pub/Sub usa una cuenta de servicio de Identity and Access Management (IAM) para acceder a los recursos de Google Cloud . De forma predeterminada, usa el agente de servicio de Pub/Sub (service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com).

Para permitir que Pub/Sub escriba en Cloud Storage, la cuenta de servicio requiere los siguientes roles:

  • Creador de objetos de almacenamiento (roles/storage.objectCreator)
  • Lector de buckets heredados de almacenamiento (roles/storage.legacyBucketReader)

Puedes otorgar permisos a la cuenta de servicio para el proyecto o el bucket de Cloud Storage de la siguiente manera:

Proyecto

  1. En la consola de Google Cloud , ve a la página Buckets.

    Ir a Buckets

  2. Selecciona Incluir asignaciones de roles proporcionadas por Google.

  3. Busca la fila de la cuenta de servicio de Cloud Pub/Sub y haz clic en Editar principal.

  4. Haz clic en Agregar otro rol y selecciona el rol Creador de objetos de almacenamiento. Repite este paso para la función Lector de depósitos heredados de almacenamiento.

Para obtener más información, consulta Otorga un rol de IAM con la consola.

Bucket de Cloud Storage

  1. En la consola de Google Cloud , ve a Buckets.

    Ir a Buckets

  2. Haz clic en el nombre del bucket de Cloud Storage al que deseas otorgar permiso.

  3. En la página Detalles del bucket, haz clic en la pestaña Permisos.

  4. En el panel Permisos, haz clic en la pestaña Ver por principales.

  5. Haz clic en Otorgar acceso.

  6. En el campo Principales nuevas, ingresa el identificador de la cuenta de servicio con el siguiente formato:

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

  7. En la lista Asignar roles, selecciona Creador de objetos de Storage.

  8. Haz clic en Agregar otro rol y selecciona Lector de buckets heredados de Storage.

  9. Haz clic en Guardar. A la principal se le otorgan los roles en el recurso.

Usar una cuenta de servicio personalizada

Si otorgas los roles de creador de objetos de Storage y lector de buckets heredados de Storage a la cuenta de servicio de Cloud Pub/Sub, cualquier usuario que tenga permiso para crear una suscripción en tu proyecto podrá escribir en el bucket de Cloud Storage. Si deseas proporcionar permisos más detallados, configura una cuenta de servicio administrada por el usuario.

Se requieren los siguientes permisos para configurar una cuenta de servicio administrada por el usuario para escribir en Cloud Storage:

  • La cuenta de servicio administrada por el usuario debe tener los roles de creador de objetos de almacenamiento y lector de buckets heredados de Storage.

  • La cuenta de servicio de Cloud Pub/Sub debe tener el permiso iam.serviceAccounts.getAccessToken en la cuenta de servicio administrada por el usuario.

  • El usuario que crea la suscripción debe tener el permiso iam.serviceAccounts.actAs en la cuenta de servicio administrada por el usuario.

Cuando crees la suscripción, especifica la cuenta de servicio administrada por el usuario como la cuenta de servicio de suscripción.

Propiedades de la suscripción a Cloud Storage

Las suscripciones de Cloud Storage admiten todas las propiedades de suscripción comunes. En las siguientes secciones, se describen las propiedades específicas de las suscripciones de Cloud Storage.

Nombre del bucket

Ya debe existir un bucket de Cloud Storage antes de que crees una suscripción de Cloud Storage.

Los mensajes se envían en lotes y se almacenan en el bucket de Cloud Storage. Un solo lote o archivo se almacena como un objeto en el bucket.

El bucket de Cloud Storage debe tener inhabilitada la opción Pagos del solicitante.

Para crear un bucket de Cloud Storage, consulta Crea buckets.

Prefijo, sufijo y fecha y hora del nombre de archivo

Los archivos de salida de Cloud Storage que genera la suscripción a Cloud Storage se almacenan como objetos en el bucket de Cloud Storage. El nombre del objeto almacenado en el bucket de Cloud Storage tiene el siguiente formato: <file-prefix><UTC-date-time>_<uuid><file-suffix>.

En la siguiente lista, se incluyen detalles sobre el formato del archivo y los campos que puedes personalizar:

  • <file-prefix> es el prefijo del nombre de archivo personalizado. Este paso es opcional,

  • <UTC-date-time> es una cadena personalizable que se genera automáticamente según la hora en que se crea el objeto.

  • <uuid> es una cadena aleatoria generada automáticamente para el objeto.

  • <file-suffix> es el sufijo del nombre de archivo personalizado. Este paso es opcional, El sufijo del nombre de archivo no puede terminar en "/".

  • Puedes cambiar el prefijo y el sufijo del nombre de archivo:

    • Por ejemplo, si el valor del prefijo del nombre de archivo es prod_ y el valor del sufijo del nombre de archivo es _archive, un nombre de objeto de muestra es prod_2023-09-25T04:10:00+00:00_uN1QuE_archive.

    • Si no especificas el prefijo y el sufijo del nombre de archivo, el nombre del objeto almacenado en el bucket de Cloud Storage tendrá el siguiente formato: <UTC-date-time>_<uuid>.

    • Los requisitos para nombrar objetos de Cloud Storage también se aplican al prefijo y al sufijo del nombre de archivo. Para obtener más información, consulta Acerca de los objetos de Cloud Storage.

  • Puedes cambiar la forma en que se muestran la fecha y la hora en el nombre del archivo:

    • Se requieren comparadores de fecha y hora que puedes usar solo una vez: año (YYYY o YY), mes (MM), día (DD), hora (hh), minuto (mm) y segundo (ss). Por ejemplo, YY-YYYY o MMM no son válidos.

    • Coincidencias opcionales que puedes usar solo una vez: separador de fecha y hora (T) y compensación de zona horaria (Z o +00:00).

    • Elementos opcionales que puedes usar varias veces: guion (-), guion bajo (_), dos puntos (:) y barra diagonal (/).

    • Por ejemplo, si el valor del formato de fecha y hora del nombre de archivo es YYYY-MM-DD/hh_mm_ssZ, un nombre de objeto de muestra es prod_2023-09-25/04_10_00Z_uNiQuE_archive.

    • Si el formato de fecha y hora del nombre de archivo termina en un carácter que no es un comparador, ese carácter reemplazará el separador entre <UTC-date-time> y <uuid>. Por ejemplo, si el valor del formato de fecha y hora del nombre de archivo es YYYY-MM-DDThh_mm_ss-, un nombre de objeto de muestra es prod_2023-09-25T04_10_00-uNiQuE_archive.

Procesamiento de archivos por lotes

Las suscripciones a Cloud Storage te permiten decidir cuándo quieres crear un archivo de salida nuevo que se almacene como un objeto en el bucket de Cloud Storage. Pub/Sub escribe un archivo de salida cuando se cumple una de las condiciones de procesamiento por lotes especificadas. A continuación, se indican las condiciones de procesamiento por lotes de Cloud Storage:

  • Es la duración máxima del lote de almacenamiento. Este parámetro de configuración es obligatorio. Pub/Sub escribe un nuevo archivo de salida si se supera el valor especificado para la duración máxima. La duración se mide desde el momento en que Pub/Sub comienza a escribir en un archivo nuevo hasta el momento en que se finaliza el archivo. Por ejemplo, si estableces la duración máxima en 5 minutos, Pub/Sub finaliza el archivo como máximo 5 minutos después de que Pub/Sub comenzó a escribir en él. Se puede crear un archivo nuevo antes de que transcurra la duración máxima. Si no especificas el valor, se aplica un valor predeterminado de 5 minutos. Los siguientes son los valores aplicables para la duración máxima:

    • El valor mínimo es 1 minuto.
    • Valor predeterminado = 5 minutos
    • Valor máximo = 10 minutos

  • Cantidad máxima de bytes de almacenamiento. Este es un parámetro de configuración opcional. La suscripción de Cloud Storage escribe un nuevo archivo de salida si se supera el valor especificado de bytes máximos. Los siguientes son los valores aplicables para los bytes máximos:

    • Valor mínimo = 1 KB
    • El valor máximo es 10 GiB.

  • Cantidad máxima de mensajes por lote de almacenamiento. Este es un parámetro de configuración opcional. La suscripción de Cloud Storage escribe un nuevo archivo de salida si se supera la cantidad especificada de mensajes máximos. Estos son los valores aplicables para la cantidad máxima de mensajes:

    • Valor mínimo = 1,000

Por ejemplo, puedes configurar la duración máxima en 6 minutos y los bytes máximos en 2 GB. Si, en el minuto 4, el archivo de salida alcanza un tamaño de 2 GB, Pub/Sub finaliza el archivo anterior y comienza a escribir en uno nuevo.

Una suscripción a Cloud Storage puede escribir en varios archivos de un bucket de Cloud Storage de forma simultánea. Si configuraste tu suscripción para que se cree un archivo nuevo cada 6 minutos, es posible que observes que se crean varios archivos de Cloud Storage cada 6 minutos.

En algunas situaciones, es posible que Pub/Sub comience a escribir en un archivo nuevo antes de la hora configurada por las condiciones de procesamiento por lotes de archivos. Un archivo también puede superar el valor de Max bytes si la suscripción recibe mensajes más grandes que ese valor.

Formato de archivo

Cuando creas una suscripción a Cloud Storage, puedes especificar el formato de los archivos de salida que se almacenarán en un bucket de Cloud Storage como Texto o Avro.

  • Texto: Los mensajes se almacenan como texto sin formato. Un carácter de salto de línea separa un mensaje del mensaje anterior en el archivo. Solo se almacenan las cargas útiles de los mensajes, no los atributos ni otros metadatos.

  • Avro: Los mensajes se almacenan en formato binario Apache Avro. Cuando seleccionas Avro, puedes habilitar las siguientes propiedades adicionales:

    • Escribir metadatos: Esta opción te permite almacenar los metadatos del mensaje junto con el mensaje. Los metadatos, como los campos subscription_name, message_id, publish_time y attributes, se escriben en los campos de nivel superior del objeto Avro de salida, mientras que todas las demás propiedades del mensaje que no son datos (por ejemplo, un ordering_key, si está presente) se agregan como entradas en el mapa attributes.

      Si la opción Escribir metadatos está inhabilitada, solo la carga útil del mensaje se escribe en el objeto Avro de salida. Este es el esquema de Avro para los mensajes de salida con los metadatos de escritura inhabilitados:

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

      Este es el esquema de Avro para los mensajes de salida con los metadatos de escritura habilitados:

      {
  "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" }
  ]
}

    • Usar el esquema de tema: Esta opción permite que Pub/Sub use el esquema del tema de Pub/Sub al que se adjunta la suscripción cuando escribe archivos Avro.

      Cuando uses esta opción, recuerda verificar los siguientes requisitos adicionales:

      • El esquema del tema debe estar en formato Apache Avro.

      • Si se habilitan use topic schema y write metadata, el esquema de temas debe tener un objeto Record en su raíz. Pub/Sub expandirá la lista de campos del registro para incluir los campos de metadatos. Como resultado, el registro no puede contener ningún campo con el mismo nombre que los campos de metadatos (subscription_name, message_id, publish_time o attributes).

Cuenta de servicio

Tienes las siguientes opciones para escribir mensajes en un bucket de Cloud Storage:

  • Configura una cuenta de servicio personalizada para que solo los usuarios que tengan el permiso iam.serviceAccounts.actAs en la cuenta de servicio puedan crear una suscripción que escriba en el bucket. Un ejemplo de rol que incluye el permiso iam.serviceAccounts.actAs es el rol de usuario de cuenta de servicio (roles/iam.serviceAccountUser).

  • Usa el agente de servicio de Pub/Sub predeterminado que permite que cualquier usuario con la capacidad de crear suscripciones en el proyecto cree una suscripción que escriba en el bucket. El agente de servicio de Pub/Sub es el parámetro de configuración predeterminado cuando no especificas una cuenta de servicio personalizada.

Crea una suscripción a Cloud Storage

Console

  1. En la consola de Google Cloud , ve a la página Suscripciones.

    Ir a Suscripciones

  2. Haz clic en Crear suscripción.

  3. En el campo ID de suscripción, ingresa un nombre.

    Para obtener información sobre cómo asignar un nombre a una suscripción, consulta Lineamientos para asignar un nombre a un tema o una suscripción.

  4. Elige o crea un tema desde el menú desplegable.

    La suscripción recibe mensajes del tema.

    Para obtener información sobre cómo crear un tema, consulta Crea y administra temas.

  5. Selecciona Tipo de entrega como Escribir en Cloud Storage.

  6. En el bucket de Cloud Storage, haz clic en Explorar.

    • Puedes seleccionar un bucket existente de cualquier proyecto adecuado.

    • También puedes hacer clic en el ícono de crear y seguir las instrucciones en la pantalla para crear un bucket nuevo.

      Después de crear el bucket, selecciónalo para la suscripción a Cloud Storage.

      Para obtener más información sobre cómo crear un bucket, consulta Crea buckets.

    Cuando especificas el bucket, Pub/Sub verifica los permisos adecuados en el bucket para el agente de servicio de Pub/Sub. Si hay problemas de permisos, verás un mensaje similar al siguiente: 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. Si tienes problemas con los permisos, haz clic en Set Permission y sigue las instrucciones en pantalla.

    Como alternativa, sigue las instrucciones en Asigna roles de Cloud Storage al agente de servicio de Pub/Sub.

  8. En Formato de archivo, selecciona Texto o Avro.

    Si seleccionas Avro, también puedes especificar si deseas almacenar los metadatos del mensaje en el resultado.

    Para obtener más información sobre las dos opciones, incluida la opción de metadatos de mensajes para el formato Avro, consulta Formato de archivo.

  9. Opcional: Puedes especificar el prefijo, el sufijo y la fecha y hora del nombre de archivo para todos los archivos que se escribirán en el bucket de Cloud Storage. Un archivo se almacena como un objeto en el bucket.

    Para obtener más información sobre cómo configurar el prefijo, el sufijo y la fecha y hora del archivo, consulta Prefijo, sufijo y fecha y hora del nombre de archivo.

  10. En File batching, especifica un tiempo máximo que debe transcurrir antes de crear un archivo nuevo.

    También puedes establecer de forma opcional el tamaño máximo de archivo o la cantidad máxima de mensajes para los archivos.

    Para obtener más información sobre las opciones de procesamiento por lotes de archivos, consulta Procesamiento por lotes de archivos.

  11. Te recomendamos que habilites Dead lettering para controlar las fallas de mensajes.

    Para obtener más información, consulta Tema de mensajes no entregados.

  12. Puedes mantener el resto de los parámetros de configuración con sus valores predeterminados y hacer clic en Crear.

gcloud

  1. En la consola de Google Cloud , activa Cloud Shell.

    Activa Cloud Shell

    En la parte inferior de la consola de Google Cloud , se inicia una sesión de Cloud Shell que muestra una ventana emergente con una línea de comandos. Cloud Shell es un entorno de shell con Google Cloud CLI ya instalada y con valores ya establecidos para el proyecto actual. La sesión puede tardar unos segundos en inicializarse.

  2. Para crear una suscripción a Cloud Storage, ejecuta el 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

    Si quieres usar una cuenta de servicio personalizada, proporciónala como un argumento adicional:

    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

    En el comando, solo se requieren SUBSCRIPTION_ID, la marca --topic y la marca --cloud-storage-bucket. Las marcas restantes son opcionales y se pueden omitir.

    Reemplaza lo siguiente:

    • SUBSCRIPTION_ID: Es el nombre o ID de tu nueva suscripción a Cloud Storage.
    • TOPIC_ID: Es el nombre o el ID del tema.
    • BUCKET_NAME: Especifica el nombre de un bucket existente. Por ejemplo, prod_bucket El nombre del bucket no debe incluir el ID del proyecto. Para crear un bucket, consulta Crea buckets.
    • CLOUD_STORAGE_FILE_PREFIX: Especifica el prefijo del nombre de archivo de Cloud Storage. Por ejemplo: log_events_.
    • CLOUD_STORAGE_FILE_SUFFIX: Especifica el sufijo del nombre de archivo de Cloud Storage. Por ejemplo: .txt.
    • CLOUD_STORAGE_FILE_DATETIME_FORMAT: Especifica el formato de fecha y hora para el nombre de archivo de Cloud Storage. Por ejemplo, YYYY-MM-DD/hh_mm_ssZ
    • CLOUD_STORAGE_MAX_DURATION: Es la duración máxima que puede transcurrir antes de que se cree un nuevo archivo de Cloud Storage. El valor debe estar entre 1 m y 10 m. Por ejemplo: 5m.
    • CLOUD_STORAGE_MAX_BYTES: Es la cantidad máxima de bytes que se pueden escribir en un archivo de Cloud Storage antes de que se cree un archivo nuevo. El valor debe estar entre 1 KB y 10 GB. Por ejemplo: 20MB.
    • CLOUD_STORAGE_MAX_MESSAGES: Es la cantidad máxima de mensajes que se pueden escribir en un archivo de Cloud Storage antes de que se cree un archivo nuevo. El valor debe ser mayor o igual que 1,000. Por ejemplo, 100000
    • CLOUD_STORAGE_OUTPUT_FORMAT: Es el formato de salida de los datos escritos en Cloud Storage. Los valores son los siguientes:
      • text: Los mensajes se escriben como texto sin formato, separados por un salto de línea.
      • avro: Los mensajes se escriben como un binario de Avro. --cloud-storage-write-metadata y --cloud-storage-use-topic-schema solo afectan las suscripciones con el formato de salida avro.
    • SERVICE_ACCOUNT_NAME: Especifica el nombre de la cuenta de servicio que se usará para escribir en Cloud Storage.

C++

Antes de probar esta muestra, sigue las instrucciones de configuración de C++ en la guía de inicio rápido de Pub/Sub sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para C++.

Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente. 

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#

Antes de probar esta muestra, sigue las instrucciones de configuración de C# en la guía de inicio rápido de Pub/Sub sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para C#.

Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente. 


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

Antes de probar esta muestra, sigue las instrucciones de configuración de Go en la guía de inicio rápido de Pub/Sub sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para Go.

Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente. 

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

Antes de probar esta muestra, sigue las instrucciones de configuración de Java en la guía de inicio rápido de Pub/Sub sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para Java.

Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente. 

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

Antes de probar esta muestra, sigue las instrucciones de configuración de Node.js en la guía de inicio rápido de Pub/Sub sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para Node.js.

Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente. 

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

Antes de probar esta muestra, sigue las instrucciones de configuración de Node.js en la guía de inicio rápido de Pub/Sub sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para Node.js.

Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente. 

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

Antes de probar esta muestra, sigue las instrucciones de configuración de PHP en la guía de inicio rápido de Pub/Sub sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para PHP.

Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente. 

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

Antes de probar esta muestra, sigue las instrucciones de configuración de Python en la guía de inicio rápido de Pub/Sub sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para Python.

Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente. 

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

Supervisa una suscripción a Cloud Storage

Cloud Monitoring proporciona varias métricas para supervisar las suscripciones.

Para obtener una lista de todas las métricas disponibles relacionadas con Pub/Sub y sus descripciones, consulta la documentación de supervisión de Pub/Sub.

También puedes supervisar las suscripciones desde Pub/Sub.

¿Qué sigue?