Crear suscripciones de Cloud Storage

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

Antes de empezar

Antes de leer este documento, asegúrate de que conoces los siguientes conceptos:

Roles y permisos necesarios

A continuación, se incluye una lista de directrices sobre roles y permisos:

  • Para crear una suscripción, debes configurar el control de acceso a nivel de proyecto.

  • También necesitas permisos a nivel de recurso si tus suscripciones y temas están en proyectos diferentes, como se explica más adelante en esta sección.

  • Para crear una suscripción de Cloud Storage, el agente de servicio de Pub/Sub o una cuenta de servicio personalizada deben tener permiso para escribir en el segmento de Cloud Storage específico y para leer los metadatos del segmento. Para obtener más información sobre cómo conceder estos permisos, consulta la siguiente sección de este documento.

Para obtener los permisos que necesitas para crear suscripciones de Cloud Storage, pide a tu administrador que te conceda el rol de gestión de identidades y accesos Editor de Pub/Sub (roles/pubsub.editor) en el proyecto. Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene los permisos necesarios para crear suscripciones de Cloud Storage. Para ver los permisos exactos que se necesitan, despliega la sección Permisos necesarios:

Permisos obligatorios

Para crear suscripciones de Cloud Storage, se necesitan los siguientes permisos:

  • Crear una suscripción: pubsub.subscriptions.create
  • Adjuntar una suscripción a un tema: pubsub.topics.attachSubscription
  • Extraer de una suscripción: pubsub.subscriptions.consume
  • Obtener una suscripción: pubsub.subscriptions.get
  • Mostrar una suscripción: pubsub.subscriptions.list
  • Actualizar una suscripción: pubsub.subscriptions.update
  • Eliminar una suscripción: pubsub.subscriptions.delete
  • Obtener la política de gestión de identidades y accesos de una suscripción: pubsub.subscriptions.getIamPolicy
  • Configura la política de gestión de identidades y accesos de una suscripción: pubsub.subscriptions.setIamPolicy

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

Para permitir que una entidad de un proyecto cree una suscripción de Cloud Storage en otro proyecto, debes conceder a esa entidad el rol Editor de Pub/Sub (roles/pubsub.editor) en ambos proyectos. De esta forma, se proporcionan los permisos necesarios para crear la nueva suscripción y adjuntarla al tema original. Google Cloud El rol Editor de Pub/Sub (roles/pubsub.editor) del tema también te ayuda a adjuntar Google Cloud suscripciones de otro proyecto al tema.

Asignar roles a cuentas de servicio

Algunos servicios de Google Cloud tienen cuentas de servicio gestionadas por Google Cloudque permiten que los servicios accedan a tus recursos. Estas cuentas de servicio se conocen como agentes de servicio. Pub/Sub crea y mantiene un agente de servicio para cada proyecto con el formato service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com.

Puedes elegir entre permitir que el agente de servicio de Pub/Sub o una cuenta de servicio personalizada escriba en el segmento de Cloud Storage.

Si concedes permiso al agente de servicio de Pub/Sub, cualquier usuario que tenga permiso para crear una suscripción en tu proyecto podrá escribir en el bucket de Cloud Storage. Si quieres proporcionar permisos más específicos para escribir en el segmento de Cloud Storage, configura una cuenta de servicio personalizada.

Para obtener más información sobre la gestión de identidades y accesos de Cloud Storage, consulta el artículo Gestión de identidades y accesos de Cloud Storage.

Asignar roles de Cloud Storage al agente de servicio de Pub/Sub

Si quieres crear una suscripción de Cloud Storage con el agente de servicio de Pub/Sub, este debe tener permiso para escribir en el segmento de Cloud Storage específico y para leer los metadatos del segmento.

Asigna los roles Creador de objetos de Storage (roles/storage.objectCreator) y Lector de segmentos heredados de Storage (roles/storage.legacyBucketReader) al agente de servicio de Pub/Sub. Concede el permiso en el bucket individual.

