Esta página se ha traducido con Cloud Translation API.

Crear suscripciones a BigQuery

En este documento se describe cómo crear una suscripción de BigQuery. 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 BigQuery.

Antes de empezar

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

Cómo funcionan las suscripciones.
El flujo de trabajo de las suscripciones de BigQuery.
Cómo configurar un tema de mensajes fallidos para gestionar los errores de mensajes.

Además de conocer Pub/Sub y BigQuery, debes cumplir los siguientes requisitos previos antes de crear una suscripción de BigQuery:

Existe una tabla de BigQuery. También puedes crear una al crear la suscripción de BigQuery, tal 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 añades una tabla de BigQuery no compatible, recibirás un mensaje de error relacionado con la compatibilidad. Para obtener más información, consulta Compatibilidad de esquemas.

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 BigQuery, el agente de servicio de Pub/Sub o una cuenta de servicio personalizada deben tener permiso para escribir en la tabla de BigQuery específica. Para obtener más información sobre cómo conceder estos permisos, consulta la siguiente sección de este documento.
Puedes configurar una suscripción de BigQuery en un proyecto para escribir en una tabla de BigQuery de otro proyecto.

Para obtener los permisos que necesitas para crear suscripciones de BigQuery, pide a tu administrador que te asigne 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 BigQuery. Para ver los permisos exactos que se necesitan, despliega la sección Permisos necesarios:

Permisos obligatorios

Para crear suscripciones de BigQuery, se necesitan los siguientes permisos:

Extraer de una suscripción: pubsub.subscriptions.consume
Crear una suscripción: pubsub.subscriptions.create
Eliminar una suscripción: pubsub.subscriptions.delete
Obtener una suscripción: pubsub.subscriptions.get
Mostrar una suscripción: pubsub.subscriptions.list
Actualizar una suscripción: pubsub.subscriptions.update
Adjuntar una suscripción a un tema: pubsub.topics.attachSubscription
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 BigQuery en otro proyecto, debes asignarle el rol Editor de Pub/Sub (roles/pubsub.editor) en ambos proyectos. De esta forma, se conceden los permisos necesarios para crear la nueva suscripción de BigQuery y adjuntarla al tema original. La función Editor de Pub/Sub (roles/pubsub.editor) en el tema también te ayuda a adjuntar suscripciones de BigQuery 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 escriban en la tabla de BigQuery.

Si das permiso al agente de servicio de Pub/Sub, cualquier usuario que tenga permiso para crear una suscripción en tu proyecto podrá escribir en la tabla de BigQuery. Si quieres proporcionar permisos más específicos para escribir en la tabla de BigQuery, configura una cuenta de servicio personalizada.

Para obtener más información sobre la gestión de identidades y accesos de BigQuery, consulta el artículo sobre los roles y permisos de BigQuery.

Asignar roles de BigQuery al agente de servicio de Pub/Sub

Si quieres crear una suscripción de BigQuery con el agente de servicio de Pub/Sub, este debe tener permiso para escribir en la tabla de BigQuery específica y leer los metadatos de la tabla.

Otorga el rol Editor de datos de BigQuery (roles/bigquery.dataEditor) a la cuenta de servicio de Pub/Sub. Puedes conceder el permiso en una tabla concreta o en todo el proyecto.

Tabla

En la Google Cloud consola, ve a BigQuery Studio.

Ir a BigQuery Studio
En el cuadro de búsqueda del panel Explorador, etiquetado como Filtrar por nombre y etiquetas, escribe el nombre de la tabla y pulsa Intro.
Haga clic en la tabla a la que quiera conceder permiso.
En la tabla, selecciona Más acciones > Compartir > Permisos.

También puede hacer clic en la tabla y, en la página principal, en Compartir > Permisos.

Se abrirá la ventana Permisos para compartir.
Haz clic en Añadir principal.
En Añadir principales, introduce el nombre del 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.
En el menú desplegable Seleccionar un rol, introduce BigQuery y selecciona el rol Editor de datos de BigQuery.
Haz clic en Guardar.

Proyecto

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

