Neste guia, explicamos como usar webhooks para receber notificações assíncronas para o status das suas solicitações de exportação de público-alvo. Este recurso está disponível apenas na versão v1alpha da API Data.
Notificações de webhook são um recurso avançado da interface de dados do Google Analytics API. Para uma introdução ao de exportação de público-alvo, consulte Criar uma exportação de público-alvo.
Sem os webhooks, você precisará pesquisar periodicamente a API para determinar quando uma solicitação é concluída.
Criar um aplicativo de webhook de amostra usando o Cloud Run
Para criar um aplicativo de webhook de amostra usando o Google Cloud, siga estas instruções: o tutorial Guia de início rápido: implantar um serviço de amostra no Cloud Run
Para que o serviço de amostra detecte 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 é impresso.
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.
Ao chegar ao fim do tutorial de início rápido do Cloud Run e fazer a implantação
o aplicativo de webhook usando o comando gcloud run deploy, salve
o URL em que o serviço está implantado.
O URL do serviço é exibido no console, por exemplo:
Service URL: https://webhooks-test-abcdef-uc.a.run.app
Esse é o URI de notificação do servidor de onde o aplicativo escuta notificações webhook Google Analytics.
Criar uma lista de público-alvo e ativar as notificações de webhook
Para solicitar notificações de webhook, especifique os seguintes valores em webhookNotification.
objeto:
O URI de notificação do servidor contendo o endereço da Web que receberá as notificações de webhook.
(Opcional) Uma string arbitrária
channelToken. para se proteger contra spoofing. Especifique ochannelTokenno cabeçalho HTTPX-Goog-Channel-Tokenda solicitação POST do webhook.
Veja 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 as
webhookNotification, que confirma 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.
Este é 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 webhook
A solicitação POST para um serviço de webhook contém uma versão JSON do
recurso de operação de longa duração
no corpo e um campo sentTimestamp. O carimbo de data/hora enviado especifica
o horário da época Unix em microssegundos em que a solicitação foi enviada. Você pode usar isso
para identificar notificações repetidas.
Uma ou duas solicitações POST são enviadas para o webhook durante uma criação da lista de público-alvo:
- A primeira solicitação POST é enviada imediatamente, mostrando a recém-criada
lista de público-alvo no estado
CREATING. Se a primeira solicitação ao o webhook falhar, a operaçãoaudienceLists.createretornará um erro e os detalhes da falha do webhook. - A segunda solicitação POST é enviada depois que a lista de público-alvo é concluída.
criação. A criação é concluída quando a lista de público-alvo alcança
o estado
ACTIVEouFAILED.
Veja um exemplo da primeira notificação de uma lista de público-alvo, na
CREATING estado:
{
"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"
}
}
Veja um exemplo da segunda notificação de uma lista de público-alvo, na
ACTIVE estado:
{
"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
pronto para ser consultado usando o audienceLists.query.
.
Para testar webhooks depois de chamar o método audienceLists.create, faça o seguinte:
inspecione os registros
do aplicativo de webhook do Cloud Run e conferir o corpo JSON de cada
notificação enviada pelo Google Analytics.