Neste documento, descrevemos as listas de público-alvo recorrentes, que são um recurso avançado da API Google Analytics Data v1. Para uma introdução ao recurso de exportação de listas de público-alvo, consulte o guia de conceitos básicos de exportação de público-alvo.
As listas de público-alvo recorrentes são geradas diariamente conforme as associações de público-alvo mudam, para garantir que você esteja trabalhando com os dados mais recentes.
As listas de público-alvo regulares (não recorrentes) são listas estáticas de usuários no público-alvo no momento em que a lista é gerada.
Criar uma lista de público-alvo diariamente
O tempo necessário para processar os dados de público-alvo de um dia e atualizar as associações varia. Não há como garantir que os dados da lista de público-alvo sejam atualizados em 24 horas.
Por exemplo, mesmo que você peça uma lista de público-alvo no mesmo horário todos os dias, em alguns dias ela será igual à do dia anterior, e em outros, será diferente e vai conter um dia adicional de mudanças na associação.

As listas de público-alvo são baseadas em dados de eventos do dia anterior às mudanças mais recentes na associação. Se você criar uma lista de público-alvo antes das atualizações diárias de associação, ela vai usar os dados dos dois dias anteriores. Se você criar uma lista de público-alvo após as atualizações diárias de associação, ela vai usar os dados de ontem.
Consultar periodicamente uma lista de público-alvo recorrente
As listas de público-alvo recorrentes só produzem listas de público-alvo quando os dados de um dia adicional estão disponíveis. Isso elimina a necessidade de adivinhar quando criar novas listas de público-alvo. Em vez disso, você pode consultar a lista de público-alvo recorrente ao longo do dia para verificar se há mais dados disponíveis.

Criar uma lista de público-alvo recorrente
Para criar uma lista de público-alvo recorrente, chame o método
recurringAudienceLists.create
usando o objeto
RecurringAudienceList
em uma solicitação. Os seguintes parâmetros são necessários:
- Um nome de público-alvo válido no campo
audience, formatado comoproperties/{propertyId}/audiences/{audienceId}. Use o métodoaudiences.listda v1 da API Admin do Google Analytics para conseguir esse valor. O campoAudience.nameda respostaaudiences.listcontém o nome do público-alvo. - Uma lista válida de dimensões no campo
dimensions. A lista de dimensões compatíveis com esse método pode ser encontrada na documentação do esquema de exportação de público-alvo. Somente os dados das dimensões mencionadas nesse campo são incluídos em uma lista de público-alvo.
Confira um exemplo de solicitação de criação de lista de público-alvo recorrente:
Solicitação HTTP
POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/recurringAudienceLists
{
"audience": "properties/1234567/audiences/12345",
"dimensions": [
{
"dimensionName": "deviceId"
}
]
}
Uma resposta do método recurringAudienceLists.create contém o nome no campo name (como properties/1234567/recurringAudienceLists/123), que pode ser usado em consultas subsequentes para recuperar os metadados de configuração dessa lista de público-alvo recorrente. Além disso, os metadados de configuração contêm
nomes de recursos para instâncias de lista de público-alvo
criadas para essa lista recorrente.
Resposta HTTP
{
"name": "properties/1234567/recurringAudienceLists/123",
"audience": "properties/1234567/audiences/12345",
"audienceDisplayName": "Purchasers",
"dimensions": [
{
"dimensionName": "deviceId"
}
],
"activeDaysRemaining": 180,
"audienceLists": [
"properties/1234567/audienceLists/45678"
]
}
Metadados de configuração da enquete
Use o método recurringAudienceLists.get para recuperar metadados de configuração sobre uma lista de público-alvo recorrente específica. Os metadados de configuração contêm
nomes de recursos para instâncias de lista de público-alvo
criadas para essa lista de público-alvo recorrente.
Veja um exemplo:
Solicitação HTTP
GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/recurringAudienceLists/123
Uma instância de RecurringAudienceList
é retornada em resposta. Ele contém os metadados de configuração, que incluem
nomes de recursos para instâncias de lista de público-alvo
criadas para essa lista de público-alvo recorrente.
Resposta HTTP
{
"name": "properties/1234567/recurringAudienceLists/123",
"audience": "properties/1234567/audiences/12345",
"audienceDisplayName": "Purchasers",
"dimensions": [
{
"dimensionName": "deviceId"
}
],
"activeDaysRemaining": 180,
"audienceLists": [
"properties/1234567/audienceLists/45678"
]
}
Use
recurringAudienceLists.list
para listar todas as listas de público-alvo recorrentes de uma propriedade.
Usar webhooks para receber notificações assíncronas sobre novas listas de público-alvo
Em vez de consultar periodicamente os metadados de configuração de uma lista de público-alvo recorrente específica usando o método recurringAudienceLists.get, você pode receber notificações de webhook de forma assíncrona quando uma lista de público-alvo estiver disponível.
Para configurar as notificações de webhook, especifique o campo webhookNotification ao criar uma nova lista de público-alvo recorrente.
Siga o guia Async audience lists with webhooks para mais informações sobre como usar webhooks na API Google Analytics Data v1.
Recuperar usuários em uma exportação de público-alvo
Para recuperar usuários em uma exportação de público-alvo, chame o método audienceExports.query e especifique o nome da exportação de público-alvo recuperado dos metadados de configuração fornecidos por recurringAudienceLists.get ou recurringAudienceLists.list.
Solicitação HTTP
POST https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports/123:query
Se a exportação de público-alvo estiver pronta, uma resposta com a lista de usuários em um público-alvo será retornada:
Resposta HTTP
{
"audienceExport": {
"name": "properties/1234567/audienceExports/123",
"audience": "properties/1234567/audiences/12345",
"audienceDisplayName": "Purchasers",
"dimensions": [
{
"dimensionName": "deviceId"
}
],
"state": "ACTIVE",
"beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
},
"audienceRows": [
{
"dimensionValues": [
{
"value": "1000276123.1681742376"
}
]
},
{
"dimensionValues": [
{
"value": "1000374452.1668627377"
}
]
},
{
"dimensionValues": [
{
"value": "1000391956.1652750758"
}
]
},
{
"dimensionValues": [
{
"value": "1000410539.1682018694"
}
]
},
{
"dimensionValues": [
{
"value": "1000703969.1666725875"
}
]
}
],
"rowCount": 5
}