Publicar eventos numa tabela do BigQuery

Publicar eventos numa tabela do BigQuery

Avançadas

Este início rápido mostra como publicar e receber mensagens de eventos criando um bus avançado do Eventarc e uma inscrição no seu projeto Google Cloud.

• Um autocarro permite-lhe centralizar o fluxo de mensagens através do seu sistema e funciona como um router. Recebe mensagens de eventos de uma origem de mensagens ou publicadas por um fornecedor e avalia-as de acordo com uma inscrição.

• Uma inscrição identifica uma subscrição de um barramento específico e define os critérios de correspondência para mensagens, fazendo com que sejam encaminhadas em conformidade para um ou mais destinos.

Neste início rápido, vai:

1. Crie uma tabela do BigQuery.

2. Crie um barramento avançado do Eventarc.

3. Crie uma inscrição avançada do Eventarc.

4. Publicar uma mensagem de evento no barramento.

5. Veja os dados dos eventos na tabela do BigQuery.

Pode concluir este início rápido através da CLI gcloud e da ferramenta de linhas de comando bq.

Antes de começar

As restrições de segurança definidas pela sua organização podem impedir a conclusão dos seguintes passos. Para informações de resolução de problemas, consulte o artigo Desenvolva aplicações num ambiente Google Cloud restrito.

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.

Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

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

Install the Google Cloud CLI.

Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

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

1. Atualize os componentes de gcloud:

   gcloud components update

2. Inicie sessão com a sua conta:

   gcloud auth login

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

   REGION=REGION

   Substitua REGION por uma localização suportada para o autocarro, por exemplo, us-central1.

4. Se for o criador do projeto, é-lhe atribuída a função básica de proprietário (roles/owner). Por predefinição, esta função do Identity and Access Management (IAM) inclui as autorizações necessárias para acesso total à maioria dos Google Cloud recursos e pode ignorar este passo.

   Se não for o criador do projeto, as autorizações necessárias têm de ser concedidas no projeto ao principal adequado. Por exemplo, um principal pode ser uma Conta Google (para utilizadores finais) ou uma conta de serviço (para aplicações e cargas de trabalho de computação).

   Autorizações necessárias

   Para receber as autorizações de que precisa para concluir este início rápido, peça ao seu administrador que lhe conceda as seguintes funções da IAM no seu projeto:

   • Editor de dados do BigQuery (roles/bigquery.dataEditor)
   • Eventarc Developer (roles/eventarc.developer)
   • Eventarc Message Bus Admin (roles/eventarc.messageBusAdmin)
   • Aceder à vista de registos (roles/logging.viewAccessor)
   • Project IAM Admin (roles/resourcemanager.projectIamAdmin)
   • Administrador da conta de serviço (roles/iam.serviceAccountAdmin)
   • Utilizador da conta de serviço (roles/iam.serviceAccountUser)
   • Administrador de utilização de serviços (roles/serviceusage.serviceUsageAdmin)

   Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

   Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

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

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

      Substitua SERVICE_ACCOUNT_NAME por um nome para a sua conta de serviço.
   2. Conceda a função da IAM à conta de serviço:roles/bigquery.dataEditor

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

Crie uma tabela do BigQuery

Crie uma tabela do BigQuery como destino de eventos. São suportados outros destinos de eventos, como um tópico do Pub/Sub, fluxos de trabalho ou outro ponto final HTTP. Para mais informações, consulte Fornecedores e destinos de eventos.

Antes de criar uma tabela do BigQuery, crie um conjunto de dados que funcione como um contentor de nível superior para o esquema da tabela.

1. Para criar um novo 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 novo ficheiro denominado my-schema.json.

