Monitorize o estado das tarefas através de notificações do Pub/Sub e do BigQuery

Este documento explica como pode monitorizar as alterações de estado de tarefas e trabalhos configurando notificações do Pub/Sub. Pode usar as notificações para vários exemplos de utilização. Por exemplo, este documento explica como fazer stream das notificações para uma tabela do BigQuery, que pode usar para analisar os dados. Para saber mais sobre os exemplos de utilização das notificações do Pub/Sub, consulte o artigo Escolha um tipo de subscrição na documentação do Pub/Sub.

Em alternativa, se quiser exportar todas as informações sobre uma tarefa para o BigQuery, consulte Exportar informações da tarefa em vez disso.

Nota: o Pub/Sub e o BigQuery são produtos Google Cloud separados com preços próprios. Para mais informações, consulte os preços do Pub/Sub e os preços do BigQuery.

Antes de começar

1. Se nunca usou o Batch, reveja o artigo Comece a usar o Batch e ative o Batch concluindo os pré-requisitos para projetos e utilizadores.
2. Se quiser configurar notificações do Pub/Sub para os seus trabalhos em lote, faça o seguinte:

   1. Enable the Pub/Sub API.

      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.

      Enable the API

   2. Para obter as autorizações de que precisa para configurar um tópico e uma subscrição do Pub/Sub, peça ao seu administrador que lhe conceda a função IAM Editor do Pub/Sub (roles/pubsub.editor) num projeto. 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.

   Nota: depois de configurar um tópico e uma subscrição do Pub/Sub, o administrador tem de conceder autorizações adicionais a vários principais para permitir que os trabalhos enviem notificações para esse tópico. Especificamente, as funções necessárias estão listadas na página Crie e execute uma tarefa que envie notificações de estado do Pub/Sub.
3. Os requisitos adicionais variam consoante o tipo de subscrição que decide configurar. Por exemplo, se quiser fazer stream e analisar notificações para uma tabela do BigQuery, tem de fazer o seguinte:

   1. Enable the BigQuery API.

      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.

      Enable the API

   2. Para garantir que a conta de serviço do Pub/Sub tem as autorizações necessárias para transmitir notificações do Pub/Sub para o BigQuery, peça ao seu administrador para conceder à conta de serviço do Pub/Sub a função de IAM Editor de dados do BigQuery (roles/bigquery.dataEditor) no projeto do tópico do Pub/Sub.

      Importante: tem de conceder esta função à conta de serviço do Pub/Sub e não à sua conta de utilizador. Se não conceder a função ao principal correto, podem ocorrer erros de autorização.

      Para mais informações sobre a atribuição desta função, consulte o artigo Atribua funções do BigQuery à conta de serviço do Pub/Sub.

   3. Certifique-se de que todos os utilizadores que quer que analisem as notificações no BigQuery têm as autorizações necessárias.

      Para receber as autorizações de que precisa para consultar notificações do Pub/Sub no BigQuery, peça ao seu administrador para lhe conceder as seguintes funções de IAM:

      • Utilizador da tarefa do BigQuery (roles/bigquery.jobUser) no projeto da tabela do BigQuery
      • Visualizador de dados do BigQuery (roles/bigquery.dataViewer) na tabela do BigQuery

Configure notificações do Pub/Sub para o Batch

O Batch suporta notificações do Pub/Sub para alterações aos estados de tarefas e trabalhos, que pode usar para alertas, observabilidade ou análise.

Para configurar notificações do Pub/Sub para uma ou mais tarefas em lote, conclua os passos descritos nas secções seguintes:

1. Crie ou identifique um tópico do Pub/Sub para as suas tarefas em lote.
2. Crie, pelo menos, uma subscrição para o seu tópico para receber e usar as respetivas notificações.
3. Configure tarefas para enviar notificações para o seu tópico.

Depois de configurar as notificações do Pub/Sub para o Batch, pode configurar opcionalmente cada tarefa para enviar notificações específicas. Pode receber notificações sempre que o estado de uma tarefa ou de um trabalho for alterado, ou pode filtrar as notificações por estados específicos de tarefas ou trabalhos. Em particular, o Pub/Sub não envia notificações para o primeiro estado em que uma tarefa ou um trabalho entra. O Pub/Sub só envia notificações quando um trabalho passa de um estado para outro.

Importante: devido a um problema conhecido, o Pub/Sub pode não enviar notificações para todos os estados intermédios quando um trabalho ou uma tarefa muda muito rapidamente. Pode mitigar este problema vendo o histórico de estados através de eventos de estado. Para mais informações, consulte o artigo O Pub/Sub pode não enviar notificações para estados intermédios durante alterações rápidas.

Para mais informações sobre os atributos que pode configurar para as notificações do Pub/Sub, consulte o artigo Crie e execute uma tarefa que envie notificações de estado do Pub/Sub.

