Neste guia, abordamos os recursos de solução de problemas do RTB, que permitem acessar de maneira programática
métricas de campanhas com lances em tempo real que também são expostas pela ferramenta
Detalhamento de RTB encontrada na
IU do Authorized Buyers. Isso inclui bidders.filterSets
, bidders.accounts.filterSets
e
todos os recursos abaixo deles de maneira hierárquica.
Com as métricas dos recursos de solução de problemas do RTB, é possível conseguir insights sobre oportunidades perdidas para ganhar impressões que podem ajudar a otimizar sua campanha de lances em tempo real.
Ajustes na estrutura e no estilo da API
Os recursos de solução de problemas do RTB apresentam algumas mudanças para indicar explicitamente a propriedade e o acesso, oferecem um controle mais granular sobre os dados retornados pela API e se alinham melhor às práticas de design da API do Google.
Recursos no nível do bidder e da conta
Os recursos são estruturados em bidders
e bidders.accounts
. Elas permitem especificar se uma chamada de API está segmentando um bidder (também conhecido como conta principal) e todas as contas filhas associadas ou contas individuais do Authorized Buyers. No contexto da solução de problemas
do RTB, os recursos estruturados em bidders.filterSets
retornam métricas agregadas
para o bidder especificado e todas as contas filhas associadas. Por outro lado, aqueles em bidders.accounts.filterSets
só vão retornar métricas para a conta especificada, seja ela um bidder ou uma conta filha.
Observação: as contas que delegam lances a outro comprador não são contas de bidder e, consequentemente, não podem acessar recursos no nível do bidder. Além disso, contas que não são proponentes não podem acessar recursos impressionMetrics
, filteredBidResponses
, bidResponseErrors
e bidResponsesWithoutBids
no nível da conta.
Introdução aos nomes de recursos como identificadores exclusivos
Os nomes de recursos são usados como identificadores exclusivos em vez de IDs de números inteiros ou strings. Ao criar uma nova instância de um determinado tipo de recurso, agora é preciso especificar um nome de recurso relativo usando o caminho do URI do recurso seguido pelo ID do recurso preferido. Veja a seguir exemplos de nomes relevantes para os recursos de solução de problemas do RTB:
Recurso | Exemplo de nome |
---|---|
bidders.filterSets | bidders/12345678/filterSets/fset_1 |
bidders.accounts.filterSets | bidders/12345678/accounts/87654321/filterSets/fset_2 |
Observação: o ID do recurso especificado para bidders
no nome precisa ser o
ID da conta do Authorized Buyers do bidder. Para accounts
, o ID do recurso precisa ser um ID de conta
do bidder ou de uma conta filha gerenciada por ele. Caso não saiba quais contas do Authorized Buyers
estão associadas à sua Conta do Google, use o método
accounts.list para encontrá-las.
Conjuntos de filtros
Um conjunto de filtros é uma representação das opções de filtragem disponíveis e pode ser criado no nível do bidder ou da conta. Ele é usado para filtrar os resultados da lista dos recursos de solução de problemas do RTB que recuperam métricas para suas campanhas de lances em tempo real.
O filtro aplicado durante a recuperação das métricas é a interseção de cada filtro no conjunto de filtros
especificado. Os filtros de lista, como platforms
, são interpretados como a união de cada item na lista.
Os conjuntos de filtros no nível da conta e do bidder são diferentes e só podem ser acessados no nível em que foram criados, independentemente da conta usada na criação. Um proponente e uma conta filha compartilham conjuntos de filtros criados no nível da conta, enquanto somente um proponente pode acessar recursos nesse nível. A tabela a seguir resume como as contas filhas e do bidder podem acessar recursos em qualquer um dos níveis:
bidders.filterSets | bidders.accounts.filterSets | |
---|---|---|
Conta do bidder | Uma chamada de API que afeta apenas os conjuntos de filtros no nível do bidder. | Uma chamada de API que afeta apenas os conjuntos de filtros no nível da conta. |
Conta Infantil | Essa chamada de API retornará uma resposta de erro. | Uma chamada de API que afeta apenas os conjuntos de filtros no nível da conta. |
Criar um conjunto de filtros
Ao criar um conjunto de filtros, você precisa especificar um período como relativeDateRange
,
absoluteDateRange
ou realtimeTimeRange
. Ao recuperar métricas, o comportamento padrão é que todos os dados sejam fornecidos para o período inteiro. Se você quiser receber
um detalhamento de série temporal no período, especifique timeSeriesGranularity
para indicar intervalos HOURLY
ou DAILY
.
Se você só precisa de um conjunto de filtros por um curto período, defina o parâmetro de consulta isTransient
como true
. Isso indica que o conjunto de filtros é temporário, o que significa que ele não será mantido indefinidamente. Os conjuntos de filtros temporários estarão disponíveis por pelo menos uma hora após serem criados, mas serão excluídos. Por padrão, os conjuntos de filtros não são temporários.
Exemplo no nível do bidder
Para criar um novo conjunto de filtros no nível do bidder, envie uma solicitação POST
para o URI de recurso bidders.filterSets
, que tem o seguinte formato:
https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets
Aviso: os conjuntos de filtros no nível do bidder não podem filtrar por criativos ou IDs da transação. Se você especificar esses filtros ao criar um conjunto de filtros no nível do proponente, receberá uma resposta de erro.
SolicitaçãoVeja um exemplo de uma solicitação POST
que cria um novo conjunto de filtros não temporários no nível do proponente:
POST https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets Authorization: Bearer access token here Content-Type: application/json { "name": "bidders/12345678/filterSets/bidder-fs", "format": "DISPLAY", "environment": "APP", "platforms": ["TABLET", "MOBILE"], "absoluteDateRange": { "startDate": { "month": 11, "day": 26, "year": 2017 }, "endDate": { "month": 12, "day": 3, "year": 2017 } }, "timeSeriesGranularity": "DAILY" }Resposta
Se a solicitação for bem-sucedida, o servidor responderá com um código de status 200 OK. O corpo da resposta incluirá o recurso do conjunto de filtros criado, que será idêntico ao conjunto enviado na solicitação.
Exemplo no nível da conta
Para criar um novo conjunto de filtros no nível da conta, envie uma solicitação POST
para o URI de recurso bidders.accounts.filterSets
, que tem o seguinte formato:
https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets
Observação: o ID do recurso especificado para accounts
pode
ser o ID de qualquer conta do Authorized Buyers acessível à conta do bidder
especificada no URI, incluindo a própria conta do bidder.
Veja um exemplo de uma solicitação POST
que cria um novo conjunto de filtros não temporários no nível da conta:
POST https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets Authorization: Bearer access token here Content-Type: application/json { "name": "bidders/12345678/accounts/87654321/filterSets/account-fs", "format": "VIDEO", "environment": "WEB", "platforms": ["DESKTOP"], "absoluteDateRange": { "startDate": { "month": 11, "day": 26, "year": 2017 }, "endDate": { "month": 12, "day": 3, "year": 2017 } }, "timeSeriesGranularity": "DAILY" }Resposta
Se a solicitação for bem-sucedida, o servidor responderá com um código de status 200 OK. O corpo da resposta inclui o recurso do conjunto de filtros criado, que é idêntico ao enviado na solicitação.
Receber um conjunto de filtros
O método "get" só pode receber um conjunto de filtros no mesmo nível em que foi criado. Por exemplo, uma conta de proponente precisa usar bidders.accounts.filterSets.get
para recuperar um conjunto de filtros criado no nível da conta, em vez do método bidders.filterSets.get
.
Nível do bidder
É possível recuperar um conjunto de filtros no nível do bidder enviando uma solicitação HTTP GET para o URI do recurso bidders.filterSets
, que tem o seguinte formato:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}Solicitação
Confira um exemplo:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/bidder-fsResposta
Se a solicitação for bem-sucedida, o servidor responderá com um código de status HTTP 200 OK
e o conjunto de filtros recuperado:
{ "name": "bidders/12345678/filterSets/bidder-fs", "format": "DISPLAY", "environment": "APP", "platforms": ["TABLET", "MOBILE"], "absoluteDateRange": { "startDate": { "month": 11, "day": 26, "year": 2017 }, "endDate": { "month": 12, "day": 3, "year": 2017 } }, "timeSeriesGranularity": "DAILY" }
Nível da conta
Você pode recuperar um conjunto de filtros no nível da conta enviando uma solicitação GET
HTTP para o URI do recurso bidders.accounts.filterSets
, que tem o seguinte formato:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}Solicitação
Confira um exemplo:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/account-fsResposta
Se a solicitação for bem-sucedida, o servidor responderá com um código de status HTTP 200 OK
e o conjunto de filtros recuperado:
{ "name": "bidders/12345678/accounts/87654321/filterSets/account-fs", "format": "VIDEO", "environment": "WEB", "platforms": ["DESKTOP"], "absoluteDateRange": { "startDate": { "month": 11, "day": 26, "year": 2017 }, "endDate": { "month": 12, "day": 3, "year": 2017 } }, "timeSeriesGranularity": "DAILY" }
Listar conjuntos de filtros
O método de lista retornará apenas os conjuntos de filtros acessíveis no nível em que ele está sendo chamado.
Por exemplo, uma conta de bidder não verá os conjuntos de filtros criados para si mesma por meio de
bidders.accounts.filterSets.create
ao chamar bidders.filterSets.list
.
Nível do bidder
É possível recuperar todos os conjuntos de filtros no nível do bidder para um determinado bidder enviando uma solicitação GET
HTTP
para o URI do recurso bidders.filtersets
, que tem o seguinte formato:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSetsSolicitação
Veja um exemplo que lista todos os conjuntos de filtros no nível do bidder para um bidder com o ID de conta 12345678:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSetsResposta
{ "filterSets": [{ "filterSetId": "99994", "name": "bidders/12345678/filterSets/test-b-1", "relativeDateRange": { "durationDays": 30 } }, { "realtimeTimeRange": { "startTimeStamp": "2017-11-15T12:30:30.072831583Z" }, "filterSetId": "99995", "name": "bidders/12345678/filterSets/test-b-2", "timeSeriesGranularity": "HOURLY" }, { "absoluteDateRange": { "endDate": { "day": 12, "month": 3, "year": 2017 }, "startDate": { "day": 26, "month": 11, "year": 2017 } }, "filterSetId": "99996", "name": "bidders/12345678/filterSets/bidder-fs", "timeSeriesGranularity": "DAILY", "platforms": ["TABLET", "MOBILE"], "environment": "APP", "format": "DISPLAY" } ] }
Nível da conta
É possível recuperar todos os conjuntos de filtros no nível da conta enviando uma solicitação GET
HTTP para o URI do recurso bidders.accounts.filtersets
, que tem o seguinte formato:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSetsSolicitação
Veja um exemplo que lista todos os conjuntos de filtros no nível da conta de uma conta filha com o ID 87654321:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSetsResposta
{ "filterSets": [{ "realtimeTimeRange": { "startTimeStamp": "2017-11-19T04:24:43.252893487Z" }, "filterSetId": "99997", "name": "bidders/12345678/accounts/87654321/filterSets/test-a-1", "timeSeriesGranularity": "DAILY" }, { "absoluteDateRange": { "endDate": { "day": 3, "month": 12, "year": 2017 }, "startDate": { "day": 26, "month": 11, "year": 2017 } }, "filterSetId": "99998", "name": "bidders/12345678/accounts/87654321/filterSets/account-fs", "timeSeriesGranularity": "DAILY", "platforms": ["DESKTOP"], "environment": "WEB", "format": "VIDEO" } ] }
Excluir um conjunto de filtros
Você pode usar o método delete
para remover todos os conjuntos de filtros não temporários que não são mais necessários. Ela só pode remover conjuntos de filtros acessíveis no nível em que está sendo chamada.
Por exemplo, uma conta de proponente não pode excluir um conjunto de filtros criado com bidders.accounts.filterSets.create
com bidders.filterSets.delete
.
Nível do bidder
É possível excluir um conjunto de filtros no nível do proponente para uma determinada conta enviando uma solicitação HTTP DELETE
para o URI do recurso bidders.filtersets
, que tem o seguinte formato:
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}Solicitação
Confira um exemplo de exclusão de um conjunto de filtros no nível do bidder:
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/test-b-2Resposta
Se a solicitação for bem-sucedida, o corpo da solicitação vai ficar vazio. O conjunto de filtros especificado não poderá mais ser acessado.
Nível da conta
É possível excluir um conjunto de filtros no nível da conta enviando uma solicitação DELETE
HTTP para o URI do recurso bidders.accounts.filtersets
, que tem o seguinte formato:
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}Solicitação
Veja um exemplo de exclusão de um conjunto de filtros no nível da conta:
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/test-a-1Resposta
Se a solicitação for bem-sucedida, o corpo da solicitação vai ficar vazio. O conjunto de filtros especificado não poderá mais ser acessado.
Recuperar métricas de solução de problemas do RTB
Todos os recursos de solução de problemas do RTB usados para receber métricas funcionam de maneira semelhante: eles têm um único método para listar métricas para o conjunto de filtros especificado por um parâmetro de caminho filterSetName
. O conjunto de filtros especificado determinará quais filtros e configurações serão aplicados ao
consultar as métricas. Chamar esses recursos no nível do bidder vai retornar métricas agregadas
da conta do bidder e de todas as contas filhas associadas, enquanto uma chamada do nível da conta
só vai retornar métricas de uma conta individual.
Métricas de lance
O recurso bidMetrics
é usado para recuperar métricas que são medidas no número de lances. Por exemplo, é possível usar isso para determinar o número total de lances em um determinado período e quantos deles não foram filtrados do leilão, ganharam uma impressão etc. Como todos os outros recursos de solução de problemas de RTB usados para coletar métricas, ele só tem um método list
.
Listar métricas de lance no nível do bidder
É possível listar métricas de lance no nível do bidder para um determinado conjunto de filtros enviando uma solicitação HTTP GET
para o URI do recurso bidders.filtersets.bidMetrics
, que tem o seguinte formato:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}/bidMetricsSolicitação
Veja um exemplo que lista as métricas de lance no nível do bidder:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/bidder-fs/bidMetricsResposta
Se a solicitação for bem-sucedida, o servidor responderá com um código de status 200 OK
e um corpo com linhas de métricas para as dimensões e a granularidade especificadas.
{ "bidMetricsRows": [{ "bids": { "value": "6160" }, "bidsInAuction": { "value": "5698" }, "billedImpressions": { "value": "1196" }, "impressionsWon": { "value": "2920" }, "measurableImpressions": { "value": "1160" }, "rowDimensions": { "timeInterval": { "endTime": "2017-11-29T08:00:00Z", "startTime": "2017-11-28T08:00:00Z" } }, "viewableImpressions": { "value": "683" } }, { "bids": { "value": "104288" }, "bidsInAuction": { "value": "94016" }, "billedImpressions": { "value": "99" }, "impressionsWon": { "value": "125" }, "measurableImpressions": { "value": "94" }, "rowDimensions": { "timeInterval": { "endTime": "2017-11-30T08:00:00Z", "startTime": "2017-11-29T08:00:00Z" } }, "viewableImpressions": { "value": "87" } }, { "bids": { "value": "3999" }, "bidsInAuction": { "value": "3631" }, "billedImpressions": { "value": "618" }, "impressionsWon": { "value": "1819" }, "measurableImpressions": { "value": "604" }, "rowDimensions": { "timeInterval": { "endTime": "2017-12-01T08:00:00Z", "startTime": "2017-11-30T08:00:00Z" } }, "viewableImpressions": { "value": "369" } }, { "bids": { "value": "15" }, "bidsInAuction": { "value": "3" }, "billedImpressions": {}, "impressionsWon": { "value": "3" }, "measurableImpressions": {}, "rowDimensions": { "timeInterval": { "endTime": "2017-12-02T08:00:00Z", "startTime": "2017-12-01T08:00:00Z" } }, "viewableImpressions": {} } ] }
Observação: os campos definidos como 0 para uma determinada métrica não aparecerão na resposta.
As métricas billedImpressions
e measurableImpressions
vazias acima indicam que o valor e a variação delas estão definidos como 0.
Aviso: para qualquer detalhamento de dados na resposta, ela não
incluirá linhas se elas não contiverem pelo menos uma métrica diferente de zero. Por exemplo, quando um timeSeriesGranularity
é especificado, a resposta não inclui linhas para nenhum timeInterval
no período especificado do conjunto de filtros em que todas as métricas são zero.
Listar métricas de lance no nível da conta
É possível listar métricas de lances no nível da conta para um determinado conjunto de filtros enviando uma solicitação GET
HTTP para o URI do recurso bidders.accounts.filtersets.bidMetrics
, que tem o seguinte formato:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}/bidMetricsSolicitação
Veja um exemplo que lista as métricas de lance no nível da conta:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/account-fs/bidMetricsResposta
Se a solicitação for bem-sucedida, o servidor responderá com um código de status 200 OK
e um corpo com linhas de métricas para as dimensões e a granularidade especificadas.
{ "bidMetricsRows": [{ "bids": { "value": "1748" }, "bidsInAuction": { "value": "1421" }, "billedImpressions": { "value": "301" }, "impressionsWon": { "value": "915" }, "measurableImpressions": { "value": "298" }, "rowDimensions": { "timeInterval": { "endTime": "2017-12-01T08:00:00Z", "startTime": "2017-11-30T08:00:00Z" } }, "viewableImpressions": { "value": "172" } }, { "bids": { "value": "6" }, "bidsInAuction": { "value": "2" }, "billedImpressions": {}, "impressionsWon": { "value": "1" }, "measurableImpressions": {}, "rowDimensions": { "timeInterval": { "endTime": "2017-12-02T08:00:00Z", "startTime": "2017-12-01T08:00:00Z" } }, "viewableImpressions": {} } ] }
Observação: os campos definidos como 0 para uma determinada métrica não aparecerão na resposta. As métricas vazias billedImpressions
e measurableImpressions
acima indicam que o valor e a variação delas estão definidos como 0.
Aviso: para qualquer detalhamento de dados na resposta, ela não incluirá
linhas se elas não contiverem pelo menos uma métrica diferente de zero. Por exemplo, quando um timeSeriesGranularity
é especificado, a resposta não inclui linhas para nenhum timeInterval
no período especificado do conjunto de filtros em que todas as métricas são zero.