Publicar eventos em uma tabela do BigQuery

Publicar eventos em uma tabela do BigQuery

Avançado

Neste guia de início rápido, mostramos como publicar e receber mensagens de eventos criando um barramento do Eventarc Advanced e fazendo a inscrição no seu projeto do Google Cloud.

• Um barramento atua como um roteador central, recebendo mensagens de fontes de eventos ou publicadas por provedores.

• Um registro encaminha as mensagens recebidas pelo barramento para um ou mais destinos por um pipeline de processamento.

Neste guia de início rápido, você fará as seguintes tarefas:

1. Crie uma tabela do BigQuery.

2. Crie um barramento do Eventarc Advanced.

3. Crie um registro do Eventarc Advanced.

4. Publique uma mensagem de evento no barramento.

5. Confira os dados de eventos na tabela do BigQuery.

É possível concluir este guia de início rápido usando a CLI gcloud e a ferramenta de linha de comando bq.

Antes de começar

As restrições de segurança definidas pela sua organização podem impedir que você conclua as etapas a seguir. Para informações sobre solução de problemas, consulte Desenvolver aplicativos em um ambiente restrito de Google Cloud .

Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

Instale a CLI do Google Cloud.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

Para inicializar a gcloud CLI, execute o seguinte comando:

gcloud init

Crie ou selecione um Google Cloud projeto.

Funções necessárias para selecionar ou criar um projeto

• Selecionar um projeto: não é necessário um papel específico do IAM para selecionar um projeto. Você pode escolher qualquer projeto em que tenha recebido um papel.
• Criar um projeto: para criar um projeto, é necessário ter o papel de Criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder papéis.

Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

• Crie um projeto do Google Cloud :

  gcloud projects create PROJECT_ID

  Substitua PROJECT_ID por um nome para o projeto Google Cloud que você está criando.

• Selecione o projeto Google Cloud que você criou:

  gcloud config set project PROJECT_ID

  Substitua PROJECT_ID pelo nome do projeto do Google Cloud .

Verifique se o faturamento está ativado para o projeto do Google Cloud .

Ative as APIs BigQuery e Eventarc:

Funções necessárias para ativar APIs

Para ativar as APIs, é necessário ter o papel do IAM de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.

gcloud services enable bigquery.googleapis.com eventarc.googleapis.com eventarcpublishing.googleapis.com

Instale a CLI do Google Cloud.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

Para inicializar a gcloud CLI, execute o seguinte comando:

gcloud init

Crie ou selecione um Google Cloud projeto.

Funções necessárias para selecionar ou criar um projeto

• Selecionar um projeto: não é necessário um papel específico do IAM para selecionar um projeto. Você pode escolher qualquer projeto em que tenha recebido um papel.
• Criar um projeto: para criar um projeto, é necessário ter o papel de Criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder papéis.

Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

• Crie um projeto do Google Cloud :

  gcloud projects create PROJECT_ID

  Substitua PROJECT_ID por um nome para o projeto Google Cloud que você está criando.

• Selecione o projeto Google Cloud que você criou:

  gcloud config set project PROJECT_ID

  Substitua PROJECT_ID pelo nome do projeto do Google Cloud .

Verifique se o faturamento está ativado para o projeto do Google Cloud .

Ative as APIs BigQuery e Eventarc:

Funções necessárias para ativar APIs

Para ativar as APIs, é necessário ter o papel do IAM de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.

gcloud services enable bigquery.googleapis.com eventarc.googleapis.com eventarcpublishing.googleapis.com

1. Atualize os componentes gcloud:

   gcloud components update

2. Faça login usando sua conta:

   gcloud auth login

3. Defina a variável de configuração usada neste guia de início rápido:

   REGION=REGION

   Substitua REGION por um local compatível para o ônibus, por exemplo, us-central1.

4. Se você for o criador do projeto, vai receber o papel de proprietário básico (roles/owner). Por padrão, esse papel do Identity and Access Management (IAM) inclui as permissões necessárias para acesso total à maioria dos recursos do Google Cloud, e você pode pular esta etapa.

   Se você não é o criador do projeto, as permissões necessárias precisam ser concedidas ao principal apropriado. Por exemplo, um principal pode ser uma Conta do Google (para usuários finais) ou uma conta de serviço (para aplicativos e cargas de trabalho de computação).

   Permissões necessárias

   Para conseguir as permissões necessárias a fim de concluir o guia de início rápido, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

   • Editor de dados do BigQuery (roles/bigquery.dataEditor)
   • Desenvolvedor do Eventarc (roles/eventarc.developer)
   • Administrador de barramento de mensagem do Eventarc (roles/eventarc.messageBusAdmin)
   • Acessador de exibição de registros (roles/logging.viewAccessor)
   • Administrador de projetos do IAM (roles/resourcemanager.projectIamAdmin)
   • Administrador da conta de serviço (roles/iam.serviceAccountAdmin)
   • Usuário da conta de serviço (roles/iam.serviceAccountUser)
   • Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin)

   Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

   Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