Ir a IAM
Haz clic en Conceder acceso.
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.
En la sección Asignar roles, haz clic en Añadir otro rol.
En el menú desplegable Seleccionar un rol, introduce BigQuery y selecciona el rol Editor de datos de BigQuery.
Haz clic en Guardar.

Asignar roles de BigQuery a una cuenta de servicio personalizada

Si quieres usar una cuenta de servicio personalizada para escribir en una tabla de BigQuery, debes definir los siguientes permisos:

La cuenta de servicio personalizada debe tener permiso para escribir en la tabla de BigQuery específica y para leer los metadatos de la tabla.
El agente de servicio de Pub/Sub debe tener el permiso iam.serviceAccounts.getAccessToken en la cuenta de servicio personalizada.
El usuario que cree la suscripción debe tener el permiso iam.serviceAccounts.actAs en la cuenta de servicio personalizada.

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

Crea la cuenta de servicio personalizada. La cuenta de servicio debe estar en el mismo proyecto que la suscripción.
Otorga el rol Editor de datos de BigQuery (roles/bigquery.dataEditor) 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 de BigQuery al agente de servicio de Pub/Sub. 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.
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

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

Ir a Cuentas de servicio
Introduce el nombre de la cuenta de servicio personalizada en el filtro.
Selecciona la cuenta de servicio en la lista.
Haz clic en Principales con acceso.
Haz clic en Conceder acceso.
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.
En el menú desplegable Seleccionar un rol, introduce Service Account y selecciona el rol Creador de tokens de cuenta de servicio.
Haz clic en Guardar.

Proyecto

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

Ir a IAM
Haz clic en Conceder acceso.
En la sección Añadir principales, introduce el nombre de tu cuenta de servicio personalizada.
En la sección Asignar roles, haz clic en Añadir otro rol.
En el menú desplegable Seleccionar un rol, introduce Service Account y selecciona el rol Creador de tokens de cuenta de servicio.
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:

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

Ir a Cuentas de servicio
Introduce el nombre de la cuenta de servicio personalizada en el filtro.
Selecciona la cuenta de servicio en la lista.
Haz clic en Principales con acceso.
Haz clic en Conceder acceso.
En la sección Añadir principales, escribe el nombre de la cuenta a la que quieras dar acceso.
En el menú desplegable Selecciona un rol, introduce Service Account y selecciona el rol Usuario de cuenta de servicio.
Además, si tu tabla de BigQuery es una tabla de Apache Iceberg, concede a la cuenta de servicio de Pub/Sub el rol Administrador de Storage (roles/storage.admin) para acceder al segmento de Cloud Storage.
Haz clic en Guardar.

Propiedades de las suscripciones de BigQuery

Cuando configuras una suscripción a BigQuery, puedes especificar las siguientes propiedades.

Propiedades comunes

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

Usar el esquema de temas

Esta opción permite que Pub/Sub use el esquema del tema de Pub/Sub al que está vinculada la suscripción. Además, Pub/Sub escribe los campos de los mensajes en las columnas correspondientes de la tabla de BigQuery.

Si utilizas esta opción, recuerda que debes cumplir 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 del esquema del tema también debe ser opcional en el esquema de BigQuery.
No es necesario que los campos obligatorios del esquema del 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 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 eliminar, seleccione la opción Eliminar campos desconocidos.
Solo puede seleccionar una de las propiedades de suscripción: Usar esquema de tema o Usar esquema de tabla.

Si no seleccionas la opción Usar esquema de tema o Usar 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 los cambios en el esquema de los temas de Pub/Sub o en el esquema de la tabla de BigQuery no se apliquen inmediatamente a los mensajes escritos en la tabla de BigQuery. Por ejemplo, si la opción Eliminar campos desconocidos está habilitada y hay un campo en el esquema de Pub/Sub, pero no en el de BigQuery, es posible que los mensajes escritos en la tabla de BigQuery sigan sin contener el campo después de añadirlo al esquema de BigQuery. Finalmente, los esquemas se sincronizan y los mensajes posteriores incluyen el campo.

Si utiliza la opción Usar esquema de tema en su suscripción de BigQuery, también puede aprovechar la captura de datos de cambios (CDC) de BigQuery. La CDC actualiza tus tablas de BigQuery procesando y aplicando los cambios a las filas.

