En este documento, se describe cómo crear una suscripción a BigQuery. 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 BigQuery.
Antes de comenzar
Antes de leer este documento, asegúrate de estar familiarizado con la siguiente información:
Cómo funcionan las suscripciones
Flujo de trabajo para suscripciones a BigQuery
Cómo configurar un tema de mensajes no entregados para controlar las fallas de los mensajes
Además de estar familiarizado con Pub/Sub y BigQuery, asegúrate de cumplir con los siguientes requisitos previos antes de crear una suscripción a BigQuery:
Existe una tabla de BigQuery. Como alternativa, puedes crear una cuando creas la suscripción a BigQuery, como se describe en las secciones posteriores de este documento.
Compatibilidad entre el esquema del tema de Pub/Sub y la tabla de BigQuery Si agregas una tabla de BigQuery no compatible, recibirás un mensaje de error relacionado con la compatibilidad. Para obtener más información, consulta Compatibilidad con el esquema.
Roles 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 a nivel de proyecto.
También necesitas permisos a nivel de recursos si tus suscripciones y temas se encuentran en proyectos diferentes, como se explica más adelante en esta sección.
Para crear una suscripción a BigQuery, la cuenta de servicio de Pub/Sub debe tener permiso para escribir en la tabla de BigQuery específica. Para obtener más información sobre cómo otorgar estos permisos, consulta la siguiente sección de este documento.
Puedes configurar una suscripción a BigQuery en un proyecto para escribir en una tabla de BigQuery de un proyecto diferente.
Para obtener los permisos que necesitas para crear suscripciones a BigQuery,
solicita 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.
Este rol predefinido contiene los permisos necesarios para crear suscripciones a BigQuery. 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 BigQuery:
-
Extraer de una suscripción:
pubsub.subscriptions.consume
-
Crea una suscripción:
pubsub.subscriptions.create
-
Borrar una suscripción:
pubsub.subscriptions.delete
-
Obtener una suscripción:
pubsub.subscriptions.get
-
Muestra una suscripción:
pubsub.subscriptions.list
-
Actualiza una suscripción:
pubsub.subscriptions.update
-
Adjunta una suscripción a un tema:
pubsub.topics.attachSubscription
-
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, también, otros roles predefinidos.
Si necesitas crear suscripciones de BigQuery en un proyecto que estén asociados con un tema en otro proyecto, pídele al administrador de temas que también te otorgue la función de IAM (roles/pubsub.editor)
del editor de Pub/Sub en el tema.
Asigna roles de BigQuery a la cuenta de servicio de Pub/Sub
Algunos servicios de Google Cloud tienen cuentas de servicio administradas por Google Cloud que permiten que los servicios accedan a tus recursos. Estas cuentas de servicio se conocen
como agentes de servicio. Pub/Sub crea y mantiene una cuenta de servicio para cada proyecto en el formato service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com
.
Para crear una suscripción a BigQuery, la cuenta de servicio de Pub/Sub debe tener permiso para escribir en la tabla de BigQuery específica y leer los metadatos de la tabla.
Otorga la función de editor de datos de BigQuery (roles/bigquery.dataEditor
) a la cuenta de servicio de Pub/Sub.
En la consola de Google Cloud, ve a la página IAM.
Haz clic en Otorgar acceso.
En la sección Agregar principales, ingresa el nombre de tu cuenta de servicio de Pub/Sub. El formato de la cuenta de servicio es
service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com
. Por ejemplo, para un proyecto conproject-number=112233445566
, la cuenta de servicio tiene el formatoservice-112233445566@gcp-sa-pubsub.iam.gserviceaccount.com
.En la sección Asignar roles, haz clic en Agregar otro rol.
En el menú desplegable Seleccionar una función, ingresa
BigQuery
y selecciona el rol de Editor de datos de BigQuery.Haz clic en Guardar.
Para obtener más información sobre IAM de BigQuery, consulta Funciones y permisos de BigQuery.
Propiedades de suscripción a BigQuery
Cuando configuras una suscripción a BigQuery, puedes especificar las siguientes propiedades.
Propiedades comunes
Obtén información sobre las propiedades de suscripción comunes que puedes configurar en todas las suscripciones.
Usar el esquema de tema
Esta opción permite que Pub/Sub use el esquema del tema de Pub/Sub al que está adjunta la suscripción. Además, Pub/Sub escribe los campos de los mensajes en las columnas correspondientes de la tabla de BigQuery.
Cuando uses esta opción, recuerda verificar los siguientes requisitos adicionales:
Los campos en el esquema de tema y en el esquema de BigQuery deben tener los mismos nombres y sus tipos deben ser compatibles entre sí.
Cualquier campo opcional en el esquema del tema debe serlo también en el esquema de BigQuery.
No es necesario que los campos obligatorios en el esquema de tema sean obligatorios en el esquema de BigQuery.
Si hay campos de BigQuery que no están presentes en el esquema del tema, estos campos de BigQuery deben estar en modo
NULLABLE
.Si el esquema del tema tiene campos adicionales que no están presentes en el esquema de BigQuery y estos campos se pueden descartar, selecciona la opción Descartar campos desconocidos.
Puedes seleccionar solo una de las propiedades de suscripción, Usar el esquema de tema o Usar el esquema de tabla.
Si no seleccionas la opción Usar el esquema de tema o Usar el esquema de tabla, asegúrate de que la tabla de BigQuery tenga una columna llamada data
de tipo BYTES
, STRING
o JSON
. Pub/Sub escribe el mensaje
en esta columna de BigQuery.
Es posible que no veas que los cambios en el esquema de temas de Pub/Sub o en el esquema de la tabla de BigQuery se apliquen de inmediato con los mensajes escritos en la tabla de BigQuery. Por ejemplo, si la opción Descartar campos desconocidos está habilitada y hay un campo presente en el esquema de Pub/Sub, pero no en el esquema de BigQuery, es posible que los mensajes escritos en la tabla de BigQuery aún no contengan el campo después de agregarlo al esquema de BigQuery. Con el tiempo, los esquemas se sincronizan y los mensajes posteriores incluyen el campo.
Cuando usas la opción Usar el esquema de tema para tu suscripción a BigQuery, también puedes aprovechar la captura de datos modificados (CDC) de BigQuery. La CDC actualiza las tablas de BigQuery mediante el procesamiento y la aplicación de cambios en las filas existentes.
Si deseas obtener más información sobre esta función, consulta Cómo transmitir actualizaciones de tablas con la captura de datos modificados.
Para obtener información sobre cómo utilizar esta función con suscripciones a BigQuery, consulta Captura de datos modificados de BigQuery.
Usar el esquema de tabla
Esta opción permite que Pub/Sub use el esquema de la tabla de BigQuery para escribir los campos de un mensaje JSON en las columnas correspondientes. Cuando uses esta opción, recuerda verificar los siguientes requisitos adicionales:
Los mensajes publicados deben estar en formato JSON.
Si el tema de la suscripción tiene un esquema asociado, la propiedad de codificación de mensajes debe establecerse en
JSON
.Si hay campos de BigQuery que no están presentes en los mensajes, estos campos de BigQuery deben estar en modo
NULLABLE
.Si los mensajes tienen campos adicionales que no están presentes en el esquema de BigQuery y estos campos se pueden descartar, selecciona la opción Descartar campos desconocidos.
En el mensaje JSON, los valores
DATE
,DATETIME
,TIME
yTIMESTAMP
deben ser números enteros que cumplan con las representaciones admitidas.En el mensaje JSON, los valores
NUMERIC
yBIGNUMERIC
deben ser bytes codificados con BigDecimalByteStringEncoder.Puedes seleccionar solo una de las propiedades de suscripción, Usar el esquema de tema o Usar el esquema de tabla.
Si no seleccionas la opción Usar el esquema de tema o Usar el esquema de tabla, asegúrate de que la tabla de BigQuery tenga una columna llamada data
de tipo BYTES
, STRING
o JSON
. Pub/Sub escribe el mensaje
en esta columna de BigQuery.
Es posible que no veas que los cambios en el esquema de la tabla de BigQuery se apliquen de inmediato con los mensajes escritos en la tabla de BigQuery. Por ejemplo, si la opción Descartar campos desconocidos está habilitada y hay un campo presente en los mensajes, pero no en el esquema de BigQuery, es posible que los mensajes escritos en la tabla de BigQuery aún no contengan el campo después de agregarlo al esquema de BigQuery. Con el tiempo, el esquema se sincroniza y los mensajes posteriores incluyen el campo.
Cuando usas la opción Usar el esquema de tabla para tu suscripción a BigQuery, también puedes aprovechar la captura de datos modificados (CDC) de BigQuery. La CDC actualiza las tablas de BigQuery mediante el procesamiento y la aplicación de cambios en las filas existentes.
Si deseas obtener más información sobre esta función, consulta Cómo transmitir actualizaciones de tablas con la captura de datos modificados.
Para obtener información sobre cómo utilizar esta función con suscripciones a BigQuery, consulta Captura de datos modificados de BigQuery.
Quitar campos desconocidos
Esta opción se usa con las opciones Usar el esquema de tema o Usar el esquema de tabla. Esta opción permite que Pub/Sub descarte cualquier campo que esté presente en el esquema o mensaje del tema, pero no en el esquema de BigQuery. Si no se configuran los campos desconocidos, los mensajes con campos adicionales no se escriben en BigQuery y permanecen en las tareas pendientes de la suscripción. La suscripción termina en un estado de error.
Escribir metadatos
Esta opción permite que Pub/Sub escriba los metadatos de cada mensaje en columnas adicionales de la tabla de BigQuery. De lo contrario, los metadatos no se escriben en la tabla de BigQuery.
Si seleccionas la opción Escribir metadatos, asegúrate de que la tabla de BigQuery tenga los campos descritos en la siguiente tabla.
Si no seleccionas la opción Escribir metadatos, la tabla de BigQuery de destino solo requiere el campo data
, a menos que use_topic_schema
sea verdadero. Si seleccionas las opciones Escribir metadatos y Usar esquema de tema, el esquema del tema no debe contener campos con nombres que coincidan con los de los parámetros de metadatos.
Esta limitación incluye versiones en mayúsculas y minúsculas de estos parámetros de Snake case.
Parámetros | |
---|---|
subscription_name |
STRING Es el nombre de una suscripción. |
message_id |
STRING ID de un mensaje |
publish_time |
TIMESTAMP Indica la hora de publicación de un mensaje. |
data |
BYTES, STRING o JSON El cuerpo del mensaje. El campo |
attributes |
STRING o JSON Un objeto JSON que contiene todos los atributos del mensaje. También contiene campos adicionales que forman parte del mensaje de Pub/Sub, incluida la clave de ordenamiento, si está presente. |
Crea una suscripción a BigQuery
En los siguientes ejemplos, se muestra cómo crear una suscripción con la entrega de BigQuery.
Consola
- En la consola de Google Cloud, ve a la página Suscripciones.
- Haz clic en Crear suscripción.
- En el campo ID de la suscripción, ingresa un nombre.
Si quieres obtener información para 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.
- Selecciona Tipo de entrega como Escribir en BigQuery.
- Selecciona el proyecto para la tabla de BigQuery.
- Selecciona un conjunto de datos existente o crea uno nuevo.
Para obtener información sobre cómo crear un conjunto de datos, consulta Crea conjuntos de datos.
- Selecciona una tabla existente o crea una nueva.
Para obtener información sobre cómo crear una tabla, consulta Crea tablas.
- Te recomendamos que habilites los mensajes no entregados para manejar las fallas de los mensajes.
Para obtener más información, consulta el Tema de mensajes no entregados.
- Haz clic en Crear.
También puedes crear una suscripción desde la página Temas. Este acceso directo es útil para asociar temas a suscripciones.
- En la consola de Google Cloud, ve a la página Temas.
- Haz clic en more_vert junto al tema para el que deseas crear una suscripción.
- En el menú contextual, selecciona Crear suscripción (Create subscription).
- Selecciona Tipo de entrega como Escribir en BigQuery.
- Selecciona el proyecto para la tabla de BigQuery.
- Selecciona un conjunto de datos existente o crea uno nuevo.
Para obtener información sobre cómo crear un conjunto de datos, consulta Crea conjuntos de datos.
- Selecciona una tabla existente o crea una nueva.
Para obtener información sobre cómo crear un conjunto de datos, consulta Crea tablas.
- Te recomendamos que habilites los mensajes no entregados para manejar las fallas de los mensajes.
Para obtener más información, consulta el Tema de mensajes no entregados.
- Haz clic en Crear.
gcloud
-
En la consola de Google Cloud, activa Cloud Shell.
En la parte inferior de la consola de Google Cloud, se inicia una sesión de Cloud Shell en la que se muestra una ventana de 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.
-
Para crear una suscripción a Pub/Sub, usa el comando
gcloud pubsub subscriptions create
:gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --bigquery-table=PROJECT_ID:DATASET_ID.TABLE_ID
Reemplaza lo siguiente:
- SUBSCRIPTION_ID: Especifica el ID de la suscripción.
- TOPIC_ID: Especifica el ID del tema. El tema requiere un esquema.
- PROJECT_ID: Especifica el ID del proyecto.
- DATASET_ID: Especifica el ID de un conjunto de datos existente. Para crear un conjunto de datos, consulta Cómo crear conjuntos de datos.
- TABLE_ID: Especifica el ID de una tabla existente. La tabla requiere un campo data si tu tema no tiene un esquema. Para crear una tabla, consulta Crea una tabla vacía con una definición de esquema.
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.
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.
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.
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.
Node.js
Node.js
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.
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.
Ruby
Antes de probar esta muestra, sigue las instrucciones de configuración de Ruby 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 Ruby.
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.
¿Qué sigue?
- Crear o modificar una suscripción con los comandos de
gcloud
- Crea o modifica una suscripción con las APIs de REST.
- Soluciona los problemas de una suscripción a BigQuery.