Эта страница переведена с помощью Cloud Translation API.

Устранение неполадок с назначением ставок в реальном времени

В этом руководстве описаны ресурсы по устранению неполадок RTB, которые позволяют программно получить доступ к показателям кампании с назначением ставок в реальном времени, которые также доступны с помощью инструмента RTB Breakout , который находится в пользовательском интерфейсе Авторизованных покупателей. К ним относятся bidders.filterSets , bidders.accounts.filterSets и все ресурсы, находящиеся под ними иерархически.

Используя показатели из ресурсов по устранению неполадок RTB, вы можете получить представление об упущенных возможностях для получения показов, что поможет вам оптимизировать кампанию с назначением ставок в реальном времени.

Изменения в структуре и стиле API

В ресурсы по устранению неполадок RTB внесено несколько изменений, позволяющих явно указать право собственности и доступ, обеспечить более детальный контроль над данными, возвращаемыми API, и лучше согласовать их с практикой проектирования Google API .

Ресурсы на уровне участников торгов и аккаунта

Ресурсы структурированы как по bidders так и bidders.accounts . Они позволяют вам указать, нацелен ли вызов API на участника аукциона (также известного как родительский аккаунт) и все связанные с ним дочерние аккаунты или на отдельные аккаунты Авторизованных покупателей. В контексте устранения неполадок с назначением ставок в реальном времени ресурсы, структурированные в bidders.filterSets , будут возвращать агрегированные показатели для данного участника назначения ставок и всех связанных с ним дочерних аккаунтов. Напротив, те, что находятся в bidders.accounts.filterSets , будут возвращать показатели только для указанного аккаунта, независимо от того, является ли он участником аукциона или дочерним аккаунтом.

Примечание. Аккаунты, которые делегируют свои ставки другому покупателю, не являются аккаунтами участников торгов и, следовательно, не имеют доступа к ресурсам уровня участников торгов. Кроме того, аккаунты, не участвующие в торгах, не могут получить доступ к ресурсам impressionMetrics , filteredBidResponses , bidResponseErrors и bidResponsesWithoutBids на уровне аккаунта.

Представление названий ресурсов в качестве уникальных идентификаторов

Имена ресурсов используются как уникальные идентификаторы, а не целые или строковые идентификаторы. При создании нового экземпляра данного типа ресурса теперь необходимо указать относительное имя ресурса, используя путь URI ресурса, за которым следует предпочтительный идентификатор ресурса. Ниже приведены примеры названий, соответствующих ресурсам по устранению неполадок RTB:

Ресурс	Пример имени
bidders.filterSets	участники торгов/12345678/filterSets/fset_1
bidders.accounts.filterSets	участники торгов/12345678/accounts/87654321/filterSets/fset_2

Примечание. Идентификатор ресурса, указанный для bidders в имени, должен совпадать с идентификатором аккаунта Авторизованных покупателей участника. Для accounts идентификатор ресурса должен быть идентификатором учетной записи либо участника торгов, либо дочерней учетной записи, управляемой им. Если вы не знаете, какие учетные записи Авторизованных покупателей связаны с вашей учетной записью Google, вы можете использовать методaccounts.list , чтобы найти их.

Наборы фильтров

Набор фильтров – это представление доступных параметров фильтрации. Его можно создать на уровне участника торгов или аккаунта. Он используется для фильтрации результатов списка ресурсов по устранению неполадок RTB, которые получают показатели для ваших кампаний с назначением ставок в реальном времени.

Фильтр, применяемый при получении метрик, представляет собой пересечение каждого фильтра в указанном наборе фильтров. Фильтры списков, например platforms , интерпретируются как объединение каждого элемента списка.

Наборы фильтров на уровне участника назначения ставок и аккаунта различны и доступны только на том уровне, на котором они были созданы, независимо от аккаунта, который использовался для их создания. Участники аукциона и дочерняя учетная запись совместно используют наборы фильтров, созданные на уровне учетной записи, тогда как только участник торгов может получить доступ к ресурсам на уровне участника торгов. В следующей таблице показано, как участники торгов и дочерние учетные записи могут получить доступ к ресурсам на любом уровне:

	bidders.filterSets	bidders.accounts.filterSets