5. Para conceder ao Eventarc Advanced as permissões necessárias para atualizar as propriedades da tabela do BigQuery, peça ao administrador para conceder o papel do IAM Editor de dados do BigQuery (roles/bigquery.dataEditor) no projeto Google Cloud a uma conta de serviço:
   1. Crie uma conta de serviço. Para fins de teste, você vai anexar essa conta de serviço a um pipeline do Eventarc Advanced para representar a identidade do pipeline.

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

      Substitua SERVICE_ACCOUNT_NAME por um nome para a conta de serviço.
   2. Conceda o papel do IAM roles/bigquery.dataEditor à conta de serviço:

      gcloud projects add-iam-policy-binding PROJECT_ID \
          --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
          --role=roles/bigquery.dataEditor

Criar uma tabela do BigQuery

Crie uma tabela do BigQuery como destino de eventos. Outros destinos de eventos são aceitos, como um tópico do Pub/Sub, Workflows ou outro endpoint HTTP. Para mais informações, consulte Provedores e destinos de eventos.

Antes de criar uma tabela do BigQuery, crie um conjunto de dados, que funciona como um contêiner de nível superior para a tabela, e um esquema de tabela.

1. Para criar um conjunto de dados, use o comando bq mk com a flag --dataset.

   bq --location=$REGION mk --dataset DATASET_ID

   Substitua DATASET_ID por um nome exclusivo para o conjunto de dados do BigQuery, por exemplo, my_dataset.

2. No terminal, crie um arquivo chamado my-schema.json.

3. Copie e cole o esquema a seguir no novo arquivo e salve-o.

   [
       {
           "name": "name",
           "type": "STRING",
           "mode": "REQUIRED"
       },
       {
           "name": "age",
           "type": "INTEGER",
           "mode": "NULLABLE"
       }
   ]

4. Para criar uma tabela, use o comando bq mk com a flag --table.

   bq mk --table PROJECT_ID:DATASET_ID.TABLE_ID my-schema.json

   Substitua TABLE_ID por um nome exclusivo para a tabela do BigQuery, por exemplo, my-table.

Criar um barramento do Eventarc Advanced

Um barramento recebe mensagens de eventos de uma origem de mensagens ou publicadas por um provedor e atua como um roteador de mensagens.

Para mais informações, consulte Criar um barramento para rotear mensagens.

Observação: é possível criar um barramento por Google Cloud projeto por região compatível.

Crie um barramento do Eventarc Advanced no seu projeto usando o comando gcloud eventarc message-buses create:

gcloud eventarc message-buses create BUS_NAME \
    --location=$REGION

Substitua BUS_NAME pelo ID do barramento ou um nome totalmente qualificado, por exemplo, my-bus.

Criar uma inscrição no Eventarc Advanced

Um registro determina quais mensagens são roteadas para um destino e também especifica o pipeline usado para configurar um destino para as mensagens de evento. Nesse caso, o destino é um endpoint de API BigQuery.

Para mais informações, consulte Criar uma inscrição para receber eventos.

Observação: a criação de um pipeline pode levar mais de 10 minutos.

Ao usar a CLI gcloud, primeiro crie um pipeline e depois crie uma inscrição:

1. Crie um pipeline usando o comando gcloud eventarc pipelines create:

   gcloud eventarc pipelines create PIPELINE_NAME \
       --destinations=http_endpoint_uri='https://bigquery.googleapis.com/bigquery/v2/projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_ID/insertAll',http_endpoint_message_binding_template='{"headers": headers.merge({"content-type":"application/json"}), "body": {"rows":[{"json":message.data}]}}',oauth_token_authentication_service_account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
       --input-payload-format-json= \
       --location=$REGION

   Substitua PIPELINE_NAME pelo ID do pipeline ou um nome totalmente qualificado. Por exemplo, my-pipeline.

   Observe o seguinte:

   • A chave http_endpoint_message_binding_template transforma o evento no formato esperado pela API. Ao definir uma vinculação de mensagem, é necessário configurar um formato de entrada para acessar o payload.
   • A chave oauth_token_authentication_service_account especifica um e-mail de conta de serviço. Esse e-mail é usado para gerar um token OAuth, que geralmente só deve ser usado ao chamar APIs do Google hospedadas em *.googleapis.com.
   • A flag input-payload-format-json especifica que o formato do payload de entrada do pipeline é JSON. Todas as mensagens que não corresponderem a esse formato serão tratadas como erros persistentes.

