Criar assinaturas do BigQuery

Neste documento, descrevemos como criar uma assinatura do BigQuery. É possível usar o console Google Cloud , a Google Cloud CLI, a biblioteca de cliente ou a API Pub/Sub para criar uma assinatura do BigQuery.

Antes de começar

Antes de ler este documento, confira se você conhece os seguintes conceitos:

Como as assinaturas funcionam.
O fluxo de trabalho para assinaturas do BigQuery.
Como configurar um tópico de mensagens inativas para lidar com falhas de mensagens.

Além de ter familiaridade com o Pub/Sub e o BigQuery, verifique se você atende aos seguintes pré-requisitos antes de criar uma assinatura do BigQuery:

Uma tabela do BigQuery existe. Ou crie uma ao criar a assinatura do BigQuery, conforme descrito nas seções posteriores deste documento.
Compatibilidade entre o esquema do tópico do Pub/Sub e a tabela do BigQuery. Se você adicionar uma tabela do BigQuery incompatível, vai receber uma mensagem de erro relacionada à compatibilidade. Para mais informações, consulte Compatibilidade de esquema.

Papéis e permissões necessárias

Para receber as permissões necessárias para criar uma assinatura do BigQuery, peça ao administrador para conceder a você o papel do IAM de Editor do Pub/Sub (roles/pubsub.editor) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém as permissões necessárias para criar uma assinatura do BigQuery. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para criar uma assinatura do BigQuery:

pubsub.subscriptions.create no projeto
pubsub.topics.attachSubscription no tópico

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Assinaturas entre projetos

Se você criar uma assinatura em um projeto para um tópico em outro, será necessário ter a permissão pubsub.subscriptions.create no projeto em que você está criando a assinatura e a permissão pubsub.topics.attachSubscription no tópico.

Conceder papéis do IAM à conta de serviço

O Pub/Sub usa uma conta de serviço do Identity and Access Management (IAM) para acessar recursos do Google Cloud . Por padrão, ele usa o agente de serviço do Pub/Sub (service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com).

Para permitir que o Pub/Sub grave em uma tabela do BigQuery, a conta de serviço precisa da função Editor de dados do BigQuery (roles/bigquery.dataEditor). É possível conceder permissões à conta de serviço para o projeto ou a tabela, da seguinte forma:

Projeto

No console do Google Cloud , acesse a página IAM.

Acessar IAM
Selecione Incluir concessões de papel fornecidas pelo Google.
Localize a linha da conta de serviço do Cloud Pub/Sub e clique em Editar principal.
Clique em Adicionar outro papel e selecione o papel Editor de dados do BigQuery.

Para mais informações, consulte Conceder um papel do IAM usando o console.

Tabela

No Google Cloud console, acesse o BigQuery Studio.

Acessar o BigQuery Studio
Na caixa de pesquisa do painel "Explorador" chamada Filtrar por nome e rótulos, digite o nome da tabela e pressione Enter.
Nos resultados da pesquisa, clique no nome da tabela a que você quer conceder permissão.
Na guia Detalhes, clique em Compartilhar > Gerenciar permissões.
Clique em Adicionar principal e insira o identificador da conta de serviço no seguinte formato:

service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com.
Na lista Atribuir papéis, selecione Editor de dados do BigQuery.
Clique em Salvar. O principal recebe o papel no recurso.

Usar uma conta de serviço personalizada

Ao conceder o papel de Editor de dados do BigQuery à conta de serviço do Cloud Pub/Sub, qualquer usuário com permissão para criar uma assinatura no seu projeto pode gravar na tabela do BigQuery. Se você quiser fornecer permissões mais granulares, configure uma conta serviço gerenciado pelo usuário.

As seguintes permissões são necessárias para configurar uma conta de serviço gerenciado pelo usuário para gravar no BigQuery:

A conta de serviço gerenciado pelo usuário precisa ter o papel de Editor de dados do BigQuery.
A conta de serviço do Cloud Pub/Sub precisa ter a permissão iam.serviceAccounts.getAccessToken na conta de serviço gerenciado pelo usuário.
O usuário que cria a assinatura precisa ter a permissão iam.serviceAccounts.actAs na conta de serviço gerenciado pelo usuário.

Ao criar a assinatura, especifique a conta de serviço gerenciado pelo usuário como a conta de serviço da assinatura.

Propriedades da assinatura do BigQuery

As assinaturas do BigQuery são compatíveis com todas as propriedades comuns de assinatura. As seções a seguir descrevem propriedades específicas das assinaturas do BigQuery.

Usar esquema de tópicos

Com essa opção, o Pub/Sub usa o esquema do tópico do Pub/Sub a que a assinatura está anexada. Além disso, o Pub/Sub grava os campos nas mensagens nas colunas correspondentes da tabela do BigQuery.

Ao usar essa opção, verifique os seguintes requisitos adicionais:

Os campos no esquema de tópicos e no esquema do BigQuery precisam ter os mesmos nomes e tipos compatíveis entre si.
Qualquer campo opcional no esquema de tópicos também precisa ser opcional no esquema do BigQuery.
Os campos obrigatórios no esquema de tópicos não precisam ser obrigatórios no esquema do BigQuery.
Se houver campos do BigQuery que não estão presentes no esquema de tópicos, eles precisam estar no modo NULLABLE.
Se o esquema de tópico tiver campos extras que não estão presentes no esquema do BigQuery e puderem ser descartados, selecione a opção Descartar campos desconhecidos.
Você pode selecionar apenas uma das propriedades de assinatura: Usar esquema de tópico ou Usar esquema de tabela.

Se você não selecionar a opção Usar esquema de tópicos ou Usar esquema de tabela, verifique se a tabela do BigQuery tem uma coluna chamada data do tipo BYTES, STRING ou JSON. O Pub/Sub grava a mensagem nessa coluna do BigQuery.

Talvez as mudanças no esquema de tópicos do Pub/Sub ou no esquema de tabelas do BigQuery não entrem em vigor imediatamente com as mensagens gravadas na tabela do BigQuery. Por exemplo, se a opção Descartar campos desconhecidos estiver ativada e um campo estiver presente no esquema do Pub/Sub, mas não no do BigQuery, as mensagens gravadas na tabela do BigQuery ainda poderão não conter o campo depois de adicioná-lo ao esquema do BigQuery. Com o tempo, os esquemas vão se sincronizar, e as mensagens subsequentes vão incluir o campo.

Ao usar a opção Usar esquema de tópico para sua assinatura do BigQuery, você também pode aproveitar a captura de dados alterados (CDC) do BigQuery. A CDC atualiza as tabelas do BigQuery processando e aplicando mudanças às linhas atuais.

Para saber mais sobre esse recurso, consulte Fazer streaming de atualizações da tabela com captura de dados alterados.

Para saber como usar esse recurso com assinaturas do BigQuery, consulte Captura de dados alterados do BigQuery.

Usar esquema de tabela

Com essa opção, o Pub/Sub usa o esquema da tabela do BigQuery para gravar os campos de uma mensagem JSON nas colunas correspondentes. Ao usar essa opção, verifique os seguintes requisitos adicionais:

Os nomes de cada coluna na tabela do BigQuery precisam conter apenas letras (a-z, A-Z), números (0-9) ou sublinhados (_).
As mensagens publicadas precisam estar no formato JSON.

Se uma coluna da tabela do BigQuery tiver o tipo de dados JSON, o campo correspondente na mensagem do Pub/Sub precisará ser um JSON válido em uma string de escape. Por exemplo, para uma coluna chamada myData, o campo de mensagem precisa ser "myData": "{\"key\":\"value\"}". O BigQuery rejeita mensagens que não contêm JSON válido.

As seguintes conversões JSON são compatíveis:

Tipo JSON	Tipo de dados do BigQuery
`string`	`NUMERIC`, `BIGNUMERIC`, `DATE`, `TIME`, `DATETIME` ou `TIMESTAMP`
`number`	`NUMERIC`, `BIGNUMERIC`, `DATE`, `TIME`, `DATETIME` ou `TIMESTAMP`

Ao usar number para DATE, DATETIME, TIME ou TIMESTAMP conversões, o número precisa obedecer às representações aceitas.
Ao usar number para conversão de NUMERIC ou BIGNUMERIC, a precisão e o intervalo de valores são limitados aos aceitos pelo padrão IEEE 754 para aritmética de ponto flutuante. Se você precisar de alta precisão ou um intervalo maior de valores, use conversões de string para NUMERIC ou BIGNUMERIC.
Ao usar string para conversões NUMERIC ou BIGNUMERIC, o Pub/Sub pressupõe que a string é um número legível (por exemplo, "123.124"). Se o processamento da string como um número legível falhar, o Pub/Sub vai tratar a string como bytes codificados com o BigDecimalByteStringEncoder.

Se o tópico da assinatura tiver um esquema associado a ele, a propriedade de codificação da mensagem precisará ser definida como JSON.
Se houver campos do BigQuery que não estão presentes nas mensagens, eles precisam estar no modo NULLABLE.
Se as mensagens tiverem campos adicionais que não estão no esquema do BigQuery e esses campos puderem ser descartados, selecione a opção Descartar campos desconhecidos.
Você pode selecionar apenas uma das propriedades de assinatura: Usar esquema de tópico ou Usar esquema de tabela.