Para obtener más información sobre esta función, consulta el artículo Transmitir actualizaciones de tablas con la captura de datos de cambios.

Para saber cómo usar esta función con las suscripciones de BigQuery, consulta el artículo Captura de datos modificados de BigQuery.

Usar el esquema de una 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. Si utiliza esta opción, recuerde que debe cumplir los siguientes requisitos adicionales:

Los nombres de cada columna de la tabla de BigQuery solo pueden contener letras (a-z, A-Z), números (0-9) o guiones bajos (_).
Los mensajes publicados deben estar en formato JSON.

Se admiten las siguientes conversiones JSON:

Tipo JSON	Tipo de datos de BigQuery
`string`	`NUMERIC`, `BIGNUMERIC`, `DATE`, `TIME`, `DATETIME` o `TIMESTAMP`
`number`	`NUMERIC`, `BIGNUMERIC`, `DATE`, `TIME`, `DATETIME` o `TIMESTAMP`

Cuando se usan conversiones de number a DATE, DATETIME, TIME o TIMESTAMP, el número debe cumplir las representaciones admitidas.
Cuando se usa la conversión de number a NUMERIC o BIGNUMERIC, la precisión y el intervalo de valores se limitan a los aceptados por el estándar IEEE 754 para la aritmética de coma flotante. Si necesitas una alta precisión o un intervalo de valores más amplio, usa las conversiones de string a NUMERIC o BIGNUMERIC.
Cuando se usan conversiones de string a NUMERIC o BIGNUMERIC, Pub/Sub asume que la cadena es un número legible (por ejemplo, "123.124"). Si no se puede procesar la cadena como un número legible, Pub/Sub la trata como bytes codificados con BigDecimalByteStringEncoder.

Si el tema de la suscripción tiene un esquema asociado, la propiedad de codificación de mensajes debe tener el valor JSON.
Si hay campos de BigQuery que no están presentes en los mensajes, estos campos deben estar en el modo NULLABLE.
Si los mensajes tienen campos adicionales que no están presentes en el esquema de BigQuery y estos campos se pueden eliminar, selecciona la opción Eliminar campos desconocidos.
Solo puede seleccionar una de las propiedades de suscripción: Usar esquema de tema o Usar esquema de tabla.

Es posible que los cambios en el esquema de la tabla de BigQuery no se apliquen inmediatamente a los mensajes escritos en la tabla de BigQuery. Por ejemplo, si la opción Eliminar campos desconocidos está habilitada y hay un campo en los mensajes, pero no en el esquema de BigQuery, es posible que los mensajes escritos en la tabla de BigQuery sigan sin contener el campo después de añadirlo al esquema de BigQuery. Finalmente, el esquema se sincroniza y los mensajes posteriores incluyen el campo.

Si utiliza la opción Usar esquema de tabla en su suscripción de BigQuery, también puede aprovechar la captura de datos de cambios (CDC) de BigQuery. La CDC actualiza tus tablas de BigQuery procesando y aplicando los cambios a las filas.

Para obtener más información sobre esta función, consulta el artículo Transmitir actualizaciones de tablas con la captura de datos de cambios.

Para saber cómo usar esta función con las suscripciones de BigQuery, consulta el artículo Captura de datos modificados de BigQuery.

Eliminar campos desconocidos

Esta opción se usa con las opciones Usar esquema de tema o Usar esquema de tabla. Cuando está habilitada, esta opción permite que Pub/Sub elimine cualquier campo que esté presente en el esquema del tema o del mensaje, pero no en el esquema de BigQuery. Los campos que no forman parte del esquema de BigQuery se eliminan al escribir el mensaje en la tabla de BigQuery.

Si no se ha definido la opción Eliminar campos desconocidos, los mensajes con campos adicionales no se escriben en BigQuery y permanecen en la acumulación de la suscripción, a menos que configure un tema de mensajes fallidos.

El ajuste Eliminar campos desconocidos no afecta a los campos que no se definen en el esquema del tema de Pub/Sub ni en el esquema de la tabla de BigQuery. En este caso, se envía un mensaje de Pub/Sub válido a la suscripción. Sin embargo, como BigQuery no tiene columnas definidas para estos campos adicionales, se eliminan durante el proceso de escritura de BigQuery. Para evitar este comportamiento, asegúrate de que todos los campos incluidos en el mensaje de Pub/Sub también estén incluidos en el esquema de la tabla de BigQuery.

