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 Google Cloud.

• Um barramento permite centralizar o fluxo de mensagens no sistema e atua como um roteador. Ele recebe mensagens de eventos de uma fonte de mensagens ou publicadas por um provedor e as avalia de acordo com uma inscrição.

• Um registro identifica uma assinatura de um barramento específico e define os critérios de correspondência para mensagens, fazendo com que elas sejam roteadas de acordo com um ou mais destinos.

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 uma inscrição no 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 .

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Install the Google Cloud CLI.

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

Create or select a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery and Eventarc APIs:

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

Install the Google Cloud CLI.

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

Create or select a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery and Eventarc APIs:

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 fonte de mensagens ou publicadas por um provedor e age 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 da 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 à sua tabela do BigQuery.

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

Você criou um barramento e um registro 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 Google Cloud interrompe o faturamento de todos os recursos usados nele.

Cuidado: excluir 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 vai resultar na exclusão de outros trabalhos feitos nele.
• Os IDs de projeto personalizados são perdidos. É possível que, ao criar o projeto, você tenha criado um ID de 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.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

A seguir

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