Como usar ações e APIs do GitHub para revelar dados importantes

Neste artigo, demonstraremos como escrever uma ação GitHub que consulta um sistema de software centrado em dados – neste exemplo, o Google Analytics – para gerar uma notificação e mensagem automatizadas do Slack. No exemplo abaixo, geraremos uma lista das dez páginas mais visualizadas em meu site nos últimos 7 dias e postaremos uma mensagem bem formatada em um canal público do Slack todas as sextas-feiras às 10h.

Esse método não apenas exibe dados para pessoas que possam precisar deles, mas também fornece uma maneira fácil de copiar e colar um relatório de dados em um slide para uma reunião semanal da empresa/departamento. Por que isso é necessário? Bem, o Google Analytics como produto de software é ótimo, mas normalmente nem todos na sua organização têm acesso.

Esta é a aparência do relatório postado no Slack e abaixo você encontrará um link para o repositório GitHub.

GitHub

Para usar este repositório, siga as etapas descritas no README.

• https://github.com/PaulieScanlon/tns-github-actions-analytics

Pré-requisitos

Para construir este fluxo de trabalho, você precisará de acesso de administrador às suas contas do Google Analytics e Slack e privilégios de administrador para ações e segredos do GitHub para um repositório GitHub.

Personalizando o relatório e a ação

Naturalmente, todo o código pode ser alterado para atender às suas necessidades e nas seções a seguir explicarei as áreas que você provavelmente desejará examinar.

Personalizando a ação do GitHub

O nome do arquivo Action analytics-report.yml não é visto em nenhum outro lugar além do código/repo, mas altere-o para o que quiser – você não quebrará nada.

O name e jobs: os nomes detalhados abaixo são vistos na UI do GitHub e nos logs do fluxo de trabalho.

O cron a sintaxe determina quando a ação será executada. As programações usam a sintaxe cron POSIX e, alterando os números, você pode determinar quando a ação é executada.

Você também pode alterar os nomes das variáveis ​​​​secretas, mas certifique-se de atualizá-las também em seu repositório Configurações.

Veja o código no Gist.

Personalizando o relatório do Google Analytics

A solicitação da API do Google Analytics que estou usando está configurada para extrair o fullPageUrl e pageTitle para todos os usuários ativos nos últimos sete dias e, em seguida, agrega os totais e limita a resposta a dez.

Você pode usar o GA4 Query Explorer do Google para construir sua própria consulta e, em seguida, substituir o runReport parte do código mostrado abaixo.

Veja o código no Gist.

Personalizando a mensagem do Slack

A configuração de mensagem do Slack que estou usando cria um título com um emoji, uma divisória e um parágrafo explicando qual é a mensagem.

Abaixo disso, estou usando o Markdown para construir um relatório iterando a resposta da API do Google Analytics e retornando uma string contendo sintaxe de mensagem específica do Slack, que inclui um link para cada item.

Você pode usar o Block Kit Builder do Slack para construir seu próprio formato de mensagem.

Veja o código no Gist.

Veja o código no Gist.

Antes de executar o GitHub Action, há uma série de etapas do Google, Slack e GitHub a serem concluídas.

Pronto para começar?

Criando um projeto do Google Cloud

Acesse o console do Google Cloud e, no menu suspenso na parte superior da tela, clique em Selecione um projetoe quando o modal abrir, clique em NOVO PROJETO.

Nome do Projeto

Na próxima tela, dê um nome ao seu projeto e clique em CRIAR. No meu exemplo, nomeei o projeto tns-analítica semanal.

Habilitar APIs e serviços

Nesta etapa, você ativará a API de dados do Google Analytics em seu novo projeto. Na barra lateral esquerda, navegue até APIs e serviços > Ativar APIs e serviços. Na parte superior da tela, clique em + ATIVAR APIS E SERVIÇOS.

Ativar API de dados do Google Analytics

Procurar “API de dados do Google Analytics“, selecione-o na lista e clique em HABILITAR.

Crie credenciais para a API de dados do Google Analytics

Com a API habilitada em seu projeto, agora você pode criar as credenciais necessárias. Clique no CRIAR CREDENCIAIS botão no canto superior direito da tela para configurar uma nova conta de serviço.

Uma conta de serviço permite que um “aplicativo” interaja com as APIs do Google, fornecendo as credenciais que incluem os serviços necessários. Neste exemplo, as credenciais concedem acesso à API de dados do Google Analytics.

Tipo de credenciais da conta de serviço

Na próxima tela, selecione “API de dados do Google Analytics” no menu suspenso e Dados de aplicativosentão clique PRÓXIMO.

Detalhes da conta de serviço

Na próxima tela, dê à sua conta de serviço um carne, EU IAe descrição (opcional). Então clique CRIAR E CONTINUAR. No meu exemplo, dei à minha conta de serviço um nome e ID de tns-analítica semanale adicionou uma breve descrição que explica o que a conta de serviço faz.

Função da conta de serviço

Na próxima tela selecione Proprietário para o Rolarentão clique CONTINUAR.

Conta de serviço concluída

Você pode deixar os campos em branco nesta última etapa e clicar FEITO quando você estiver pronto.

Chaves da conta de serviço

Na navegação à esquerda, selecione Contas de serviçoe clique no mais pontospara abrir o menu e selecionar Gerenciar chaves.

Chave de adição de contas de serviço

Na próxima tela localize o CHAVES guia na parte superior da tela e clique em ADICIONAR CHAVE e selecione Crie uma nova chave.

Chaves de download de contas de serviço

Na próxima tela selecione JSON como o tipo de chave e clique em CRIAR para fazer download das credenciais do seu aplicativo do Google .json arquivo.

Credenciais de aplicativos do Google

Se você abrir o .json arquivo em seu editor de código, você deverá ver algo semelhante ao abaixo.

Caso você esteja se perguntando, não, você não pode usar um objeto como uma variável definida em um .env arquivo. Para usar essas credenciais, é necessário converter todo o arquivo em uma string base64.

No seu terminal, execute o seguinte, substituindo nome-do-arquivo-creds.json com o seu nome .json arquivo.

Veja o código no Gist.

Se você já clonou o repositório e seguiu as etapas de introdução no README, adicione a string base64 retornada após executar o procedimento acima e adicione-a ao GOOGLE_APPLICATION_CREDENTIALS_BASE64 variável em seu .env arquivo. Mas certifique-se de colocar a string entre aspas duplas, por exemplo:

Veja o código no Gist.

Isso completa o lado do projeto do Google. A próxima etapa é adicionar o e-mail da sua conta de serviço à sua propriedade do Google Analytics e encontrar seu Google Analytics ID da propriedade.

Propriedades do Google Analytics

Embora sua conta de serviço agora tenha acesso à API de dados do Google Analytics, ela ainda não tem acesso à sua conta do Google Analytics.

Obtenha o ID da propriedade do Google Analytics

Para fazer consultas à API do Google Analytics, você precisará saber o ID da sua propriedade. Você pode encontrá-lo acessando sua conta do Google Analytics, verifique se está na propriedade correta (na captura de tela abaixo, selecionei minha propriedade GA4 para paulie.dev).

Clique no administrador engrenagem no canto inferior esquerdo da tela e clique em Detalhes da propriedade.

Na próxima tela você verá o ID DA PROPRIEDADE no canto superior direito. Se você já clonou o repositório e seguiu as etapas de introdução no README, adicione o valor do ID da propriedade ao GA4_PROPERTY_ID variável em seu .env arquivo.

Adicionar e-mail do cliente ao Google Analytics

Das credenciais do aplicativo Google .json arquivo que você baixou anteriormente, localize o client_email e copie o endereço de e-mail.

No meu exemplo, fica assim: tns-weekly-analytics@tns-weekly-analytics.iam.gserviceaccount.com.

Agora navegue até Gerenciamento de acesso à propriedade na navegação do lado esquerdo e clique no botão + no canto superior direito e clique em Adicionar usuários.

Na próxima tela adicione o email_cliente para o Endereço de e-mail entrada, desmarque Notificar novos usuários por e-mail e selecione Visualizador sob Funções diretas e restrições de dadosentão clique Adicionar.

Isso completa a seção de propriedades do Google Analytics. Seu “aplicativo” usará as credenciais do aplicativo Google que contêm client_email e agora terá acesso à sua conta do Google Analytics por meio da API de dados do Google Analytics.

Canais Slack e Webhooks

Nas etapas a seguir, você criará um novo canal do Slack que será usado para exibir mensagens enviadas do seu “aplicativo” por meio de um Webhook do Slack.

Criando o canal Slack

Crie um novo canal no seu espaço de trabalho do Slack. Eu nomeei o meu #relatório analítico semanal.

Criando um aplicativo Slack

Vá para o painel da API do Slack e clique em Crie um aplicativo.

Na próxima tela selecione De um manifesto de aplicativo.

Na próxima tela, selecione seu espaço de trabalho do Slack e clique em Próximo.

Nesta tela, você pode dar um nome ao seu aplicativo. No meu exemplo, eu o nomeei Relatório analítico semanal. Clique Próximo quando você estiver pronto.

Na etapa 3, você pode simplesmente clicar Feito.

Com o App criado, agora você pode configurar um Webhook.

Criando um webhook do Slack

Navegar para Webhooks de entrada na navegação à esquerda e, em seguida, mude o botão para Sobre para ativar webhooks de entrada. Em seguida, na parte inferior da tela, clique em Adicionar novo webhook ao espaço de trabalho.

Na próxima tela, selecione seu canal do Slack e clique em Permitir.

Agora você deve ver seu novo Slack Webhook com um botão de cópia. Copie o URL do webhook e, se você já clonou o repositório e seguiu as etapas de primeiros passos no README, adicione o URL do webhook para o SLACK_WEBHOOK_URL variável em seu .env arquivo.

Configuração do aplicativo Slack

Na navegação à esquerda, selecione Informação básica. Nesta tela você pode personalizar seu aplicativo e adicionar um ícone e uma descrição. Certifique-se de clicar Salvar alterações quando você acabar.

Se você for agora para o Slack, verá que seu aplicativo foi adicionado ao seu espaço de trabalho.

Isso conclui a seção Slack deste artigo. Agora é hora de adicionar suas variáveis ​​de ambiente ao GitHub Secrets e executar o fluxo de trabalho.

Adicionar segredos do GitHub

Vá para o Configurações guia do seu repositório GitHub e, na navegação à esquerda, selecione Segredos e variáveisentão clique Ações.

Adicione as três variáveis ​​da sua .env arquivo abaixo Segredos do repositório.

Apenas uma observação sobre a string base64: você não precisará incluir aspas duplas!

Executar fluxo de trabalho

Para testar se sua Action está funcionando corretamente, vá para o Ações guia do seu repositório GitHub, selecione o nome do trabalho (Relatório do Google Analytics de 7 dias), então clique Executar fluxo de trabalho.

Se tudo funcionou corretamente, agora você deve estar vendo uma lista bem formatada das dez principais visualizações de página do seu site no Slack.

Finalizado

E é isso! Um relatório do Google Analytics totalmente automatizado que é postado diretamente no seu Slack. Trabalhei em alguns lugares onde os dados do Google Analytics estavam bloqueados e acho que essa abordagem de compartilhar dados do Analytics com o Slack (algo ao qual todos têm acesso) pode ser muito valiosa para várias pessoas na sua organização.

A postagem Como usar ações e APIs do GitHub para revelar dados importantes apareceu pela primeira vez em The New Stack.