El comportamiento en relación con los campos adicionales también puede depender del tipo de esquema específico (Avro o Protocol Buffer) y de la codificación (JSON o binaria) que se utilicen. Para obtener información sobre cómo afectan estos factores a la gestión de campos adicionales, consulta la documentación de tu tipo de esquema y codificación específicos.

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 escribirán en la tabla de BigQuery.

Si selecciona la opción Escribir metadatos, asegúrese de que la tabla de BigQuery tenga los campos descritos en la siguiente tabla.

Si no selecciona la opción Escribir metadatos, la tabla de BigQuery de destino solo requerirá el campo data, a menos que use_topic_schema sea true. Si selecciona las opciones Escribir metadatos y Usar esquema de tema, el esquema del tema no debe contener ningún campo con nombres que coincidan con los de los parámetros de metadatos. Esta limitación incluye las versiones en camel case de estos parámetros en snake case.

Parámetros
`subscription_name`	STRING Nombre de una suscripción.
`message_id`	STRING ID de un mensaje
`publish_time`	TIMESTAMP La hora de publicación de un mensaje.
`data`	BYTES, STRING o JSON El cuerpo del mensaje. El campo `data` es obligatorio para todas las tablas de BigQuery de destino que no seleccionen Usar esquema de tema o Usar esquema de tabla. Si el campo es de tipo JSON, el cuerpo del mensaje debe ser un JSON válido.
`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 ordenación, si está presente.

Crear una suscripción de BigQuery

En los siguientes ejemplos se muestra cómo crear una suscripción con entrega de BigQuery.

Consola

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

Ir a Suscripciones
Haz clic en Crear suscripción.
En el campo ID de suscripción, introduce un nombre. Para obtener información sobre cómo asignar un nombre a una suscripción, consulta las directrices para asignar un nombre a un tema o a una suscripción.
Elige o crea un tema en el menú desplegable. La suscripción recibe mensajes del tema.
Seleccione Tipo de publicación y, a continuación, Escribir en BigQuery.
Selecciona el proyecto de la tabla de BigQuery.
Selecciona un conjunto de datos o crea uno. Para obtener información sobre cómo crear un conjunto de datos, consulta Crear conjuntos de datos.
Seleccione una tabla que ya tenga o cree una. Para obtener información sobre cómo crear una tabla, consulta el artículo Crear tablas.
Te recomendamos que habilites Dead lettering para gestionar los errores de mensajes. Para obtener más información, consulta el artículo Tema de mensajes fallidos.
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 Google Cloud consola, ve a la página Temas.

Ir a Temas
Haz clic en junto al tema del que quieras crear una suscripción.
En el menú contextual, selecciona Crear suscripción.
Seleccione Tipo de publicación y, a continuación, Escribir en BigQuery.
Selecciona el proyecto de la tabla de BigQuery.
Selecciona un conjunto de datos o crea uno. Para obtener información sobre cómo crear un conjunto de datos, consulta Crear conjuntos de datos.
Seleccione una tabla que ya tenga o cree una. Para obtener información sobre cómo crear un conjunto de datos, consulta Crear tablas.
Te recomendamos que habilites Dead lettering para gestionar los errores de mensajes. Para obtener más información, consulta el artículo Tema de mensajes fallidos.
Haz clic en Crear.

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

Para crear una suscripción de 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
```
Si quieres usar una cuenta de servicio personalizada, proporciónala como argumento adicional:
```
gcloud pubsub subscriptions create SUBSCRIPTION_ID \
    --topic=TOPIC_ID \
    --bigquery-table=PROJECT_ID.DATASET_ID.TABLE_ID 
    --bigquery-service-account-email=SERVICE_ACCOUNT_NAME
```
Haz los cambios siguientes:
- 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. Para crear un conjunto de datos, consulta Crear conjuntos de datos.
- TABLE_ID: especifica el ID de una tabla ya creada. La tabla requiere un campo data si tu tema no tiene un esquema. Para crear una tabla, consulta Crear una tabla vacía con una definición de esquema.
- SERVICE_ACCOUNT_NAME: especifica el nombre de la cuenta de servicio que se usará para escribir en BigQuery.

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 sobre cómo usar bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API de C++ de Pub/Sub.

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& table_id) {
  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_bigquery_config()->set_table(table_id);
  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 sobre cómo usar bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API de C# de Pub/Sub.


using Google.Cloud.PubSub.V1;

public class CreateBigQuerySubscriptionSample
{
    public Subscription CreateBigQuerySubscription(string projectId, string topicId, string subscriptionId, string bigqueryTableId)
    {
        SubscriberServiceApiClient subscriber = SubscriberServiceApiClient.Create();
        TopicName topicName = TopicName.FromProjectTopic(projectId, topicId);
        SubscriptionName subscriptionName = SubscriptionName.FromProjectSubscription(projectId, subscriptionId);

        var subscriptionRequest = new Subscription
        {
            SubscriptionName = subscriptionName,
            TopicAsTopicName = topicName,
            BigqueryConfig = new BigQueryConfig
            {
                Table = bigqueryTableId
            }
        };
        var subscription = subscriber.CreateSubscription(subscriptionRequest);
        return subscription;
    }
}

Go

En el siguiente ejemplo se usa la versión principal de la biblioteca de cliente de Pub/Sub de Go (v2). Si sigues usando la biblioteca v1, consulta la guía de migración a la versión 2. Para ver una lista de ejemplos de código de la versión 1, consulta los ejemplos de código obsoletos.

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

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsub/v2"
	"cloud.google.com/go/pubsub/v2/apiv1/pubsubpb"
)