Аккаунт участника торгов	Вызов API, влияющий только на наборы фильтров на уровне системы назначения ставок.	Вызов API, влияющий только на наборы фильтров на уровне учетной записи.
Детский аккаунт	Этот вызов API вернет ответ об ошибке.	Вызов API, влияющий только на наборы фильтров на уровне учетной записи.

Создать набор фильтров

При создании набора фильтров необходимо указать диапазон времени как relativeDateRange , absoluteDateRange или realtimeTimeRange . При получении метрик по умолчанию предоставляются все данные за весь диапазон времени. Если вы хотите получить разбивку временных рядов по временному диапазону, вы можете указать timeSeriesGranularity , чтобы указать HOURLY или DAILY интервалы.

Если вам требуется набор фильтров только на короткий период времени, вы можете установить для параметра запроса isTransient true . Это будет означать, что набор фильтров является временным, то есть он не будет сохраняться бесконечно. Наборы переходных фильтров будут доступны в течение как минимум одного часа после их создания, но в конечном итоге будут удалены. По умолчанию наборы фильтров не являются временными.

Пример на уровне участника торгов

Чтобы создать новый набор фильтров на уровне системы назначения ставок, отправьте запрос POST на URI ресурса bidders.filterSets , который имеет следующий формат:

https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets

Внимание! Наборы фильтров на уровне системы назначения ставок не поддерживают фильтрацию по идентификаторам объявлений или сделок. Если вы укажете эти фильтры при создании набора фильтров на уровне системы назначения ставок, вы получите ответ об ошибке.

Запрос

Ниже приведен пример запроса POST , который создает новый постоянный набор фильтров на уровне системы назначения ставок:

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"
}

Ответ

Если запрос успешен, сервер отвечает кодом состояния 200 OK. Тело ответа будет включать созданный ресурс набора фильтров, который будет идентичен набору фильтров, отправленному в запросе.

Пример на уровне аккаунта

Чтобы создать новый набор фильтров на уровне аккаунта, отправьте POST -запрос на URI ресурса bidders.accounts.filterSets , который имеет следующий формат:

https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets

Примечание. Идентификатор ресурса, указанный для accounts , может быть идентификатором любой учетной записи Авторизованных покупателей, доступной для учетной записи участника торгов, указанной в URI, включая саму учетную запись участника торгов.

Запрос

Вот пример запроса POST , который создает новый постоянный набор фильтров на уровне учетной записи:

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"
}

Ответ

Получить набор фильтров

Метод get может получить набор фильтров только на том уровне, на котором он был создан. Например, аккаунт участника торгов должен использовать bidders.accounts.filterSets.get для получения набора фильтров, созданного на уровне аккаунта, а не метод bidders.filterSets.get .

Уровень участника торгов

Вы можете получить набор фильтров на уровне системы назначения ставок, отправив HTTP-запрос GET на URI ресурса bidders.filterSets , который имеет следующий формат:

GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}

Запрос

Вот пример:

GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/bidder-fs

Ответ

Если запрос успешен, сервер отвечает кодом состояния HTTP 200 OK и полученным набором фильтров:

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

На уровне аккаунта

Вы можете получить набор фильтров на уровне аккаунта, отправив HTTP-запрос GET на URI ресурса bidders.accounts.filterSets , который имеет следующий формат:

GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}

Запрос

Вот пример:

GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/account-fs

Ответ

Если запрос успешен, сервер отвечает кодом состояния HTTP 200 OK и полученным набором фильтров:

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

Получение списка наборов фильтров

Метод list будет возвращать только наборы фильтров, доступные на том уровне, на котором он вызывается. Например, аккаунт участника торгов не увидит наборы фильтров, созданные для него с помощью bidders.accounts.filterSets.create при вызове bidders.filterSets.list .

Уровень участника торгов

Вы можете получить все наборы фильтров на уровне системы назначения ставок для данного участника, отправив HTTP-запрос GET на URI ресурса bidders.filtersets , который имеет следующий формат:

GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets

Запрос

Ниже приведен пример списка всех наборов фильтров на уровне системы назначения ставок для участника с идентификатором аккаунта 12345678:

GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets

Ответ

{
  "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"
    }
  ]
}

На уровне аккаунта

