Este guia explica como usar webhooks para receber notificações assíncronas sobre o status das suas solicitações de exportação de público-alvo. Esse recurso está disponível apenas na versão v1alpha da API Data.
As notificações de webhook são um recurso avançado da API Data do Google Analytics. Para uma introdução ao recurso de exportação de público-alvo, consulte Criar uma exportação de público-alvo.
Sem webhooks, você vai precisar consultar a API periodicamente para determinar quando uma solicitação é concluída.
Criar um aplicativo de webhook de exemplo usando o Cloud Run
É possível criar um aplicativo de webhook de exemplo usando o Google Cloud seguindo o tutorial Guia de início rápido: implantar um serviço de exemplo no Cloud Run.
Para que o serviço de exemplo receba solicitações de notificação de webhook POST,
substitua o arquivo index.js do tutorial de início rápido pelo seguinte
código:
import express from 'express';
const app = express();
app.use(express.json());
app.post('/', (req, res) => {
const channelToken = req.get('X-Goog-Channel-Token');
const bodyJson = JSON.stringify(req.body);
console.log(`channel token: ${channelToken}`);
console.log(`notification body: ${bodyJson}`);
res.sendStatus(200);
});
const port = parseInt(process.env.PORT) || 8080;
app.listen(port, () => {
console.log(`helloworld: listening on port ${port}`);
});
Para cada notificação de webhook recebida enviada como uma solicitação POST, esse código imprime
o corpo JSON da notificação de webhook e um valor de token de canal e
retorna o código HTTP 200 para indicar a operação bem-sucedida.
Depois de concluir o tutorial de início rápido do Cloud Run e implantar o aplicativo do webhook usando o comando gcloud run deploy, salve o URL em que o serviço foi implantado.
O URL do serviço aparece no console, por exemplo:
Service URL: https://webhooks-test-abcdef-uc.a.run.app
Esse é o URI de notificação do servidor em que seu aplicativo escuta notificações de webhook do Google Analytics.
Criar uma lista de público-alvo e ativar as notificações por webhook
Para solicitar notificações de webhook, especifique os seguintes valores no objeto
webhookNotification:
O URI de notificação do servidor que contém o endereço da Web que vai receber as notificações do webhook.
(Opcional) Uma string arbitrária
channelTokenpara evitar que a mensagem seja falsificada. Especifique ochannelTokenno cabeçalho HTTPX-Goog-Channel-Tokenda solicitação POST do webhook.
Confira um exemplo de solicitação que usa webhooks:
Solicitação HTTP
POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/audienceLists
{
"webhookNotification": {
"uri": "https://webhooks-test-abcdef-uc.a.run.app",
"channelToken": "123456"
},
"audience": "properties/1234567/audiences/12345",
"dimensions": [
{
"dimensionName": "deviceId"
}
]
}
A resposta do método audienceLists.create contém o
webhookNotification, que confirma que o webhook especificado respondeu
em menos de 5 segundos.
Veja um exemplo de resposta:
Resposta HTTP
{
"response": {
"@type": "type.googleapis.com/google.analytics.data.v1alpha.AudienceList",
"name": "properties/1234567/audienceLists/123",
"audience": "properties/1234567/audiences/12345",
"audienceDisplayName": "Purchasers",
"dimensions": [
{
"dimensionName": "deviceId"
}
],
"state": "ACTIVE",
"beginCreatingTime": "2024-06-10T04:50:09.119726379Z",
"creationQuotaTokensCharged": 51,
"rowCount": 13956,
"percentageCompleted": 100,
"webhookNotification": {
"uri": "https://webhooks-test-abcdef-uc.a.run.app",
"channelToken": "123456"
}
}
}
Se um webhook não responder ou se você fornecer um URL de serviço incorreto, uma mensagem de erro será retornada.
Confira um exemplo de erro que você pode receber:
{
"error": {
"code": 400,
"message": "Expected response code of 200 from webhook URI but instead
'404' was received.",
"status": "INVALID_ARGUMENT"
}
}
Processar notificações de webhook
A solicitação POST para um serviço de webhook contém uma versão JSON do
recurso de operação de longa execução
no corpo e um campo sentTimestamp. O carimbo de data/hora enviado especifica
o horário da Era Unix em microssegundos em que a solicitação foi enviada. É possível usar esse
carimbo de data/hora para identificar notificações repetidas.
Uma ou duas solicitações POST são enviadas ao webhook durante a criação de uma lista de público-alvo:
- A primeira solicitação POST é enviada imediatamente, mostrando a lista de público-alvo recém-criada
no estado
CREATING. Se a primeira solicitação ao webhook falhar, a operaçãoaudienceLists.createvai retornar um erro e os detalhes da falha do webhook. - A segunda solicitação POST é enviada depois que a criação da lista de público-alvo é concluída. A criação é concluída quando a lista de público-alvo atinge o estado
ACTIVEouFAILED.
Confira um exemplo da primeira notificação para uma lista de público-alvo no estado
CREATING:
{
"sentTimestamp":"1718261355692983",
"name": "properties/1234567/audienceLists/123",
"audience": "properties/1234567/audiences/12345",
"audienceDisplayName":"Purchasers",
"dimensions":[{"dimensionName":"deviceId"}],
"state":"CREATING",
"beginCreatingTime": "2024-06-10T04:50:09.119726379Z",
"creationQuotaTokensCharged":0,
"rowCount":0,
"percentageCompleted":0,
"webhookNotification":
{
"uri": "https://webhooks-test-abcdef-uc.a.run.app",
"channelToken":"123456"
}
}
Confira um exemplo da segunda notificação para uma lista de público-alvo no estado ACTIVE:
{
"sentTimestamp":"1718261355692983",
"name": "properties/1234567/audienceLists/123",
"audience": "properties/1234567/audiences/12345",
"audienceDisplayName":"Purchasers",
"dimensions":[{"dimensionName":"deviceId"}],
"state":"ACTIVE",
"beginCreatingTime": "2024-06-10T04:50:09.119726379Z",
"creationQuotaTokensCharged":68,
"rowCount":13956,
"percentageCompleted":100,
"webhookNotification":
{
"uri": "https://webhooks-test-abcdef-uc.a.run.app",
"channelToken":"123456"
}
}
A segunda notificação confirma que a lista de público-alvo foi criada e está
pronta para ser consultada usando o método
audienceLists.query.
Para testar webhooks depois de chamar o método audienceLists.create, é possível
inspecionar os registros
do seu aplicativo de webhook do Cloud Run de exemplo e conferir o corpo JSON de cada
notificação enviada pelo Google Analytics.