Segmento

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

    Ir a Cloud Storage

  2. Haz clic en el segmento de Cloud Storage en el que quieras escribir mensajes.

    Se abrirá la página Detalles del segmento.

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

  4. En la pestaña Permisos > Ver por principales, haz clic en Dar acceso.

    Se abrirá la página Dar acceso.

  5. En la sección Añadir principales, introduce el nombre de tu agente de servicio de Pub/Sub del proyecto que contiene la suscripción.

    El formato del agente de servicio es service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com. Por ejemplo, en un proyecto con PROJECT_NUMBER=112233445566, el agente de servicio tiene el formato service-112233445566@gcp-sa-pubsub.iam.gserviceaccount.com.

  6. En el menú desplegable Asignar roles > Seleccionar un rol, introduce Creator y selecciona el rol Creador de objetos de Storage.

  7. Haz clic en Añadir otro rol.

  8. En el menú desplegable Selecciona un rol, introduce Bucket Reader y selecciona el rol Lector de segmentos heredados de Storage.

  9. Haz clic en Guardar.

Proyecto

  1. En la consola, ve a la página Gestión de identidades y accesos. Google Cloud

    Ir a IAM

  2. En la pestaña Permisos > Ver por principales, haz clic en Dar acceso.

    Se abrirá la página Dar acceso.

  3. En la sección Añadir principales, introduce el nombre de tu agente de servicio de Pub/Sub.

    El formato del agente de servicio es service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com. Por ejemplo, en un proyecto con PROJECT_NUMBER=112233445566, el agente de servicio tiene el formato service-112233445566@gcp-sa-pubsub.iam.gserviceaccount.com.

  4. En el menú desplegable Asignar roles > Seleccionar un rol, introduce Storage Admin y selecciona el rol Administrador de almacenamiento.

  5. Haz clic en Guardar.

Asignar roles de Cloud Storage a una cuenta de servicio personalizada

Si quieres usar una cuenta de servicio personalizada para escribir en un segmento de Cloud Storage, debes definir los siguientes permisos:

  • La cuenta de servicio personalizada debe tener permiso para escribir en el segmento de Cloud Storage específico y para leer los metadatos del segmento.
  • El agente de servicio de Pub/Sub debe tener permiso iam.serviceAccounts.getAccessToken en la cuenta de servicio personalizada.
  • El usuario que cree la suscripción debe tener permiso iam.serviceAccounts.actAs en la cuenta de servicio personalizada.

Crea la cuenta de servicio y concede permisos siguiendo estos pasos:

  1. Crea la cuenta de servicio personalizada. La cuenta de servicio debe estar en el mismo proyecto que la suscripción.

  2. Asigna los roles Creador de objetos de Storage (roles/storage.objectCreator) y Lector de segmentos heredados de Storage (roles/storage.legacyBucketReader) a la cuenta de servicio personalizada.

    Puedes conceder permiso a la cuenta de servicio en una sola tabla del proyecto o en todas las tablas del proyecto. Para ello, consulta la sección correspondiente del artículo Asignar roles al agente de servicio de Pub/Sub Google Cloud . En el procedimiento, sustituye la dirección de correo del agente de servicio de Pub/Sub por la dirección de correo de la cuenta de servicio personalizada.

  3. Da al agente de servicio de Pub/Sub el permiso iam.serviceAccounts.getAccessToken en la cuenta de servicio personalizada o en todas las cuentas de servicio del proyecto. Para conceder este permiso, asigna el rol roles/iam.serviceAccountTokenCreator al agente de servicio de Pub/Sub.

    Elige el método adecuado en función de tus requisitos.

Cuenta de servicio

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

    Ir a Cuentas de servicio

  2. Introduce el nombre de la cuenta de servicio personalizada en el filtro.

  3. Selecciona la cuenta de servicio en la lista.

  4. Haz clic en Principales con acceso.

  5. Haz clic en Conceder acceso.

  6. En la sección Añadir principales, introduce el nombre de tu agente de servicio de Pub/Sub del proyecto que contiene la suscripción. El formato del agente de servicio es service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com. Por ejemplo, en un proyecto con project-number=112233445566, el agente de servicio tiene el formato service-112233445566@gcp-sa-pubsub.iam.gserviceaccount.com.

  7. En el menú desplegable Seleccionar un rol, introduce Service Account y selecciona el rol Creador de tokens de cuenta de servicio.

  8. Haz clic en Guardar.