Crie ou identifique um tópico Pub/Sub para o Batch

Crie um novo tópico do Pub/Sub ou identifique um tópico do Pub/Sub existente que quer usar para notificações em lote.

Conforme explicado mais adiante neste documento, as tarefas não podem enviar notificações para este tópico do Pub/Sub até que o seu administrador conceda autorizações adicionais que o permitam.

Crie uma subscrição para receber e usar as notificações

Para receber e usar mensagens publicadas num tópico Pub/Sub, tem de criar, pelo menos, uma subscrição desse tópico.

Por exemplo, uma opção é configurar o tópico para transmitir as respetivas notificações para o BigQuery. Em seguida, quando estiver a executar trabalhos que publicam notificações, pode receber e analisar as notificações numa tabela do BigQuery. Para mais informações, consulte o Exemplo: receba e use notificações do Pub/Sub no BigQuery neste documento.

Caso contrário, para saber mais sobre subscrições e outras opções de subscrição, consulte o Resumo das subscrições na documentação do Pub/Sub.

Configure trabalhos para enviar notificações para o seu tópico

Para configurar tarefas que enviam notificações do Pub/Sub para o seu tópico, siga as instruções na página Crie e execute uma tarefa que envia notificações de estado do Pub/Sub. Especificamente, faça o seguinte:

1. Se ainda não o fez, peça ao administrador para conceder todas as autorizações necessárias para que as tarefas enviem notificações para o seu tópico do Pub/Sub. Estas autorizações estão listadas na secção Funções necessárias dessa página.
2. Crie e execute uma tarefa que ative as notificações do Pub/Sub definindo o campo notifications da tarefa.

Exemplo: receba e use notificações do Pub/Sub no BigQuery

As secções seguintes explicam um exemplo de utilização para receber e usar notificações do Pub/Sub no BigQuery. Ao configurar uma subscrição que transmite as notificações do Pub/Sub do seu tópico para uma tabela do BigQuery, pode reter o histórico das alterações de estado de tarefas e trabalhos, e consultar essas alterações.

Configure uma subscrição que transmita notificações para o BigQuery

Configure uma subscrição do Pub/Sub que transmita notificações de um tópico para uma tabela do BigQuery fazendo o seguinte:

1. Se ainda não o fez, crie ou identifique um tópico do Pub/Sub para o Batch.

2. Se ainda não tiver um, crie um conjunto de dados do BigQuery.

3. Crie uma tabela do BigQuery com a seguinte definição de esquema:

   [
     {
       "name": "data",
       "type": "STRING"
     },
     {
       "name": "subscription_name",
       "type": "STRING"
     },
     {
       "name": "message_id",
       "type": "STRING"
     },
     {
       "name": "attributes",
       "type": "JSON"
     },
     {
       "name": "publish_time",
       "type": "TIMESTAMP",
       "mode": "NULLABLE"
     }
   ]
   

4. Crie uma subscrição do Pub/Sub que faça streaming para o BigQuery e especifique as seguintes opções:

   • Tópico: selecione o tópico do Pub/Sub para o processamento em lote.
   • Projeto: selecione o projeto que contém a sua tabela do BigQuery.
   • Conjunto de dados: selecione o conjunto de dados que contém a sua tabela do BigQuery.
   • Tabela: selecione a tabela que criou no passo anterior.
   • Selecione Usar esquema de tópicos.
   • Selecione Escrever metadados.

Agora, sempre que uma notificação do Pub/Sub for enviada para esse tópico, o Pub/Sub transmite essa notificação para a tabela do BigQuery. Depois de configurar tarefas para enviar notificações do Pub/Sub, pode analisar as notificações no BigQuery.

Analise as notificações no BigQuery

Pode analisar as notificações no BigQuery depois de configurar uma subscrição de uma tabela do BigQuery para o seu tópico e executar tarefas que enviam notificações para o seu tópico. Para analisar as notificações no BigQuery, execute uma consulta na coluna attributes da tabela do BigQuery. Os atributos que pode consultar dependem de ter configurado notificações para tarefas ou trabalhos.

Pode consultar os seguintes atributos das notificações de tarefas:

• JobUID
• NewTaskState
• Region
• TaskName
• TaskUID
• Type

Pode consultar os seguintes atributos das notificações de tarefas:

• JobUID
• JobName
• NewJobState
• Region
• Type

Por exemplo, a seguinte consulta mostra o JobUID associado a cada notificação:

select attributes.JobUID from `example-table`

O que se segue?

• Saiba como criar e executar uma tarefa que envia notificações de estado do Pub/Sub.
• Saiba mais sobre as subscrições do Pub/Sub.
• Saiba mais acerca da estatística do BigQuery.