Вы можете получить все наборы фильтров на уровне учетной записи для определенной учетной записи, отправив HTTP-запрос GET на URI ресурса bidders.accounts.filtersets , который имеет следующий формат:

GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets

Запрос

Вот пример, в котором перечислены все наборы фильтров на уровне учетной записи для дочерней учетной записи с идентификатором учетной записи 87654321:

GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets

Ответ

{
  "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"
    }
  ]
}

Удаление набора фильтров

Вы можете использовать метод delete , чтобы удалить любые непереходные наборы фильтров, которые больше не нужны. Он может удалять только наборы фильтров, доступные на том уровне, на котором он вызывается; например, аккаунт участника торгов не может удалить набор фильтров, созданный с помощью bidders.accounts.filterSets.create с помощью bidders.filterSets.delete .

Уровень участника торгов

Вы можете удалить набор фильтров на уровне системы назначения ставок для определенной учетной записи, отправив HTTP-запрос DELETE на URI ресурса bidders.filtersets , который имеет следующий формат:

DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}

Запрос

Ниже приведен пример удаления набора фильтров на уровне системы назначения ставок:

DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/test-b-2

Ответ

В случае успеха тело запроса будет пустым. Указанный набор фильтров больше не будет доступен.

На уровне аккаунта

Вы можете удалить набор фильтров на уровне учетной записи для определенной учетной записи, отправив HTTP-запрос DELETE на URI ресурса bidders.accounts.filtersets , который имеет следующий формат:

DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}

Запрос

Ниже приведен пример удаления набора фильтров на уровне учетной записи:

DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/test-a-1

Ответ

В случае успеха тело запроса будет пустым. Указанный набор фильтров больше не будет доступен.

Получение показателей устранения неполадок RTB

Все ресурсы устранения неполадок RTB, используемые для получения метрик, работают аналогичным образом — у них есть единый метод для вывода списка метрик для набора фильтров, указанного через параметр пути filterSetName . Указанный набор фильтров будет определять, какие фильтры и настройки будут применяться при запросе метрик. Вызов этих ресурсов с уровня системы назначения ставок вернет агрегированные показатели из учетной записи участника назначения ставок и всех связанных дочерних учетных записей, тогда как вызов с уровня учетной записи вернет показатели только для отдельной учетной записи.

Показатели ставок

Ресурс bidMetrics используется для получения показателей, измеряемых количеством ставок. Например, вы можете использовать это, чтобы определить общее количество ставок за определенный период времени, а также то, сколько из них не было отфильтровано на аукционе, не выиграло показ и т. д. Как и все другие ресурсы по устранению неполадок RTB, используемые для сбора показателей, он имеет только метод list .

Получение списка показателей ставок на уровне системы назначения ставок

Вы можете составить список показателей ставок на уровне системы назначения ставок для определенного набора фильтров, отправив запрос HTTP GET на URI ресурса bidders.filtersets.bidMetrics , который имеет следующий формат:

GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}/bidMetrics

Запрос

Ниже приведен пример показателей ставок на уровне системы назначения ставок:

GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/bidder-fs/bidMetrics

Ответ

Если запрос успешен, сервер отвечает кодом состояния 200 OK и телом, содержащим строки показателей для указанных измерений и детализации.

{
  "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": {}
    }
  ]
}

Примечание. Любые поля, для которых установлено значение 0 для данной метрики, не будут отображаться в ответе. Пустые показатели billedImpressions и measurableImpressions выше указывают на то, что их значение и дисперсия равны 0.

Предупреждение. При любой разбивке данных в ответе ответ не будет включать строки, если они не содержат хотя бы один ненулевой показатель. Например, если указан timeSeriesGranularity , ответ не будет включать строки для любого timeInterval в течение указанного диапазона времени набора фильтров, где все метрики равны нулю.

Получение списка показателей ставок на уровне аккаунта

Вы можете перечислить показатели ставок на уровне аккаунта для определенного набора фильтров, отправив HTTP-запрос GET на URI ресурса bidders.accounts.filtersets.bidMetrics , который имеет следующий формат:

GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}/bidMetrics

Запрос

Ниже приведен пример показателей ставок на уровне аккаунта:

GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/account-fs/bidMetrics

Ответ

{
  "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": {}
    }
  ]
}