2. Crie uma inscrição usando o comando gcloud eventarc enrollments create:

   gcloud eventarc enrollments create ENROLLMENT_NAME \
       --cel-match=MATCH_EXPRESSION \
       --destination-pipeline=PIPELINE_NAME \
       --message-bus=BUS_NAME \
       --message-bus-project=PROJECT_ID \
       --location=$REGION

   Substitua:

   • ENROLLMENT_NAME: o ID da inscrição ou um nome totalmente qualificado, por exemplo, my-enrollment.

   • MATCH_EXPRESSION: a expressão de correspondência para esta inscrição usando CEL. Por exemplo:

     "message.type == 'hello-world-type'"
     

Publicar uma mensagem de evento no barramento

Para publicar uma mensagem diretamente no seu barramento, use o comando gcloud eventarc message-buses publish ou envie uma solicitação para a API REST de publicação do Eventarc. Para mais informações, consulte Publicar eventos diretamente.

A mensagem precisa estar no formato CloudEvents, que é uma especificação para descrever dados de eventos de uma maneira comum. O elemento data é a carga útil do seu evento e precisa corresponder ao esquema da sua tabela do BigQuery. Qualquer JSON bem formado pode ser inserido nesse campo. Para mais informações sobre atributos de contexto do CloudEvents, consulte Formato de evento.

Confira a seguir exemplos de publicação direta de um evento em um barramento do Eventarc Advanced:

Exemplo 1

É possível publicar um evento em um barramento usando a CLI gcloud e uma --event-data e outras flags de atributo de evento:

gcloud eventarc message-buses publish BUS_NAME \
    --event-data='{"name": "my-name", "age": "20"}' \
    --event-id=hello-world-id-1234 \
    --event-source=hello-world-source \
    --event-type=hello-world-type \
    --event-attributes="datacontenttype=application/json" \
    --location=$REGION

Exemplo 2

É possível publicar um evento em um barramento como uma mensagem JSON usando a CLI gcloud e uma flag --json-message:

gcloud eventarc message-buses publish BUS_NAME \
    --location=$REGION \
    --json-message='{"id": "hello-world-id-1234", "type":
 "hello-world-type", "source":
 "hello-world-source", "specversion": "1.0", "data":
 {"name": "my-name", "age": "20"}}'

Depois de publicar um evento, você vai receber uma mensagem informando que ele foi publicado com sucesso.

Conferir os dados de eventos na tabela do BigQuery

Depois de publicar um evento no barramento do Eventarc Advanced, use o comando bq query para confirmar se uma nova linha foi adicionada à tabela do BigQuery.

bq query \
    --use_legacy_sql=false \
    'SELECT
      *
    FROM
      `PROJECT_ID.DATASET_ID.TABLE_ID`
    LIMIT
      10;'

Você criou um barramento e uma inscrição do Eventarc Advanced, publicou uma mensagem de evento no barramento e verificou o resultado esperado consultando a tabela do BigQuery.

Limpar

Ao concluir as tarefas descritas neste guia de início rápido, é possível evitar o faturamento contínuo excluindo os recursos criados:

1. Exclua uma tabela do BigQuery.

2. Exclua um conjunto de dados do BigQuery.

3. Exclua os recursos do Eventarc Advanced:

   1. Excluir um registro.

   2. Excluir um pipeline.

   3. Excluir um ônibus.

Se preferir, exclua o projeto Google Cloud para evitar cobranças. A exclusão do projeto do Google Cloud interrompe o faturamento de todos os recursos usados nele.

Cuidado: a exclusão de um projeto tem os seguintes efeitos:

• Tudo no projeto é excluído. Se você tiver usado um projeto atual para as tarefas neste documento, a exclusão dele incluirá a exclusão de quaisquer outros trabalhos feitos nele.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um ID do projeto personalizado para ser usado no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, exclua recursos específicos do projeto, em vez de excluir o projeto inteiro.

Se você planeja explorar várias arquiteturas, tutoriais e guias de início rápido, a reutilização de projetos pode evitar que você exceda limites da cota.

Excluir um projeto do Google Cloud :

gcloud projects delete PROJECT_ID

A seguir

• Publicar eventos de fontes do Google
• Publicar eventos diretamente
• Transformar eventos recebidos
• Formatar eventos recebidos