Criar assinaturas do Bigtable

Neste documento, descrevemos como criar uma assinatura do Bigtable no Pub/Sub. Com as assinaturas do Bigtable, é possível gravar mensagens do Pub/Sub diretamente em uma tabela do Bigtable.

Para mais informações sobre esse tipo de assinatura, consulte Assinaturas do Bigtable.

Antes de começar

A tabela do Bigtable em que você quer gravar mensagens do Pub/Sub precisa existir. Para mais informações, consulte Criar e gerenciar tabelas.
A tabela precisa ter um grupo de colunas chamado data. É possível adicionar a família de colunas ao criar a tabela.
Se você quiser gravar metadados de mensagens na tabela, ela também precisará ter um grupo de colunas chamado pubsub_metadata.

Papéis e permissões necessárias

Para receber as permissões necessárias para criar uma assinatura do Bigtable, 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 Bigtable. 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 Bigtable:

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 . Para permitir que o Pub/Sub grave no Bigtable, conceda o papel de Usuário do Bigtable (roles/bigtable.user) a essa conta de serviço.

Por padrão, o Pub/Sub usa o agente de serviço do Pub/Sub
(service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com). Também é possível especificar uma conta de serviço gerenciado pelo usuário ao criar a assinatura do Bigtable.

Usar o agente de serviço do Pub/Sub

Para conceder o papel necessário ao agente de serviço do Pub/Sub, siga estas etapas. É possível conceder o papel no projeto ou na instância do Bigtable que contém a tabela.

Projeto

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

Acessar IAM
Selecione Incluir concessões de papel fornecidas pelo Google.
Encontre a linha da Conta de serviço do Cloud Pub/Sub e clique em Editar principal.
Clique em Adicionar outro papel e selecione a função Usuário do Bigtable.

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

Instância

No console do Google Cloud , acesse a página Bigtable > Instâncias.

Acesse "Instâncias"
Na página Instâncias, marque a caixa de seleção ao lado do nome da instância.
Se o painel de informações não estiver visível, clique em Mostrar painel de informaçõ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 Usuário do Bigtable.
Clique em Salvar. O principal recebe o papel no recurso.

Usar uma conta de serviço personalizada

Se você conceder o papel Usuário do Bigtable ao agente de serviço do Pub/Sub, qualquer usuário com permissão para criar uma assinatura no seu projeto poderá gravar na tabela do Bigtable. Se você quiser fornecer permissões mais granulares, configure uma conta serviço gerenciado pelo usuário.

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

A conta de serviço gerenciado pelo usuário precisa ter o papel de usuário do Bigtable.
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. Para mais informações, consulte Criar uma assinatura do Bigtable.

Gravações na tabela do Bigtable

Esta seção descreve como uma assinatura do Bigtable grava mensagens do Pub/Sub em uma tabela.

Dados da mensagem

Uma assinatura do Bigtable grava os dados da mensagem do Pub/Sub em um grupo de colunas chamado data.

Cada linha contém os dados de uma mensagem.
A chave de linha é uma concatenação do ID da assinatura, um prefixo de salt do ID da mensagem e o ID da mensagem, no seguinte formato:

"projects/PROJECT_NUMBER/subscriptions/SUBSCRIPTION_ID#SALT_PREFIX#MESSAGE_ID"
Os dados da mensagem são gravados em uma única coluna no grupo de colunas data. A coluna tem um qualificador de coluna de string vazia ("").
Os dados são gravados como um tipo BYTES.
O carimbo de data/hora da célula é o horário de publicação da mensagem.

Metadados das mensagens

Por padrão, a assinatura não grava metadados de mensagens na tabela. Opcionalmente, é possível ativar a gravação de metadados ao criar uma assinatura do Bigtable.

Se a gravação de metadados estiver ativada, a assinatura vai gravar os metadados da mensagem em um grupo de colunas chamado pubsub_metadata. Antes de criar a assinatura, verifique se a tabela tem um grupo de colunas com esse nome.

Para cada mensagem, a assinatura grava uma nova linha com as seguintes colunas no grupo de colunas pubsub_metadata.

