Esta página foi traduzida pela API Cloud Translation.

Solução de problemas do RTB

Este guia aborda recursos de solução de problemas de RTB, que permitem acessar de forma programática métricas de campanhas de lances em tempo real que também são expostas por meio do ferramenta Detalhamento do RTB, encontrada na interface do Authorized Buyers. Entre eles estão bidders.filterSets, bidders.accounts.filterSets e todos os recursos abaixo deles hierarquicamente.

Com as métricas dos recursos de solução de problemas de RTB, é possível receber insights sobre oportunidades perdidas para receber impressões que ajudam a otimizar sua campanha de lances em tempo real.

Ajustes na estrutura e no estilo da API

Os recursos de solução de problemas de RTB apresentam algumas alterações para indicar explicitamente a propriedade e acesso, proporcionam controle mais granular sobre os dados retornados pela API e melhor alinham-se 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 segmenta um proponente (também conhecido como conta principal) e todas as secundárias ou individuais do Authorized Buyers. No contexto do RTB Solução de problemas: os recursos estruturados em bidders.filterSets vão retornar métricas agregadas para o bidder em questão e todas as contas filhas associadas. Em contraste, aqueles sob bidders.accounts.filterSets só retornará métricas da conta especificada, independentemente das seja uma conta secundária ou um bidder.

Observação: as contas que delegam lances a outro comprador não são contas de bidder, e Consequentemente, não pode acessar recursos no nível do bidder. Além disso, as contas que não são do bidder não podem acessar impressionMetrics, filteredBidResponses, bidResponseErrors no nível da conta e bidResponsesWithoutBids recursos.

Introdução de nomes de recursos como identificadores exclusivos

Os nomes de recursos são usados como identificadores exclusivos em vez de IDs inteiros ou de string. Ao criar uma nova instância de um determinado tipo de recurso, especifique relativo nome do recurso usando o caminho de URI do recurso seguido pelo ID de recurso preferencial. A 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 de um bidder É o ID da conta do Authorized Buyers. Para accounts, o ID do recurso precisa ser um ID de conta de o bidder ou uma conta secundária gerenciada por ele. Se você não souber quais Authorized Buyers estão associadas à sua Conta do Google, use o 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 criada no nível da conta ou do bidder. É usada para filtrar os resultados da lista da solução de problemas do RTB recursos que recuperam métricas para suas campanhas de lances em tempo real.

O filtro aplicado ao recuperar métricas é a interseção de cada filtro na um conjunto de filtros. 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 o eles foram criados, independentemente da conta usada para criá-los. Um compartilhamento de conta secundária e bidder conjuntos de filtros criados no nível da conta, enquanto apenas um proponente pode acessar recursos no nível do bidder. A tabela a seguir resume como as contas de bidder e filhas podem acessar recursos em qualquer nível:

	bidders.filterSets	bidders.accounts.filterSets
Conta do bidder	Uma chamada de API que afeta somente 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, a O comportamento padrão é fornecer todos os dados de todo o período. Se você quiser receber um detalhamento da série temporal ao longo do período, é possível especificar timeSeriesGranularity para indicar intervalos HOURLY ou DAILY.

Se você só precisar de um conjunto de filtros para um curto período, defina o 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 vão ficar disponíveis por pelo menos uma hora após a criação, 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 ID do criativo ou da transação. Se você especificar esses filtros ao criar um conjunto de filtros no nível do bidder, vai 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 bidder:

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 vai 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 de recurso especificado para accounts pode ser o ID de qualquer conta do Authorized Buyers acessível ao bidder. conta especificada no URI, incluindo a própria conta do proponente.

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 incluir o recurso do conjunto de filtros criado, que será idêntico ao conjunto de filtros enviado no da solicitação.

Obter um conjunto de filtros

O método "get" só pode obter um conjunto de filtros no mesmo nível em que foi criado. Por exemplo, um bidder a conta precisa usar bidders.accounts.filterSets.get para recuperar um conjunto de filtros criado na conta em vez do método bidders.filterSets.get.

