Crea suscripciones a BigQuery

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 lo siguiente:

Además de conocer 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 crees 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 del esquema.

Roles y permisos requeridos

Para obtener los permisos que necesitas para crear una suscripción de BigQuery, pídele 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 a proyectos, carpetas y organizaciones.

Este rol predefinido contiene los permisos necesarios para crear una suscripción 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 una suscripción a BigQuery:

  • 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 una tabla de BigQuery, la cuenta de servicio requiere el rol de editor de datos de BigQuery (roles/bigquery.dataEditor). Puedes otorgar permisos a la cuenta de servicio para el proyecto o la tabla, de la siguiente manera:

Proyecto

  1. En la consola de Google Cloud , dirígete a la página IAM.

    Ir a IAM

  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 de Editor de datos de BigQuery.

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

Tabla

  1. En la consola de Google Cloud , ve a BigQuery Studio.

    Ir a BigQuery Studio

  2. En el cuadro de búsqueda del panel Explorador etiquetado como Filtrar por nombre y etiquetas, escribe el nombre de la tabla y presiona Intro.

  3. En los resultados de la búsqueda, haz clic en el nombre de la tabla a la que deseas otorgar permiso.

  4. En la pestaña Detalles, haz clic en Compartir > Administrar permisos.

  5. Haz clic en Agregar principal y, luego, ingresa el identificador de la cuenta de servicio con el siguiente formato:

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

  6. En la lista Asignar roles, selecciona Editor de datos de BigQuery.

  7. Haz clic en Guardar. A la principal se le otorga la función en el recurso.

Usar una cuenta de servicio personalizada

Si otorgas el rol de Editor de datos de BigQuery 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 la tabla de BigQuery. 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 BigQuery:

  • La cuenta de servicio administrada por el usuario debe tener el rol de editor de datos de BigQuery.

  • 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 suscripción a BigQuery

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

Usar esquema del tema

Esta opción permite que Pub/Sub use el esquema del tema de Pub/Sub al que se 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 del esquema del tema y del esquema de BigQuery deben tener los mismos nombres, y sus tipos deben ser compatibles entre sí.

  • Cualquier campo opcional en el esquema del tema también debe ser opcional en el esquema de BigQuery.

  • Los campos obligatorios en el esquema del tema no tienen que ser 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 el 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.

  • Solo puedes seleccionar una de las propiedades de suscripción, Usar esquema de tema o Usar 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 del tipo BYTES, STRING o JSON. Pub/Sub escribe el mensaje en esta columna de BigQuery.

Es posible que no veas los cambios en el esquema de los temas de Pub/Sub o en el esquema de la tabla de BigQuery aplicarse 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 esquema de tema para tu suscripción a BigQuery, también puedes aprovechar la captura de datos modificados (CDC) de BigQuery. La CDC actualiza tus tablas de BigQuery procesando y aplicando cambios a las filas existentes.

Para obtener más información sobre esta función, consulta Transmite actualizaciones de tablas con captura de datos modificados.

Para obtener información sobre cómo usar esta función con las suscripciones de BigQuery, consulta Captura de datos modificados de BigQuery.

Usar esquema de la 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: