Neste documento, descrevemos como criar uma assinatura do BigQuery. É possível usar o console do Google Cloud, a CLI do Google Cloud, 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 tópicos:
Como as assinaturas funcionam.
O fluxo de trabalho das assinaturas do BigQuery.
Como configurar um tópico de mensagens inativas para lidar com falhas de mensagens.
Além de conhecer o Pub/Sub e o BigQuery, verifique se você atende aos pré-requisitos a seguir antes de criar uma assinatura do BigQuery:
Existe uma tabela do BigQuery. Como alternativa, crie um ao criar a assinatura do BigQuery, conforme descrito em nas próximas seções deste documento.
Compatibilidade entre o esquema do tópico do Pub/Sub e a tabela do BigQuery. Se você adicionar um bloco de anúncios Tabela do BigQuery, você recebe um erro relacionado à compatibilidade mensagem. Para mais informações, consulte Compatibilidade de esquema.
Papéis e permissões necessárias
Confira a seguir uma lista de diretrizes sobre funções e permissões:
Para criar uma assinatura, você precisa configurar o controle de acesso no projeto nível
Você também precisa de permissões no nível do recurso se as suas assinaturas e tópicos estiverem em projetos diferentes, conforme discutido mais adiante nesta seção.
Para criar uma assinatura do BigQuery, a conta de serviço do Pub/Sub precisa ter permissão para gravar na tabela específica do BigQuery. Para mais informações sobre como conceder essas permissões, consulte a próxima seção deste documento.
É possível configurar uma assinatura do BigQuery em um projeto para gravar em uma tabela do BigQuery em outro projeto.
Para receber as permissões necessárias para criar assinaturas 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 assinaturas do BigQuery. Para conferir 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 assinaturas do BigQuery:
-
Extrair de uma assinatura:
pubsub.subscriptions.consume
-
Criar uma assinatura:
pubsub.subscriptions.create
-
Para excluir uma assinatura:
pubsub.subscriptions.delete
-
Receber uma assinatura:
pubsub.subscriptions.get
-
Para listar uma assinatura:
pubsub.subscriptions.list
-
Atualizar uma assinatura:
pubsub.subscriptions.update
-
Anexe uma assinatura a um tópico:
pubsub.topics.attachSubscription
-
Acesse a política do IAM para uma assinatura:
pubsub.subscriptions.getIamPolicy
-
Configure a política do IAM para uma assinatura:
pubsub.subscriptions.setIamPolicy
Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.
Se você precisar criar modelos do BigQuery
assinaturas de um projeto que estão associadas a um tópico em outro
projeto, peça ao administrador do tópico para conceder a você o papel Editor do Pub/Sub
(roles/pubsub.editor)
no tópico.
Atribuir papéis do BigQuery à conta de serviço do Pub/Sub
Alguns serviços do Google Cloud têm contas serviço gerenciado pelo Google Cloud, o que permite
e serviços acessem seus recursos. Essas contas são
conhecidos como agentes de serviço. O Pub/Sub cria e mantém
conta de serviço para cada projeto no formato
service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com
:
Para criar uma assinatura do BigQuery, conta de serviço precisa ter permissão para gravar à tabela específica do BigQuery e ler os respectivos metadados.
Conceda o papel de editor de dados do BigQuery (roles/bigquery.dataEditor
)
à conta de serviço do Pub/Sub.
No console do Google Cloud, abra a página IAM.
Clique em Conceder acesso.
Na seção Adicionar principais, insira o nome da sua conta de serviço do Pub/Sub. O formato da conta de serviço é
service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com
. Por exemplo, para um projeto comproject-number=112233445566
, a conta de serviço tem o formatoservice-112233445566@gcp-sa-pubsub.iam.gserviceaccount.com
.Na seção Atribuir papéis, clique em Adicionar outro papel.
No menu suspenso Selecionar papel, insira
BigQuery
. e selecione o papel Editor de dados do BigQuery.Clique em Salvar.
Para mais informações sobre o IAM do BigQuery, consulte Permissões e papéis do BigQuery.
Propriedades de assinatura do BigQuery
Ao configurar uma assinatura do BigQuery, é possível especificar as seguintes propriedades.
Propriedades comuns
Saiba mais sobre as propriedades comuns de assinatura que podem ser definidas em todas as assinaturas.
Usar esquema de tópicos
Essa opção permite que o Pub/Sub use o esquema do tópico do Pub/Sub ao qual a assinatura está anexada. Além disso, o Pub/Sub grava os campos nas mensagens para colunas na tabela do BigQuery.
Ao usar essa opção, verifique os seguintes requisitos adicionais:
Os campos no esquema do tópico e no BigQuery precisam ter os mesmos nomes, e os tipos precisam ser compatíveis entre si.
Qualquer campo opcional no esquema do tópico também precisa ser opcional no esquema do BigQuery.
Os campos obrigatórios no esquema do tópico 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, esses campos do BigQuery precisa estar no modo
NULLABLE
.Se o esquema de tópicos tiver outros campos que não estão presentes no esquema do BigQuery, campos podem 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
de
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 tabela do BigQuery não entrem em vigor imediatamente com as mensagens gravadas na tabela do BigQuery. Por exemplo, se o Drop a opção de campos desconhecidos está ativada e há um campo presente na o esquema do Pub/Sub, mas não o do BigQuery, mensagens gravadas na tabela do BigQuery podem não conter depois de adicioná-lo ao esquema do BigQuery. Eventualmente, os esquemas são sincronizados e as mensagens seguintes incluem o campo.
Ao usar a opção Usar esquema de tópico na sua assinatura do BigQuery, você também pode aproveitar a captura de dados de mudança (CDC) do BigQuery. O CDC atualiza suas tabelas do BigQuery processar e aplicar alterações às linhas existentes.
Para saber mais sobre esse recurso, consulte Fazer streaming de atualizações da tabela com captura de dados alterados.
Para aprender a usar esse recurso com assinaturas do BigQuery, consulte Captura de dados alterados do BigQuery.
Usar esquema de tabela
Essa opção permite que o Pub/Sub use o esquema do tabela do BigQuery para gravar os campos de uma às colunas correspondentes. Ao usar essa opção, verifique os seguintes requisitos adicionais:
As mensagens publicadas precisam estar no formato JSON.
As seguintes conversões JSON são compatíveis:
Tipo JSON Tipo de dados do BigQuery string
NUMERIC
,BIGNUMERIC
,DATE
,TIME
,DATETIME
ouTIMESTAMP
number
NUMERIC
,BIGNUMERIC
,DATE
,TIME
,DATETIME
ouTIMESTAMP
- Ao usar conversões de
number
paraDATE
,DATETIME
,TIME
ouTIMESTAMP
, o número precisa aderir às representações compatíveis. - Ao usar a conversão de
number
paraNUMERIC
ouBIGNUMERIC
, 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 as conversões destring
paraNUMERIC
ouBIGNUMERIC
. - Ao usar conversões de
string
paraNUMERIC
ouBIGNUMERIC
, o Pub/Sub presume que a string é um número legível por humanos (por exemplo,"123.124"
). Se o processamento da string como um número legível por humanos falhar, o Pub/Sub vai tratar a string como bytes codificados com o BigDecimalByteStringEncoder.
- Ao usar conversões de
Se o tópico da assinatura tem um esquema associado, a propriedade de codificação de mensagem precisa 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 presentes no esquema do BigQuery e esses campos puderem ser descartados, selecione a opção Drop unknown fields.
É possível selecionar apenas uma das propriedades de assinatura: Usar esquema de tópicos 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
de
digite BYTES
, STRING
ou JSON
. O Pub/Sub grava a mensagem nessa coluna do BigQuery.
Talvez você não veja as alterações no esquema da tabela do BigQuery imediatamente com mensagens gravadas na tabela do BigQuery. Por exemplo, se a opção Drop unknown fields 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. Em algum momento, o esquema será sincronizado, e as mensagens subsequentes incluirão 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. O CDC atualiza as tabelas do BigQuery processando e aplicando alterações a tabelas linhas
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.
Remover campos desconhecidos
Essa opção é usada com a opção Usar esquema de tópicos ou Usar esquema de tabela. Essa opção permite que o Pub/Sub remova qualquer campo presente no tópico ou mensagem, mas não no esquema do BigQuery. Sem a configuração Drop unknown fields, as mensagens com campos extras não são gravadas no BigQuery e permanecem no backlog de assinaturas. A assinatura acaba em um estado de erro.
Gravar metadados
Essa opção permite que o Pub/Sub grave os metadados de cada mensagem em outras colunas na tabela do BigQuery. Caso contrário, os metadados não sã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 de destino do BigQuery 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ópicos, o esquema do tópico não poderá
conter campos com nomes que correspondam aos dos parâmetros de metadados.
Essa limitação inclui versões em CamelCase desses parâmetros de caixa baixa.
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 |
attributes |
STRING ou JSON Um objeto JSON que contém todos os atributos de mensagem. Ela também contém campos adicionais que fazem parte Mensagem do Pub/Sub, incluindo a chave de ordem, se estiver presente. |
Criar uma assinatura do BigQuery
Os exemplos a seguir demonstram como criar uma assinatura com entrega do BigQuery.
Console
- No console do Google Cloud, acesse página Assinaturas.
- Clique em Criar assinatura.
- Insira um nome no campo ID da assinatura.
Para informações sobre como nomear uma inscrição, consulte Diretrizes para nomear um tópico ou uma assinatura.
- Escolha ou crie um tópico no menu suspenso. A assinatura recebe mensagens do tópico.
- Selecione Tipo de entrega como Gravar no BigQuery.
- Selecione o projeto para a tabela do BigQuery.
- Selecione um conjunto de dados ou crie um novo.
Para saber como criar um conjunto de dados, consulte Como criar conjuntos de dados.
- Selecione uma tabela ou crie uma nova.
Para saber como criar uma tabela, consulte Como criar tabelas.
- É altamente recomendável ativar a letra
morta para processar falhas de mensagens.
Para mais informações, consulte Tópico de mensagens inativas.
- Clique em Criar.
Você também pode criar uma assinatura na página Tópicos. Esse atalho é útil para associar tópicos a assinaturas.
- No console do Google Cloud, acesse a página Topics página.
- Clique no more_vert ao lado do tópico desejado. para criar uma assinatura.
- No menu de contexto, selecione Criar assinatura.
- Selecione Tipo de entrega como Gravar no BigQuery.
- Selecione o projeto para a tabela do BigQuery.
- Selecione um conjunto de dados ou crie um.
Para informações sobre como criar um conjunto de dados, consulte Como criar conjuntos de dados.
- Selecione uma tabela ou crie uma nova.
Para saber como criar um conjunto de dados, consulte Como criar tabelas.
- Recomendamos que você ative a opção morta
o uso de letras para lidar com falhas de mensagens.
Para mais informações, consulte Tópico de mensagens inativas.
- Clique em Criar.
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 criar uma assinatura do Pub/Sub, use o
gcloud pubsub subscriptions create
comando:gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --bigquery-table=PROJECT_ID:DATASET_ID.TABLE_ID
Substitua:
- SUBSCRIPTION_ID: especifica o ID da assinatura.
- TOPIC_ID: especifica o ID do tópico. O requer um esquema.
- PROJECT_ID: especifica o ID do projeto.
- DATASET_ID: especifica o ID de um existente no conjunto de dados. Para criar um conjunto de dados, consulte Criar conjuntos de dados.
- TABLE_ID: especifica o ID de uma tabela existente. A tabela exige um campo data se o tópico não tem um esquema. Para criar uma tabela, consulte Criar uma tabela vazia com uma definição de esquema.
C++
Antes de testar este exemplo, siga as instruções de configuração do C++ na Guia de início rápido do Pub/Sub usando bibliotecas de cliente. Para mais informações, consulte a API C++ do Pub/Sub documentação de referência.
Para autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
C#
Antes de testar este exemplo, siga as instruções de configuração do C# na Guia de início rápido do Pub/Sub usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C#.
Para autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
Go
Antes de testar este exemplo, siga as instruções de configuração do Go na Guia de início rápido do Pub/Sub usando bibliotecas de cliente. Para mais informações, consulte a API Go do Pub/Sub documentação de referência.
Para autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
Java
Antes de testar este exemplo, siga as instruções de configuração do Java na Guia de início rápido do Pub/Sub usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Java.
Para autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
Node.js
Node.js
PHP
Antes de testar este exemplo, siga as instruções de configuração do PHP na Guia de início rápido do Pub/Sub usando bibliotecas de cliente. Para mais informações, consulte a API PHP do Pub/Sub documentação de referência.
Para autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
Python
Antes de testar esta amostra, siga as instruções de configuração do Python no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a API Python do Pub/Sub documentação de referência.
Para autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
Ruby
Antes de testar este exemplo, siga as instruções de configuração do Ruby na Guia de início rápido do Pub/Sub usando bibliotecas de cliente. Para mais informações, consulte a API Ruby do Pub/Sub documentação de referência.
Para autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
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 de monitoramento do Pub/Sub.
Também é possível monitorar as assinaturas no Pub/Sub.
A seguir
- Crie ou modifique uma assinatura com comandos
gcloud
. - Crie ou modifique uma assinatura com as APIs REST.
- Solucione problemas de uma assinatura do BigQuery.