3. Copie e cole o esquema seguinte no novo ficheiro e, de seguida, guarde o ficheiro.

   [
       {
           "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 único para a tabela do BigQuery, por exemplo, my-table.

Crie um bus avançado do Eventarc

Um barramento recebe mensagens de eventos de uma origem de mensagens ou publicadas por um fornecedor e funciona como um router de mensagens.

Para mais informações, consulte o artigo Crie um autocarro para encaminhar mensagens.

Nota: pode criar um autocarro por Google Cloud projeto por região suportada.

Crie um bus avançado do Eventarc no seu projeto através do comando gcloud eventarc message-buses create:

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

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

Crie uma inscrição avançada do Eventarc

Uma inscrição determina as mensagens que são encaminhadas para um destino e também especifica o pipeline usado para configurar um destino para as mensagens de eventos. Neste caso, o destino é um ponto final da API BigQuery.

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

Nota: a criação de um pipeline pode demorar mais de 10 minutos.

Quando usa a CLI gcloud, primeiro cria um pipeline e, em seguida, cria uma inscrição:

1. Crie um pipeline com 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 por um nome totalmente qualificado, por exemplo, my-pipeline.

   Tenha em conta o seguinte:

   • A chave http_endpoint_message_binding_template transforma o evento no formato esperado pela API. Quando define uma associação de mensagens, tem de configurar um formato de entrada para aceder à carga útil.
   • A chave oauth_token_authentication_service_account especifica um email de conta de serviço. Este email é usado para gerar um símbolo do OAuth que, geralmente, só deve ser usado quando chama APIs Google alojadas em *.googleapis.com.
   • A flag input-payload-format-json especifica que o formato de payload de entrada do pipeline é JSON. Todas as mensagens que não correspondam a este formato são tratadas como erros persistentes.

2. Crie uma inscrição através do 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 o seguinte:

   • 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 o IEC, por exemplo:

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

Publicar uma mensagem de evento no barramento

Para publicar diretamente uma mensagem no seu barramento, pode usar o comando gcloud eventarc message-buses publish ou enviar um pedido para a API REST Eventarc Publishing. Para mais informações, consulte o artigo Publique eventos diretamente.

A mensagem tem de estar num formato CloudEvents, que é uma especificação para descrever dados de eventos de forma comum. O elemento data é a carga útil do seu evento e, em última análise, tem de corresponder ao esquema da sua tabela do BigQuery. Qualquer JSON bem formado pode ser colocado neste campo. Para mais informações sobre os atributos de contexto dos CloudEvents, consulte o artigo Formato de eventos.

Seguem-se exemplos de publicação direta de um evento num bus avançado do Eventarc:

Exemplo 1

Pode publicar um evento num barramento através da CLI gcloud e de um --event-data e outras flags de atributos de eventos:

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

Pode publicar um evento num barramento como uma mensagem JSON através da CLI gcloud e de 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, deve receber a mensagem "Evento publicado com êxito".

Veja os dados dos eventos na tabela do BigQuery

Depois de publicar um evento no seu Eventarc Advanced bus, pode usar o comando bq query para confirmar que foi adicionada uma nova linha à sua tabela do BigQuery.

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

Criou com êxito um bus avançado do Eventarc e uma inscrição, publicou uma mensagem de evento no bus e verificou o resultado esperado consultando a tabela do BigQuery.

Limpar

Quando concluir as tarefas descritas neste início rápido, pode evitar a faturação contínua eliminando os recursos que criou:

1. Elimine uma tabela do BigQuery.

2. Elimine um conjunto de dados do BigQuery.

3. Elimine recursos avançados do Eventarc:

   1. Elimine uma inscrição.

   2. Elimine um pipeline.

   3. Elimine um autocarro.

Em alternativa, pode eliminar o seu Google Cloud projeto para evitar incorrer em custos. A eliminação do seu Google Cloud projeto interrompe a faturação de todos os recursos usados nesse projeto.

Atenção: a eliminação de um projeto tem os seguintes efeitos:

• Tudo no projeto é eliminado. Se usou um projeto existente para as tarefas neste documento, quando o elimina, também elimina qualquer outro trabalho que tenha feito no projeto.
• Os IDs dos projetos personalizados são perdidos. Quando criou este projeto, pode ter criado um ID do projeto personalizado que quer usar no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, elimine os recursos selecionados no projeto em vez de eliminar o projeto inteiro.

Se planeia explorar várias arquiteturas, tutoriais ou inícios rápidos, a reutilização de projetos pode ajudar a evitar exceder os limites de quota de projetos.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

O que se segue?

• Publique eventos de origens Google
• Publique eventos diretamente
• Transforme eventos recebidos
• Formate os eventos recebidos