Exportar dados para o Pub/Sub (ETL reverso)

Neste documento, descrevemos como configurar instruções reversas de extração, transformação e carregamento (RETL) do BigQuery para Pub/Sub. Você pode fazer isso usando a Instrução EXPORT DATA em uma consulta contínua para exportar dados do BigQuery para um Tópico do Pub/Sub.

Use um fluxo de trabalho RETL no Pub/Sub para combinar os recursos de análise do BigQuery com o serviço de mensagens global assíncrono e escalonável do Pub/Sub. Esse fluxo de trabalho permite disponibilizar dados para aplicativos e serviços downstream de maneira orientada a eventos.

Pré-requisitos

Crie uma conta de serviço. Uma conta de serviço é necessária para executar uma consulta contínua que exporta resultados para um tópico do Pub/Sub.

Você precisa criar um Tópico do Pub/Sub para receber os resultados da consulta contínua como mensagens e uma Assinatura do Pub/Sub que o aplicativo de destino possa usar para receber essas mensagens.

Funções exigidas

Nesta seção, você encontra informações sobre os papéis e as permissões exigidos pela conta de usuário que cria a consulta contínua e a conta de serviço que executa a consulta contínua.

Permissões da conta de usuário

Para criar um job no BigQuery, a conta de usuário deve ter a permissão bigquery.jobs.create do IAM. Cada um dos seguintes papéis do IAM concedem a permissão bigquery.jobs.create:

Para enviar um job executado usando uma conta de serviço, a conta de usuário precisa ter o papel Usuário da conta de serviço (roles/iam.serviceAccountUser). Se você estiver usando a mesma conta de usuário para criar a conta de serviço, a conta de usuário deverá ter o papel Administrador da conta de serviço (roles/iam.serviceAccountAdmin). Para saber como limitar o acesso de um usuário a uma única conta de serviço e não a todas as contas de serviço dentro de um projeto, consulte Conceder um único papel.

Se a conta de usuário precisar ativar as APIs necessárias para o caso de uso de consulta contínua, a conta de usuário deve ter o papel Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin).

Permissões de conta de serviço

Para exportar dados de uma tabela do BigQuery, a conta de serviço precisa ter a permissão bigquery.tables.export do IAM. Cada um dos seguintes papéis do IAM concedem a permissão bigquery.tables.export:

Para que a conta de serviço acesse o Pub/Sub, você precisa conceder à conta de serviço os dois papéis do IAM a seguir:

Também é possível receber as permissões necessárias através de papéis personalizados.

Antes de começar

Ative as APIs BigQuery and Pub/Sub.

Ative as APIs

Exportar para Pub/Sub

Use a Instrução EXPORT DATA para exportar dados para um tópico do Pub/Sub:

Console

No Console do Google Cloud, acesse a página BigQuery.

Ir para o BigQuery
No editor de consultas, clique em Mais > Configurações de consulta.
Na seção Consulta contínua, selecione a caixa de seleção Usar o modo de consulta contínua.
Na caixa Conta de serviço, selecione a conta de serviço que você criou.
Clique em Salvar.
No editor de consultas, digite a seguinte instrução:
```
EXPORT DATA
OPTIONS (
format = 'CLOUD_PUBSUB',
uri = 'https://pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID'
) AS
(
QUERY
);
```
Substitua:
- PROJECT_ID: o ID do projeto.
- TOPIC_ID: o ID do tópico do Pub/Sub. É possível encontrar o ID do tópico na página Tópicos do console do Google Cloud.
- QUERY: a instrução SQL para selecionar os dados a serem exportados. A instrução SQL deve conter apenas operações compatíveis.
Clique em Executar.

bq

No Console do Google Cloud, ative o Cloud Shell.

Ativar o Cloud Shell