// createBigQuerySubscription creates a Pub/Sub subscription that exports messages to BigQuery.
func createBigQuerySubscription(w io.Writer, projectID, topic, subscription, table string) error {
	// projectID := "my-project"
	// topic := "projects/my-project-id/topics/my-topic"
	// subscription := "projects/my-project/subscriptions/my-sub"
	// table := "my-project-id.dataset_id.table_id"
	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,
		BigqueryConfig: &pubsubpb.BigQueryConfig{
			Table:         table,
			WriteMetadata: true,
		},
	})
	if err != nil {
		return fmt.Errorf("failed to create subscription: %w", err)
	}
	fmt.Fprintf(w, "Created BigQuery 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 sobre cómo usar bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API de Java de Pub/Sub.

import com.google.cloud.pubsub.v1.SubscriptionAdminClient;
import com.google.pubsub.v1.BigQueryConfig;
import com.google.pubsub.v1.ProjectSubscriptionName;
import com.google.pubsub.v1.ProjectTopicName;
import com.google.pubsub.v1.Subscription;
import java.io.IOException;

public class CreateBigQuerySubscriptionExample {
  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 bigqueryTableId = "your-project.your-dataset.your-table";

    createBigQuerySubscription(projectId, topicId, subscriptionId, bigqueryTableId);
  }

  public static void createBigQuerySubscription(
      String projectId, String topicId, String subscriptionId, String bigqueryTableId)
      throws IOException {
    try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {

      ProjectTopicName topicName = ProjectTopicName.of(projectId, topicId);
      ProjectSubscriptionName subscriptionName =
          ProjectSubscriptionName.of(projectId, subscriptionId);

      BigQueryConfig bigqueryConfig =
          BigQueryConfig.newBuilder().setTable(bigqueryTableId).setWriteMetadata(true).build();

      Subscription subscription =
          subscriptionAdminClient.createSubscription(
              Subscription.newBuilder()
                  .setName(subscriptionName.toString())
                  .setTopic(topicName.toString())
                  .setBigqueryConfig(bigqueryConfig)
                  .build());

      System.out.println("Created a BigQuery 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 sobre cómo usar bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API de Node.js de Pub/Sub.

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';
// const subscriptionNameOrId = 'YOUR_SUBSCRIPTION_NAME_OR_ID';
// const bigqueryTableId = 'YOUR_TABLE_ID';

// 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 createBigQuerySubscription(
  topicNameOrId,
  subscriptionNameOrId,
  bigqueryTableId,
) {
  const options = {
    bigqueryConfig: {
      table: bigqueryTableId,
      writeMetadata: true,
    },
  };

  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId, options);

  console.log(`Subscription ${subscriptionNameOrId} created.`);
}

Node.ts

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';
// const subscriptionNameOrId = 'YOUR_SUBSCRIPTION_NAME_OR_ID';
// const bigqueryTableId = 'YOUR_TABLE_ID';

// Imports the Google Cloud client library
import {PubSub, CreateSubscriptionOptions} from '@google-cloud/pubsub';

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function createBigQuerySubscription(
  topicNameOrId: string,
  subscriptionNameOrId: string,
  bigqueryTableId: string,
) {
  const options: CreateSubscriptionOptions = {
    bigqueryConfig: {
      table: bigqueryTableId,
      writeMetadata: true,
    },
  };

  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId, options);

  console.log(`Subscription ${subscriptionNameOrId} created.`);
}

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 sobre cómo usar bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API de Pub/Sub para PHP.

use Google\Cloud\PubSub\PubSubClient;
use Google\Cloud\PubSub\V1\BigQueryConfig;

/**
 * Creates a Pub/Sub BigQuery 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 $table      The BigQuery table to which to write.
 */
function create_bigquery_subscription($projectId, $topicName, $subscriptionName, $table)
{
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);
    $topic = $pubsub->topic($topicName);
    $subscription = $topic->subscription($subscriptionName);
    $config = new BigQueryConfig(['table' => $table]);
    $subscription->create([
        'bigqueryConfig' => $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 sobre cómo usar bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API de Python de Pub/Sub.

from google.cloud import pubsub_v1

# TODO(developer)
# project_id = "your-project-id"
# topic_id = "your-topic-id"
# subscription_id = "your-subscription-id"
# bigquery_table_id = "your-project.your-dataset.your-table"

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)

bigquery_config = pubsub_v1.types.BigQueryConfig(
    table=bigquery_table_id, write_metadata=True
)

# 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,
            "bigquery_config": bigquery_config,
        }
    )