Proyecto

  1. En la consola, ve a la página Gestión de identidades y accesos. Google Cloud

    Ir a IAM

  2. Haz clic en Conceder acceso.

  3. En la sección Añadir principales, introduce el nombre de tu cuenta de servicio personalizada.

  4. En la sección Asignar roles, haz clic en Añadir otro rol.

  5. En el menú desplegable Seleccionar un rol, introduce Service Account y selecciona el rol Creador de tokens de cuenta de servicio.

  6. Haz clic en Guardar.

Si has creado la cuenta de servicio personalizada, ya deberías tener el permiso iam.serviceAccounts.actAs necesario. Si necesitas conceder a otra persona el permiso en la cuenta de servicio, sigue estos pasos:

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

    Ir a Cuentas de servicio

  2. Introduce el nombre de la cuenta de servicio personalizada en el filtro.

  3. Selecciona la cuenta de servicio en la lista.

  4. Haz clic en Principales con acceso.

  5. Haz clic en Conceder acceso.

  6. En la sección Añadir principales, escribe el nombre de la cuenta a la que quieras dar acceso.

  7. En el menú desplegable Selecciona un rol, introduce Service Account y selecciona el rol Usuario de cuenta de servicio.

  8. Haz clic en Guardar.

Propiedades de la suscripción a Cloud Storage

Cuando configuras una suscripción de Cloud Storage, debes especificar las propiedades comunes a todos los tipos de suscripción y algunas propiedades adicionales específicas de la suscripción de Cloud Storage.

Propiedades comunes de las suscripciones

Consulta las propiedades de suscripción comunes que puedes definir en todas las suscripciones.

Nombre del segmento

Debes crear un segmento de Cloud Storage antes de crear una suscripción de Cloud Storage.

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

La función Pagos del solicitante debe estar inhabilitada en el segmento de Cloud Storage.

Para crear un segmento de Cloud Storage, consulta Crear segmentos.

Prefijo, sufijo y fecha y hora del nombre de archivo

Los archivos de Cloud Storage de salida que genera la suscripción a Cloud Storage se almacenan como objetos en el segmento de Cloud Storage. El nombre del objeto almacenado en el segmento 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 de archivo y los campos que puede personalizar:

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

  • <UTC-date-time> es una cadena generada automáticamente y personalizable que se basa en la hora en la que se crea el objeto.

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

  • <file-suffix> es el sufijo de nombre de archivo personalizado. Este campo 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 ejemplo es prod_2023-09-25T04:10:00+00:00_uN1QuE_archive.

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

    • Los requisitos de nomenclatura de los objetos de Cloud Storage también se aplican al prefijo y al sufijo del nombre de archivo. Para obtener más información, consulta el artículo 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:

    • Matchers de fecha y hora obligatorios que solo puedes usar 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.

    • Matchers opcionales que solo puedes usar una vez: separador de fecha y hora (T) y diferencia horaria (Z o +00:00).

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

    • 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 ejemplo es prod_2023-09-25/04_10_00Z_uNiQuE_archive.

    • Si el formato de fecha y hora del nombre de archivo termina con un carácter que no es un elemento de coincidencia, ese carácter sustituirá al 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 ejemplo es prod_2023-09-25T04_10_00-uNiQuE_archive.

Procesamiento por lotes de archivos