Na parte inferior do Console do 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.
Na linha de comando, execute a consulta contínua usando o comando bq query com as seguintes sinalizações:
- Defina a sinalização --continuous como true para tornar a consulta contínua.
- Use a sinalização --connection_property para especificar uma conta de serviço a ser usada.
```
bq query --project_id=PROJECT_ID --use_legacy_sql=false \
--continuous=true --connection_property=service_account=SERVICE_ACCOUNT_EMAIL \
'EXPORT DATA OPTIONS (format = "CLOUD_PUBSUB", uri = "https://pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID") AS (QUERY);'
```
Substitua:
- PROJECT_ID: o ID do projeto.
- SERVICE_ACCOUNT_EMAIL: o e-mail da conta de serviço. Você pode acessar o e-mail da conta de serviço na página Contas de serviço do console do Google Cloud.
- QUERY: a instrução SQL para selecionar os dados a serem exportados. A instrução SQL deve conter apenas operações compatíveis.

API

Execute a consulta contínua chamando o método jobs.insert. Defina os seguintes campos no recurso JobConfigurationQuery do recurso Job transmitido:
- Defina o campo continuous como true para tornar a consulta contínua.
- Use o campo connection_property para especificar a conta de serviço que será usada.
```
curl --request POST \
  'https://bigquery.googleapis.com/bigquery/v2/projects/PROJECT_ID/jobs'
  --header 'Authorization: Bearer $(gcloud auth print-access-token) \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '("configuration":("query":"EXPORT DATA OPTIONS (format = 'CLOUD_PUBSUB', uri = 'https://pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID') AS (QUERY);","useLegacySql":false,"continuous":true,"connectionProperties":["key": "service_account","value":"SERVICE_ACCOUNT_EMAIL"]))' \
  --compressed
```
Substitua:
- PROJECT_ID: o ID do projeto.
- QUERY: a instrução SQL para selecionar os dados a serem exportados. A instrução SQL deve conter apenas operações compatíveis.
- SERVICE_ACCOUNT_EMAIL: o e-mail da conta de serviço. Você pode acessar o e-mail da conta de serviço na página Contas de serviço do console do Google Cloud.

Exportar várias colunas para o Pub/Sub

Para incluir várias colunas na saída, crie uma coluna struct para conter os valores da coluna e, em seguida, converta o valor do struct para uma string JSON usando a função TO_JSON_STRING. O exemplo a seguir exporta dados de quatro colunas, formatados como uma string JSON:

EXPORT DATA
  OPTIONS (
    format = 'CLOUD_PUBSUB',
    uri = 'https://pubsub.googleapis.com/projects/myproject/topics/taxi-real-time-rides')
AS (
  SELECT
    TO_JSON_STRING(
      STRUCT(
        ride_id,
        timestamp,
        latitude,
        longitude)) AS message
  FROM `myproject.real_time_taxi_streaming.taxi_rides`
  WHERE ride_status = 'enroute'
);

Otimização da exportação

Se o desempenho do seu job de consulta contínua parece estar limitado por recursos de computação disponíveis, tente aumentar o tamanho da atribuição de reserva de slot CONTINUOUS do BigQuery.

Limitações

Os dados exportados devem consistir em uma única coluna STRING ou BYTES. O nome da coluna pode ser o que você quiser.
Você deve usar uma consulta contínua para exportar para o Pub/Sub.
Não é possível transmitir um esquema para um tópico do Pub/Sub na consulta contínua.
Não é possível exportar dados para um tópico do Pub/Sub que usa um esquema.
Não é possível exportar dados com valores NULL. Você pode excluir valores NULL dos resultados da consulta incluindo um filtro WHERE message IS NOT NULL na consulta contínua.
Os dados exportados não podem exceder as cotas do Pub/Sub.

Preços

Quando você exporta dados em uma consulta contínua, a cobrança é feita usando os preços de computação da capacidade do BigQuery. Para executar consultas contínuas, é preciso ter uma reserva que usa a edição Enterprise ou Enterprise Plus, e uma atribuição de reserva que usa o tipo de job CONTINUOUS.

Depois que os dados forem exportados, você vai receber cobranças pelo uso do Pub/Sub. Para mais informações, consulte os Preços do Pub/Sub.