As mudanças no esquema da tabela do BigQuery podem não entrar em vigor imediatamente com as mensagens gravadas na tabela. Por exemplo, se a opção Descartar campos desconhecidos estiver ativada e um campo estiver presente nas mensagens, mas não no esquema do BigQuery, as mensagens gravadas na tabela do BigQuery ainda poderão não conter o campo depois de adicioná-lo ao esquema do BigQuery. Com o tempo, o esquema é sincronizado e as mensagens subsequentes incluem o campo.

Ao usar a opção Usar esquema de tabela na sua assinatura do BigQuery, você também pode aproveitar a captura de dados alterados (CDC) do BigQuery. A CDC atualiza as tabelas do BigQuery processando e aplicando mudanças às linhas existentes.

Para saber mais sobre esse recurso, consulte Fazer streaming de atualizações da tabela com captura de dados alterados.

Para saber como usar esse recurso com assinaturas do BigQuery, consulte Captura de dados de alterações do BigQuery.

Remover campos desconhecidos

Essa opção é usada com as opções Usar esquema de tópicos ou Usar esquema de tabela. Quando ativada, essa opção permite que o Pub/Sub descarte qualquer campo presente no esquema ou na mensagem do tópico, mas não no esquema do BigQuery. Os campos que não fazem parte do esquema do BigQuery são descartados ao gravar a mensagem na tabela do BigQuery.

Sem a opção Descartar campos desconhecidos definida, as mensagens com campos extras não são gravadas no BigQuery e permanecem no backlog da assinatura, a menos que você configure um tópico de mensagens mortas.

A configuração Descartar campos desconhecidos não afeta campos que não estão definidos no esquema de tópico do Pub/Sub ou no esquema de tabela do BigQuery. Nesse caso, uma mensagem válida do Pub/Sub é entregue à assinatura. No entanto, como o BigQuery não tem colunas definidas para esses campos extras, eles são descartados durante o processo de gravação do BigQuery. Para evitar esse comportamento, verifique se todos os campos contidos na mensagem do Pub/Sub também estão no esquema da tabela do BigQuery.

O comportamento em relação a campos extras também pode depender do tipo de esquema específico (Avro, buffer de protocolo) e da codificação (JSON, binário) usados. Para informações sobre como esses fatores afetam o processamento de campos extras, consulte a documentação do tipo de esquema e da codificação específicos.

Gravar metadados

Essa opção permite que o Pub/Sub grave os metadados de cada mensagem em colunas adicionais na tabela do BigQuery. Caso contrário, os metadados não serão gravados na tabela do BigQuery.

Se você selecionar a opção Gravar metadados, verifique se a tabela do BigQuery tem os campos descritos na tabela a seguir.

Se você não selecionar a opção Gravar metadados, a tabela do BigQuery de destino só vai exigir o campo data, a menos que use_topic_schema seja verdadeiro. Se você selecionar as opções Gravar metadados e Usar esquema de tópico, o esquema do tópico não poderá conter campos com nomes iguais aos dos parâmetros de metadados. Essa limitação inclui versões camelcase desses parâmetros snake case.

Parâmetros
`subscription_name`	STRING Nome de uma assinatura.
`message_id`	STRING ID de uma mensagem
`publish_time`	TIMESTAMP O horário de publicação de uma mensagem.
`data`	BYTES, STRING ou JSON O corpo da mensagem. O campo `data` é obrigatório para todas as tabelas de destino do BigQuery que não selecionam Usar esquema de tópico ou Usar esquema de tabela. Se o campo for do tipo JSON, o corpo da mensagem precisa ser um JSON válido.
`attributes`	STRING ou JSON Um objeto JSON que contém todos os atributos da mensagem. Ele também contém outros campos que fazem parte da mensagem do Pub/Sub, incluindo a chave de ordenação, se presente.

Conta de serviço

Confira as opções para gravar mensagens em uma tabela do BigQuery:

Configure uma conta de serviço personalizada para que apenas usuários com a permissão iam.serviceAccounts.actAs na conta de serviço possam criar uma assinatura que grava na tabela. Um exemplo de papel que inclui a permissão iam.serviceAccounts.actAs é o papel Usuário da conta de serviço (roles/iam.serviceAccountUser).
Use o agente de serviço padrão do Pub/Sub, que permite que qualquer usuário com a capacidade de criar assinaturas no projeto crie uma assinatura que grave na tabela. O agente de serviço do Pub/Sub é a configuração padrão quando você não especifica uma conta de serviço personalizada.

Criar uma assinatura do BigQuery

Para criar uma assinatura com entrega do BigQuery, siga estas etapas:

Console

No console do Google Cloud , acesse a página Criar assinatura.

Acessar "Assinaturas"
No campo ID da assinatura, insira um nome. Para informações sobre como nomear uma assinatura, consulte Diretrizes para nomear um tópico ou uma assinatura.
Na caixa Selecionar um tópico do Cloud Pub/Sub, digite ou selecione o tópico para receber mensagens.
Em Tipo de envio, selecione Gravar no BigQuery.
Selecione a tabela do BigQuery:
1. Em Projeto, selecione o projeto Google Cloud que contém a tabela do BigQuery.
2. Em Conjunto de dados, selecione um conjunto de dados existente ou clique em Criar novo conjunto de dados. Para informações sobre como criar um conjunto de dados, consulte Criar conjuntos de dados.
3. No campo Tabela, insira o nome da tabela. Para criar uma tabela, clique no link que leva à página Criar tabela do BigQuery. A página é aberta em uma guia separada. Para mais informações sobre como criar uma tabela, consulte Criar e usar tabelas.
Em Configuração do esquema, selecione uma das seguintes opções:
- Não usar um esquema. O Pub/Sub grava os bytes da mensagem em uma coluna chamada data.
- Usar esquema de tópicos. O Pub/Sub usa o esquema associado ao tópico. Para mais informações, consulte Usar o esquema de tópicos.
- Usar esquema de tabela. O Pub/Sub usa o esquema da tabela do BigQuery. Para mais informações, consulte Usar esquema de tabela.
Opcional. Para gravar metadados da mensagem na tabela do BigQuery, selecione Gravar metadados. Para mais informações, consulte Gravar metadados.
Opcional. Para descartar campos que não estão presentes no esquema da tabela do BigQuery, selecione Descartar campos desconhecidos. Para mais informações, consulte Descartar campos desconhecidos.
Configure as propriedades comuns da assinatura conforme necessário. Recomendamos ativar o envio para fila de mensagens inativas para processar falhas de mensagens. Para mais informações, consulte Tópico de mensagens inativas.
Clique em Criar.

gcloud

No console do Google Cloud , ative o Cloud Shell.

Ativar o Cloud Shell

Na parte de baixo do console Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.
Para criar uma assinatura do Pub/Sub, use o comando gcloud pubsub subscriptions create:
```
gcloud pubsub subscriptions create SUBSCRIPTION_ID \
    --topic=TOPIC_ID \
    --bigquery-table=PROJECT_ID.DATASET_ID.TABLE_ID
```
Se você quiser usar uma conta de serviço personalizada, forneça-a como um 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
```
Substitua:
- SUBSCRIPTION_ID: especifica o ID da assinatura.
- TOPIC_ID: especifica o ID do tema. O tópico exige um esquema.
- PROJECT_ID: especifica o ID do projeto.
- DATASET_ID: especifica o ID de um conjunto de dados existente. Para criar um conjunto de dados, consulte Criar conjuntos de dados.
- TABLE_ID: especifica o ID de uma tabela atual. A tabela precisa de um campo data se o tópico não tiver um esquema. Para criar uma tabela, consulte Criar uma tabela vazia com uma definição de esquema.
- SERVICE_ACCOUNT_NAME: especifica o nome da conta de serviço a ser usada para gravar no BigQuery.

C++

Antes de tentar esse exemplo, siga as instruções de configuração do C++ em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C++.

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 tentar esse exemplo, siga as instruções de configuração do C# em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C#.


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

O exemplo a seguir usa a versão principal da biblioteca de cliente do Go Pub/Sub (v2). Se você ainda estiver usando a biblioteca v1, consulte o guia de migração para a v2. Para conferir uma lista de exemplos de código da v1, consulte os exemplos de código descontinuados.

Antes de tentar esse exemplo, siga as instruções de configuração do Go em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Go.

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 tentar essa amostra, siga as instruções de configuração do Java em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Java.

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 tentar essa amostra, siga as instruções de configuração do Node.js em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Node.js.

/**
 * 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 tentar esse exemplo, siga as instruções de configuração do PHP em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub 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 tentar esse exemplo, siga as instruções de configuração do Python em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Python.

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

O exemplo a seguir usa a biblioteca de cliente do Ruby Pub/Sub v3. Se você ainda estiver usando a biblioteca v2, consulte o guia de migração para a v3. Para conferir uma lista de exemplos de código do Ruby v2, consulte os exemplos de código descontinuados.

Antes de tentar esse exemplo, siga as instruções de configuração do Ruby em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Ruby.

# 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}"

Monitorar uma assinatura do BigQuery

O Cloud Monitoring oferece várias métricas para monitorar assinaturas.

Para conferir uma lista de todas as métricas disponíveis relacionadas ao Pub/Sub e as descrições delas, consulte a documentação do Monitoring para o Pub/Sub.

Você também pode monitorar as assinaturas no Pub/Sub.

A seguir

Crie ou modifique uma assinatura com comandos gcloud.
Crie ou modifique uma assinatura com APIs REST.
Resolver problemas de uma assinatura do BigQuery.