Las suscripciones de Cloud Storage te permiten decidir cuándo quieres crear un archivo de salida que se almacene como objeto en el segmento de Cloud Storage. Pub/Sub escribe un archivo de salida cuando se cumple una de las condiciones de procesamiento por lotes especificadas. Estas son las condiciones de procesamiento por lotes de Cloud Storage:

  • Duración máxima del lote de almacenamiento. Este ajuste es obligatorio. La suscripción a Cloud Storage escribe un nuevo archivo de salida si se supera el valor especificado de duración máxima. Si no especificas el valor, se aplicará el valor predeterminado de 5 minutos. Estos son los valores aplicables a la duración máxima:

    • Valor mínimo: 1 minuto
    • Valor predeterminado: 5 minutos
    • Valor máximo: 10 minutos

  • Máximo de bytes por lote de almacenamiento. Este ajuste es opcional. La suscripción a Cloud Storage escribe un nuevo archivo de salida si se supera el valor especificado de bytes máximos. Estos son los valores aplicables para el número máximo de bytes:

    • Valor mínimo: 1 KB
    • Valor máximo: 10 GiB

  • Número máximo de mensajes por lote de almacenamiento. Este ajuste es opcional. La suscripción a Cloud Storage escribe un nuevo archivo de salida si se supera el número máximo de mensajes especificado. Estos son los valores aplicables para el número máximo de mensajes:

    • Valor mínimo = 1000

Por ejemplo, puedes configurar una duración máxima de 6 minutos y un tamaño máximo de 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 empieza a escribir en un archivo nuevo.

Una suscripción de Cloud Storage puede escribir en varios archivos de un segmento de Cloud Storage simultáneamente. Si has configurado tu suscripción para que 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, Pub/Sub puede empezar 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 de mayor tamaño que el valor de Max bytes.

Formato de archivo

Cuando creas una suscripción de Cloud Storage, puedes especificar el formato de los archivos de salida que se van a almacenar en un segmento 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 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 de Apache Avro. Si selecciona Avro, puede 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 campos de nivel superior del objeto Avro de salida, mientras que todas las demás propiedades del mensaje que no sean datos (por ejemplo, una clave de ordenación, si está presente) se añaden como entradas en el mapa attributes.

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

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

      Este es el esquema Avro de los mensajes de salida con la opción Escribir metadatos habilitada:

      {
  "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 esquema de tema: esta opción permite que Pub/Sub use el esquema del tema de Pub/Sub al que está vinculada la suscripción al escribir archivos Avro.

      Si utilizas esta opción, recuerda que debes cumplir los siguientes requisitos adicionales:

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

      • Si las opciones Usar esquema de tema y Escribir metadatos están habilitadas, el esquema de tema debe tener un objeto Record en su raíz. Pub/Sub ampliará la lista de campos de Record para incluir los campos de metadatos. Por lo tanto, 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 una tabla de BigQuery o en un segmento 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 la tabla o el segmento. Un ejemplo de rol que incluye el permiso iam.serviceAccounts.actAs es el rol Usuario de cuenta de servicio (roles/iam.serviceAccountUser).

  • Usa el agente de servicio de Pub/Sub predeterminado, que permite a cualquier usuario con la capacidad de crear suscripciones en el proyecto crear una suscripción que escriba en la tabla o el segmento. El agente de servicio de Pub/Sub es el ajuste predeterminado cuando no se especifica una cuenta de servicio personalizada.

Crear una suscripción de Cloud Storage

Consola

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

    Ir a Suscripciones

  2. Haz clic en Crear suscripción.

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

    Para obtener información sobre cómo poner nombre a una suscripción, consulta las directrices para nombrar un tema o una suscripción.

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

    La suscripción recibe mensajes del tema.

    Para obtener información sobre cómo crear un tema, consulta el artículo Crear y gestionar temas.

  5. Seleccione Tipo de entrega y, a continuación, Escribir en Cloud Storage.

  6. En el segmento de Cloud Storage, haga clic en Examinar.

    • Puedes seleccionar un segmento de cualquier proyecto adecuado.

    • También puedes hacer clic en el icono de crear y seguir las instrucciones que aparecen en pantalla para crear un nuevo contenedor.

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

      Para obtener más información sobre cómo crear un segmento, consulta Crear segmentos.

    Cuando especifica el segmento, Pub/Sub comprueba que el agente de servicio de Pub/Sub tiene los permisos adecuados en el segmento. Si hay problemas con los 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 Definir permiso y sigue las instrucciones que aparecen en pantalla.

    También puedes seguir las instrucciones de la sección Asignar 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 quieres almacenar los metadatos de los mensajes en el archivo de salida.

    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: Puede especificar el prefijo, el sufijo y la fecha y hora de todos los archivos que se van a escribir en el segmento de Cloud Storage. Un archivo se almacena como un objeto en el segmento.

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

  10. En Agrupación de archivos, especifica el tiempo máximo que debe transcurrir antes de crear un archivo.

    También puedes definir el tamaño máximo de los archivos o el número máximo de mensajes de los archivos.

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

  11. Te recomendamos encarecidamente que habilites Dead lettering para gestionar los errores de los mensajes.

    Para obtener más información, consulta el artículo sobre colas de mensajes fallidos.

  12. Puedes dejar el resto de los ajustes con sus valores predeterminados y hacer clic en Crear.

gcloud

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  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 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 son obligatorios SUBSCRIPTION_ID, la marca --topic y la marca --cloud-storage-bucket. Las demás marcas son opcionales y se pueden omitir.

    Haz los cambios siguientes:

    • SUBSCRIPTION_ID: el nombre o el ID de tu nueva suscripción a Cloud Storage.
    • TOPIC_ID: el nombre o el ID del tema.
    • BUCKET_NAME: especifica el nombre de un segmento ya creado. Por ejemplo, prod_bucket. El nombre del contenedor no debe incluir el ID de proyecto. Para crear un segmento, consulta el artículo Crear segmentos.
    • 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 del nombre de archivo de Cloud Storage. Por ejemplo, YYYY-MM-DD/hh_mm_ssZ.
    • CLOUD_STORAGE_MAX_DURATION: la duración máxima que puede transcurrir antes de que se cree un nuevo archivo de Cloud Storage. El valor debe estar comprendido entre 1 y 10 minutos. Por ejemplo, 5m.
    • CLOUD_STORAGE_MAX_BYTES: número máximo de bytes que se pueden escribir en un archivo de Cloud Storage antes de que se cree un archivo nuevo. El valor debe estar comprendido entre 1 KB y 10 GB. Por ejemplo, 20MB.
    • CLOUD_STORAGE_MAX_MESSAGES: número máximo de mensajes que se pueden escribir en un archivo de Cloud Storage antes de que se cree un archivo nuevo. El valor debe ser superior o igual a 1000. Por ejemplo, 100000.
    • CLOUD_STORAGE_OUTPUT_FORMAT: 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 archivo binario Avro. --cloud-storage-write-metadata y --cloud-storage-use-topic-schema solo afectan a las suscripciones con el formato de salida avro.
    • SERVICE_ACCOUNT_NAME: especifica el nombre de la cuenta de servicio que se va a usar para escribir en Cloud Storage.

    3. C++

    Antes de probar este ejemplo, sigue las instrucciones de configuración de C++ que se indican en la guía de inicio rápido de Pub/Sub con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API C++ Pub/Sub.

    Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de 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 este ejemplo, sigue las instrucciones de configuración de C# que se indican en la guía de inicio rápido de Pub/Sub con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API C# Pub/Sub.

    Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de 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 este ejemplo, sigue las instrucciones de configuración de Go que se indican en la guía de inicio rápido de Pub/Sub con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Go Pub/Sub.

    Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de 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 este ejemplo, sigue las instrucciones de configuración de Java que se indican en la guía de inicio rápido de Pub/Sub con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Java Pub/Sub.

    Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de 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 este ejemplo, sigue las instrucciones de configuración de Node.js que se indican en la guía de inicio rápido de Pub/Sub con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Node.js Pub/Sub.

    Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de 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 este ejemplo, sigue las instrucciones de configuración de Node.js que se indican en la guía de inicio rápido de Pub/Sub con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Node.js de Pub/Sub.

    Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de 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 este ejemplo, sigue las instrucciones de configuración de PHP que se indican en la guía de inicio rápido de Pub/Sub con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API PHP Pub/Sub.

    Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de 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 este ejemplo, sigue las instrucciones de configuración de Python que se indican en la guía de inicio rápido de Pub/Sub con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Python Pub/Sub.

    Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de 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}")

Monitorizar una suscripción a Cloud Storage

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

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

También puedes monitorizar las suscripciones en Pub/Sub.

Siguientes pasos