Nível do bidder

Para recuperar um conjunto de filtros no nível do bidder, envie uma solicitação GET HTTP ao URI de 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

Veja 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

Para recuperar um conjunto de filtros no nível da conta, envie 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

Veja 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 "list" retorna somente os conjuntos de filtros acessíveis no nível em que é chamado. Por exemplo, uma conta de proponente não verá os conjuntos de filtros criados para si mesma por meio bidders.accounts.filterSets.create ao chamar bidders.filterSets.list.

Nível do bidder

Para recuperar todos os conjuntos de filtros no nível do bidder de um determinado bidder, envie um HTTP GET solicitação para o URI de 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 proponente com o ID da 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

Você pode recuperar todos os conjuntos de filtros no nível da conta de uma determinada conta enviando um GET HTTP solicitação para o URI de 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

Este é um exemplo que lista todos os conjuntos de filtros no nível da conta para 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 os conjuntos de filtros não temporários que não são mais necessário. Ele só pode remover conjuntos de filtros acessíveis no nível em que é chamado. por exemplo, uma conta de bidder 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 bidder de uma determinada conta enviando uma solicitação DELETE HTTP ao URI de 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

Veja 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 bem-sucedido, o corpo da solicitação ficará vazio. O conjunto de filtros especificado não poderá mais ser acessado.

Nível da conta

Você pode excluir um conjunto de filtros no nível da conta para uma determinada conta enviando um DELETE HTTP solicitação para o URI de 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 bem-sucedido, o corpo da solicitação ficará vazio. O conjunto de filtros especificado não poderá mais ser acessado.

Recuperar métricas de solução de problemas de RTB

Todos os recursos de solução de problemas de RTB usados para receber métricas funcionam de maneira semelhante: eles têm um método único para listar métricas do conjunto de filtros especificado por um caminho filterSetName . O conjunto de filtros especificado determinará quais filtros e configurações serão aplicados quando consultando as métricas. Chamar esses recursos no nível do bidder vai retornar métricas agregadas da conta do proponente e de todas as contas secundárias associadas, enquanto uma chamada do nível da conta só retornará métricas de uma conta individual.

Métricas de lance

O recurso bidMetrics é usado para recuperar métricas medidas no máximo de lances. Por exemplo, você pode usar isso para determinar o número total de lances em um período, e quantos deles não foram filtrados do leilão, ganharam uma impressão, Assim como todos os outros recursos de solução de problemas de RTB usados para coletar métricas, ele tem apenas 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 um GET HTTP solicitação para o URI de 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 de uma listagem das 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 contendo 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 aparecem na resposta. As métricas billedImpressions e measurableImpressions vazias acima indicam que tanto o valor quanto a variância estão definidos como 0.

Aviso: para qualquer detalhamento dos dados na resposta, a resposta não será incluir linhas se não contiverem pelo menos uma métrica diferente de zero. Por exemplo, quando um timeSeriesGranularity for especificado, a resposta não incluirá linhas para nenhum timeInterval durante o período especificado do conjunto de filtros em que todas as métricas são zero.

Listar métricas de lances no nível da conta

Você pode listar métricas de lances no nível da conta para um determinado conjunto de filtros enviando um GET HTTP para o URI do recurso bidders.accounts.filtersets.bidMetrics, que tem o 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 contendo 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 aparecem na resposta. A as métricas billedImpressions e measurableImpressions vazias acima indicam que tanto o valor quanto a variância deles sejam definidos como 0.

Aviso: para qualquer detalhamento de dados na resposta, a resposta não incluirá de linhas se elas não contiverem pelo menos uma métrica diferente de zero. Por exemplo, quando um timeSeriesGranularity for especificado, a resposta não incluirá linhas para nenhum timeInterval durante o período especificado do conjunto de filtros em que todas as métricas são zero.