Coluna	Valor	Tipo de dado
`subscription_name`	O nome da assinatura	String
`message_id`	O ID da mensagem	String
`attributes`	Um objeto JSON que contém os atributos da mensagem.	String

Criar uma assinatura do Bigtable

Para criar uma assinatura do Bigtable, use o comando gcloud beta pubsub subscriptions create:

gcloud beta pubsub subscriptions create SUBSCRIPTION_ID \
  --topic=TOPIC_ID \
  --bigtable-table=projects/PROJECT_ID/instances/INSTANCE_ID/tables/TABLE_ID

Substitua:

SUBSCRIPTION_ID: um nome para a assinatura.
TOPIC_ID: o nome ou ID do tópico a ser lido.
PROJECT_ID: o ID do projeto.
INSTANCE_ID: o ID da instância do Bigtable que contém a tabela.
TABLE_ID: o ID da tabela em que gravar. A tabela precisa ter um grupo de colunas chamado data.

As sinalizações a seguir são opcionais:

--bigtable-write-metadata: especifica se é necessário gravar metadados da mensagem. Se você omitir essa flag, a assinatura não vai gravar metadados. Para mais informações, consulte Metadados da mensagem.
--bigtable-app-profile-id=APP_PROFILE: especifica um perfil de aplicativo a ser usado para gravações do Bigtable. O perfil do app precisa usar o roteamento de cluster único. Se essa flag não for especificada, a assinatura vai usar o perfil de aplicativo padrão.
--bigtable-service-account-email: especifica uma conta de serviço a ser usada ao gravar no Bigtable. Se não for especificado, a assinatura usará o agente de serviço do Pub/Sub. Para mais informações, consulte Usar uma conta de serviço personalizada.

Exemplo: gravar do Pub/Sub no Bigtable

O exemplo a seguir mostra como criar uma assinatura do Bigtable, usar a assinatura para gravar mensagens do Pub/Sub em uma tabela do Bigtable e consultar a tabela.

Crie uma instância do Bigtable chamada my-instance.

gcloud bigtable instances create my-instance --display-name="My instance" \
  --cluster-config=id=my-cluster-1,zone=ZONE,nodes=1

Substitua ZONE pela zona em que o cluster é executado. Exemplo: us-central1-b

Crie uma tabela do Bigtable chamada table-1 com um grupo de colunas chamado data.

gcloud bigtable instances tables create table-1 \
  --instance=my-instance \
  --column-families=data

Crie um tópico do Pub/Sub chamado topic-1.
```
gcloud pubsub topics create topic-1
```

Crie uma assinatura do Bigtable que leia o tópico.

gcloud beta pubsub subscriptions create bigtable-sub \
  --topic=topic-1 \
  --bigtable-table=projects/PROJECT_ID/instances/my-instance/tables/table-1

Substitua PROJECT_ID pelo ID do projeto do Google Cloud.

Publique uma mensagem no tópico.

gcloud pubsub topics publish topic-1 --message='{"name":"Alice"}'

Se a mensagem for publicada, a saída será o ID da mensagem:

messageIds:
- 'MESSAGE_ID'

A assinatura do Bigtable grava os dados da mensagem no grupo de colunas data. Para consultar os dados, siga estas etapas:

No console do Google Cloud , acesse a página Instâncias do Bigtable.

Acesse "Instâncias"
Clique na instância chamada my-cluster-1.
No menu de navegação, clique em Bigtable Studio.
No editor de consultas, execute a seguinte consulta SQL.
```
SELECT _key, JSON_VALUE(CAST(data[''] AS STRING), '$.name') AS name FROM table-1;
```
O resultado da consulta é semelhante a este:
```
+-------------------+
| _key      | name  |
+-----------|-------+
| "ROW_KEY" | Alice |
+-------------------+
```
Os dados da mensagem são armazenados como um tipo BYTES. Neste exemplo, os dados são uma string JSON. Portanto, a consulta pode usar as funções JSON do GoogleSQL para analisar os dados.

Monitorar uma assinatura do Bigtable

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

Saiba mais sobre as assinaturas do Bigtable.
Escolha um tipo de assinatura.
Resolver problemas com assinaturas do Bigtable