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 la siguiente información:
- Cómo funciona una suscripción a Cloud Storage
- Cómo funciona Cloud Storage, cómo crear y administrar buckets de Cloud Storage.
- Cómo configurar un tema de mensajes no entregados para manejar las fallas de los mensajes
Funciones y permisos requeridos
La siguiente es una lista de lineamientos relacionados con los roles y los permisos:
Para crear una suscripción, debes configurar el control de acceso en el proyecto o a nivel de organización.
También necesitas permisos a nivel de recursos 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 a Cloud Storage, el La cuenta de servicio de Pub/Sub debe tener permiso para escribir en el en un bucket específico de Cloud Storage y leer los metadatos del bucket. Para ver más para obtener más información sobre cómo otorgar estos permisos, consulta la siguiente de este documento.
A fin de obtener los permisos que necesitas para crear suscripciones a Cloud Storage,
solicita a tu administrador que te otorgue el
Rol de IAM de 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.
Este rol predefinido contiene los permisos necesarios para crear suscripciones 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 suscripciones a Cloud Storage:
-
Crea una suscripción:
pubsub.subscriptions.create
-
Adjunta una suscripción a un tema:
pubsub.topics.attachSubscription
-
Extraer de una suscripción:
pubsub.subscriptions.consume
-
Obtén una suscripción:
pubsub.subscriptions.get
-
Muestra una suscripción:
pubsub.subscriptions.list
-
Actualiza una suscripción:
pubsub.subscriptions.update
-
Borra una suscripción:
pubsub.subscriptions.delete
-
Obtén la política de IAM para una suscripción:
pubsub.subscriptions.getIamPolicy
-
Configura la política de IAM para una suscripción:
pubsub.subscriptions.setIamPolicy
También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos
Si necesitas crear Cloud Storage
suscripciones en un proyecto que están asociadas con un tema de otro
solicita a tu administrador de temas que también te otorgue el Editor de Pub/Sub
(roles/pubsub.editor)
rol de IAM en el tema.
Asigna roles de Cloud Storage a la cuenta de servicio de Pub/Sub
Algunos servicios de Google Cloud tienen cuentas de servicio administradas por Google Cloud que
permite que los servicios accedan a tus recursos. Estas cuentas de servicio se conocen como
agentes de servicio. Pub/Sub crea y mantiene un servicio
para cada proyecto en el formato
service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com
Para crear una suscripción a Cloud Storage, Pub/Sub la cuenta de servicio debe tener permiso para escribir en un bucket específico de Cloud Storage y leer los metadatos del bucket. Elegir uno de los siguientes procedimientos:
Otorga permisos a nivel de bucket. En el bucket de Cloud Storage específico bucket, otorga el rol de Creador de objetos de almacenamiento (
roles/storage.objectCreator
) y el rol de lector de buckets heredados de almacenamiento (roles/storage.legacyBucketReader
) a la cuenta de servicio de Pub/Sub.Si debes otorgar roles a nivel de proyecto, puedes otorgar el rol Administrador de almacenamiento (
roles/storage.admin
) en el proyecto que contiene el bucket de Cloud Storage. Otórgale este rol a Cuenta de servicio de Pub/Sub.
Permisos de depósitos
Realiza los siguientes pasos para otorgarle al creador de objetos de Storage
(roles/storage.objectCreator
) y lector de buckets heredados de Storage
(roles/storage.legacyBucketReader
) a nivel de bucket:
En la consola de Google Cloud, ve a la página de Cloud Storage.
Haz clic en el bucket de Cloud Storage en el que quieres escribir los mensajes.
Se abrirá la página Detalles del bucket.
En la página Detalles del bucket, haz clic en la pestaña Permisos.
En Permisos > La pestaña Ver por principales haz clic en Otorgar acceso.
Se abrirá la página Otorgar acceso.
En la sección Agregar principales, ingresa el nombre de tu Pub/Sub. cuenta de servicio.
El formato de la cuenta de servicio es el siguiente:
service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com
Por ejemplo, para un proyecto con PROJECT_NUMBER=112233445566
, La cuenta de servicio tiene el siguiente formato:service-112233445566@gcp-sa-pubsub.iam.gserviceaccount.com
En Asignar roles > En el menú desplegable Selecciona un rol, Ingresa
Creator
y selecciona el rol Creador de objetos de almacenamiento.Haz clic en Agregar otra función.
En el menú desplegable Seleccionar un rol, ingresa
Bucket Reader
. y selecciona el rol Lector de buckets heredados de almacenamiento.Haz clic en Guardar.
Permisos del proyecto
Realiza los siguientes pasos para otorgar al administrador de almacenamiento
(roles/storage.admin
) a nivel del proyecto:
En la consola de Google Cloud, ve a la página IAM.
En Permisos > La pestaña Ver por principales haz clic en Otorgar acceso.
Se abrirá la página Otorgar acceso.
En la sección Agregar principales, ingresa el nombre de tu Pub/Sub. cuenta de servicio.
El formato de la cuenta de servicio es el siguiente:
service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com
Por ejemplo, para un proyecto con PROJECT_NUMBER=112233445566
, La cuenta de servicio tiene el siguiente formato:service-112233445566@gcp-sa-pubsub.iam.gserviceaccount.com
En Asignar roles > En el menú desplegable Selecciona un rol, ingresa
Storage Admin
y selecciona el rol Administrador de almacenamiento.Haz clic en Guardar.
Para obtener más información sobre IAM de Cloud Storage, consulta Identity and Access Management de Cloud Storage.
Propiedades de suscripción de Cloud Storage
Cuando configuras una suscripción a Cloud Storage, debes especificar las propiedades comunes a todos los tipos de suscripción y algunas Propiedades específicas de suscripción a Cloud Storage.
Propiedades de suscripción comunes
Obtén más información sobre las propiedades de suscripción comunes que puedes configurar en todas las suscripciones.
Nombre del bucket
Ya debe existir un bucket de Cloud Storage antes de crear un suscripción a Cloud Storage.
Los mensajes se envían como 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 Se inhabilitaron los 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 generados por la Cloud Storage
se almacenan como objetos en el bucket de Cloud Storage. El nombre
del objeto almacenado en el bucket de Cloud Storage es de los siguientes:
formato: <file-prefix><UTC-date-time>_<uuid><file-suffix>
.
La siguiente lista incluye detalles del formato de archivo y los campos que personalizar:
<file-prefix>
es el prefijo del nombre de archivo personalizado. Este paso es opcional,<UTC-date-time>
es una cadena personalizable generada automáticamente en función de la hora 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 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 de el sufijo del nombre de archivo es_archive
, se muestraprod_2023-09-25T04:10:00+00:00_uN1QuE_archive
Si no especificas el prefijo y el sufijo del nombre de archivo, se almacenará en el bucket de Cloud Storage tiene el siguiente formato:
<UTC-date-time>_<uuid>
Los requisitos para nombrar objetos de Cloud Storage también se aplican al nombre de archivo. el prefijo y el sufijo. 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:
Comparadores de fecha y hora obligatorios que puedes usar solo una vez: año (
YYYY
oYY
), mes (MM
), día (DD
), hora (hh
), minuto (mm
) y segundo (ss
). Por ejemplo,YY-YYYY
oMMM
no es válido.Comparadores opcionales que puedes usar solo una vez: separador de fecha y hora (
T
) y y el desplazamiento 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 esprod_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 esYYYY-MM-DDThh_mm_ss-
, un nombre de objeto de muestra esprod_2023-09-25T04_10_00-uNiQuE_archive
Agrupación en lotes de archivos
Las suscripciones a Cloud Storage te permiten decidir cuándo crear un nuevo archivo de salida que se almacena como un objeto en Cloud Storage bucket. Pub/Sub escribe un archivo de salida cuando uno de los se cumplan las condiciones de lotes especificadas. Los siguientes son los Condiciones de procesamiento por lotes de Cloud Storage:
Duración máxima del lote de almacenamiento. Este es un parámetro de configuración obligatorio. El La suscripción a Cloud Storage escribe un nuevo archivo de salida si se excede el valor especificado de la duración máxima. Si no se especifica el valor, se aplica un valor predeterminado de 5 minutos. Los siguientes son los valores aplicables para la duración máxima:
- Valor mínimo: 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. El La suscripción a Cloud Storage escribe un nuevo archivo de salida si la se excede el valor especificado de la cantidad máxima de bytes. Las siguientes son las aplicables valores para la cantidad máxima de bytes:
- Valor mínimo = 1 KB
- Valor máximo = 10 GiB
Cantidad máxima de mensajes en lote de almacenamiento. Este es un parámetro de configuración opcional. El La suscripción a Cloud Storage escribe un nuevo archivo de salida si la se supera el número máximo especificado de mensajes. Las siguientes son las aplicables valores 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 máximos de 2 GB. Si en el minuto 4, el archivo de salida alcanza un tamaño de archivo de 2 GB, Pub/Sub finaliza el archivo anterior y comienza escribiendo a un nuevo archivo.
Una suscripción a Cloud Storage puede escribir en varios archivos de una de bucket de Cloud Storage al mismo tiempo. Si configuraste tu para crear un archivo nuevo cada 6 minutos, podrías observar se crean varios archivos de Cloud Storage cada 6 minutos.
En algunos casos, Pub/Sub puede empezar a escribir en un nuevo archivo anterior a la hora configurada por las condiciones de lotes. Un archivo también puede superar el valor máximo de bytes si la suscripción recibe mensajes superiores al valor máximo de bytes.
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 Text o Avro.
Texto: Los mensajes se almacenan como texto sin formato. Un carácter de línea nueva separa un mensaje del mensaje anterior en el archivo. Solo mensaje no se almacenan atributos ni otros metadatos.
Avro: Los mensajes se almacenan en Formato binario de 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
yattributes
se escriben en campos de nivel superior en el objeto Avro de salida, mientras que todas las demás propiedades de mensaje que no son datos (por ejemplo, order_key, si está presente) se agregan como entradas en el mapaattributes
.Si la escritura de 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 la opción write metadata inhabilitada:
{ "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 se escriben archivos de Avro.
Cuando uses esta opción, recuerda verificar los siguientes requisitos adicionales:
El esquema del tema debe estar en formato Apache Avro.
Si usar esquema de tema y escribir metadatos están habilitados, el esquema de tema debe tener un objeto Record en la 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
oattributes
).
Crea una suscripción a Cloud Storage
Console
-
En la consola de Google Cloud, ve a Suscripciones. .
-
Haz clic en Crear suscripción.
-
En el campo ID de la 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.
-
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 Cómo crear y administrar temas.
-
Selecciona Tipo de entrega como Escribir en Cloud Storage
-
En el bucket de Cloud Storage, haz clic en Explorar.
-
Puedes seleccionar un bucket existente de cualquier proyecto que corresponda.
-
También puedes hacer clic en el ícono de crear y seguir las instrucciones en la pantalla para crear un nuevo bucket.
Después de crear el bucket, selecciónalo para el bucket 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 comprueba la existencia de con los permisos adecuados en el bucket para Pub/Sub cuenta de servicio. Si hay problemas de permisos, verás un mensaje. similar a lo 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
. -
-
Si tienes problemas con los permisos, haz clic en Establecer permiso y y sigue las instrucciones en pantalla.
Como alternativa, sigue las instrucciones que se indican en Asigna roles de Cloud Storage con la cuenta de servicio de Pub/Sub.
-
En Formato de archivo, selecciona Texto. Avro
Si seleccionas Avro, también puedes especificar quieres almacenar los metadatos del mensaje en el resultado.
Para obtener más información sobre las dos opciones, incluido el mensaje de metadatos para el formato Avro, consulta Archivo formato.
-
Opcional: Puedes especificar el Prefijo del nombre de archivo, el sufijo y datetime para todos los archivos que se escribirán en 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 datetime, consulta Prefijo, sufijo y fecha y hora
-
En Agrupación en lotes de archivos, especifica un tiempo máximo transcurrido. antes de crear uno nuevo.
También puede establecer el tamaño máximo de archivo o la cantidad máxima de archivos mensajes nuevos para los archivos.
Para obtener más información sobre ambas opciones de agrupación de archivos en lotes, consulta Agrupación en lotes de archivos.
-
Te recomendamos que habilites los mensajes no entregados. para manejar las fallas de los mensajes.
Para obtener más información, consulta Mensajes no entregados. predeterminado.
-
Puedes mantener el resto de la configuración con sus valores predeterminados y hacer clic en Crear.
gcloud
-
In the Google Cloud console, 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.
- Para crear un
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
En el comando, solo
SUBSCRIPTION_ID
, el la marca--topic
y--cloud-storage-bucket
la marca de verificación. Las marcas restantes son opcionales y se pueden omitir.Reemplaza lo siguiente:
SUBSCRIPTION_ID
: Es el nombre o el ID del nuevo servicio. suscripción a Cloud Storage.TOPIC_ID
: Es el nombre o el ID de tu tema.BUCKET_NAME
: Especifica el nombre de un bucket existente. Por ejemplo,prod_bucket
El bucket el nombre no debe incluir el ID del proyecto. Para crear un bucket, consulta Crea buckets.CLOUD_STORAGE_FILE_PREFIX
: Especifica la para el nombre del archivo de Cloud Storage. Por ejemplo:log_events_
.CLOUD_STORAGE_FILE_SUFFIX
: Especifica la para el nombre del 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 el máximo. que puede pasar antes de que se cree un nuevo archivo crear. 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 puede escribir en un archivo de Cloud Storage antes que un archivo cuando se cree. El valor debe ser de entre 1 KB y 10 GB. Por ejemplo:20MB
.CLOUD_STORAGE_MAX_MESSAGES
: Es el máximo. cantidad de mensajes que se pueden escribir en un archivo de Cloud Storage antes de crear un archivo nuevo. El valor debe ser mayor o igual que en 1,000. Por ejemplo,100000
CLOUD_STORAGE_OUTPUT_FORMAT
: Es el resultado. para los datos escritos en Cloud Storage. Los valores son los siguientes: sigue:text
: Los mensajes se escriben como texto sin procesar, separados. por una línea nueva.avro
: Los mensajes se escriben como un objeto binario de Avro.--cloud-storage-write-metadata
tiene efecto solo para suscripciones con formato de salidaavro
.
C++
Antes de probar esta muestra, sigue las instrucciones de configuración de C++ que se encuentran en el Guía de inicio rápido de Pub/Sub con bibliotecas cliente. Para obtener más información, consulta la API de C++ de Pub/Sub documentación de referencia.
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.
Go
Antes de probar esta muestra, sigue las instrucciones de configuración de Go que se encuentran en el Guía de inicio rápido de Pub/Sub con bibliotecas cliente. Para obtener más información, consulta la API de Go de Pub/Sub documentación de referencia.
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.
Java
Antes de probar esta muestra, sigue las instrucciones de configuración de Java que se encuentran en el Guía de inicio rápido de Pub/Sub con bibliotecas cliente. Para obtener más información, consulta la API de Java de Pub/Sub documentación de referencia.
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.
Supervisa las suscripciones
Cloud Monitoring proporciona una serie de métricas para supervisar las suscripciones.
También puedes supervisar las suscripciones desde Pub/Sub.
¿Qué sigue?
Soluciona problemas relacionados con una suscripción a Cloud Storage.
Obtén más información sobre Cloud Storage.
Revisa los precios de Pub/Sub, incluida la suscripción a Cloud Storage.