print(f"BigQuery subscription created: {subscription}.")
print(f"Table for subscription is: {bigquery_table_id}")

Ruby

En el siguiente ejemplo se usa la biblioteca de cliente de Ruby Pub/Sub v3. Si sigues usando la biblioteca v2, consulta la guía de migración a la versión 3. Para ver una lista de ejemplos de código de Ruby v2, consulta los ejemplos de código obsoletos.

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

# project_id = "your-project-id"
# topic_id = "your-topic-id"
# subscription_id = "your-subscription-id"
# bigquery_table_id = "my-project:dataset-id.table-id"

pubsub = Google::Cloud::PubSub.new project_id: project_id
subscription_admin = pubsub.subscription_admin

subscription = subscription_admin.create_subscription \
  name: pubsub.subscription_path(subscription_id),
  topic: pubsub.topic_path(topic_id),
  bigquery_config: {
    table: bigquery_table_id,
    write_metadata: true
  }

puts "BigQuery subscription created: #{subscription_id}."
puts "Table for subscription is: #{bigquery_table_id}"

Monitorizar una suscripción de BigQuery

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

Crea o modifica una suscripción con los comandos de gcloud.
Crea o modifica una suscripción con las APIs REST.
Soluciona problemas con una suscripción a BigQuery.

Crear suscripciones a BigQuery Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

Antes de empezar

Roles y permisos necesarios

Permisos obligatorios

Asignar roles a cuentas de servicio

Asignar roles de BigQuery al agente de servicio de Pub/Sub

Tabla

Proyecto

Asignar roles de BigQuery a una cuenta de servicio personalizada

Cuenta de servicio

Proyecto

Propiedades de las suscripciones de BigQuery

Propiedades comunes

Usar el esquema de temas

Usar el esquema de una tabla

Eliminar campos desconocidos

Escribir metadatos

Crear una suscripción de BigQuery

Consola

gcloud

C++

C#

Go

Java

Node.js

Node.ts

PHP

Python

Ruby

Monitorizar una suscripción de BigQuery

Siguientes pasos

Crear suscripciones a BigQuery