Esta página foi traduzida pela API Cloud Translation.

Solução de problemas do RTB

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ção

Veja 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.

Solicitação

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-fs

Resposta

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-fs

Resposta

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}/filterSets

Solicitaçã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/filterSets

Resposta

{
  "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}/filterSets

Solicitaçã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/filterSets

Resposta

{
  "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-2

Resposta

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-1

Resposta

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}/bidMetrics

Solicitaçã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/bidMetrics

Resposta

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}/bidMetrics

Solicitaçã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/bidMetrics

Resposta

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.