In diesem Leitfaden werden Ressourcen zur Fehlerbehebung bei Echtzeitgeboten behandelt, mit denen Sie programmatisch auf Kampagnenmesswerte für Echtzeitgebote zugreifen können, die auch über das Tool Aufschlüsselung von Echtzeitgeboten auf der Authorized Buyers-Benutzeroberfläche verfügbar sind. Dazu gehören bidders.filterSets
, bidders.accounts.filterSets
und alle hierarchisch untergeordneten Ressourcen.
Mithilfe der Messwerte aus den Ressourcen zur Fehlerbehebung bei Echtzeitgeboten erhalten Sie Einblicke in verpasste Chancen, Impressionen zu erzielen, und können so Ihre Kampagne mit Echtzeitgeboten optimieren.
Anpassungen an API-Struktur und -Stil
In den Ressourcen zur Fehlerbehebung bei Echtzeitgeboten werden einige Änderungen eingeführt, um die Inhaberschaft und den Zugriff explizit anzugeben, eine detailliertere Kontrolle über die von der API zurückgegebenen Daten zu ermöglichen und besser auf die Designpraktiken der Google API abzustimmen.
Ressourcen auf Bieter- und Kontoebene
Ressourcen sind sowohl nach bidders
als auch nach bidders.accounts
strukturiert. Damit können Sie angeben, ob ein API-Aufruf auf einen Bieter (auch als übergeordnetes Konto bezeichnet) und alle zugehörigen untergeordneten Konten oder einzelne Authorized Buyers-Konten ausgerichtet werden soll. Im Rahmen der Fehlerbehebung bei Echtzeitgeboten geben Ressourcen, die unter bidders.filterSets
strukturiert sind, zusammengefasste Messwerte für den angegebenen Bieter und alle zugehörigen untergeordneten Konten zurück. Im Gegensatz dazu geben Werte unter bidders.accounts.filterSets
nur Messwerte für das angegebene Konto zurück, unabhängig davon, ob es sich um ein Bieter- oder ein untergeordnetes Konto handelt.
Hinweis: Konten, die ihre Gebote an einen anderen Käufer delegieren, sind keine Bieterkonten und können daher nicht auf Ressourcen auf Bieterebene zugreifen. Darüber hinaus können Konten ohne Bieter nicht auf Ressourcen vom Typ impressionMetrics
, filteredBidResponses
, bidResponseErrors
und bidResponsesWithoutBids
auf Kontoebene zugreifen.
Einführung von Ressourcennamen als eindeutige Kennzeichnung
Ressourcennamen werden als eindeutige Kennungen statt als Ganzzahl- oder String-IDs verwendet. Wenn Sie eine neue Instanz eines bestimmten Ressourcentyps erstellen, müssen Sie jetzt einen relativen Ressourcennamen unter Verwendung des URI-Pfads der Ressource gefolgt von der bevorzugten Ressourcen-ID angeben. Im Folgenden finden Sie Beispiele für Namen, die für Ressourcen zur Fehlerbehebung bei EZG relevant sind:
Ressource | Namensbeispiel |
---|---|
bidders.filterSets | bidders/12345678/filterSets/fset_1 |
bidders.accounts.filterSets | bidders/12345678/accounts/87654321/filterSets/fset_2 |
Hinweis: Die Ressourcen-ID, die im Namen für bidders
angegeben wird, muss die Authorized Buyers-Konto-ID eines Bieters sein. Für accounts
muss die Ressourcen-ID die Konto-ID des Bieters oder eines untergeordneten Kontos sein, das von ihm verwaltet wird. Wenn Sie nicht wissen, welche Authorized Buyers-Konten mit Ihrem Google-Konto verknüpft sind, können Sie sie mithilfe der Methode accounts.list finden.
Filterkombinationen
Eine Filtergruppe ist eine Darstellung der verfügbaren Filteroptionen und kann auf Bieter- oder Kontoebene erstellt werden. Damit können die Listenergebnisse von Ressourcen zur Fehlerbehebung bei Echtzeitgeboten gefiltert werden, die Messwerte für Ihre Kampagnen mit Echtzeitgeboten abrufen.
Der beim Abrufen von Messwerten angewendete Filter ist die Schnittmenge aller Filter in der angegebenen Filtergruppe. Listenfilter wie platforms
werden als Zusammenführung aller Elemente in der Liste interpretiert.
Filtergruppen auf Bieter- und Kontoebene sind unterschiedlich und können nur auf der Ebene aufgerufen werden, auf der sie erstellt wurden – unabhängig davon, über welches Konto sie erstellt wurden. Freigabefilter für Bieter und untergeordnete Konten werden auf Kontoebene erstellt, während nur ein Bieter auf Ressourcen auf Bieterebene zugreifen kann. In der folgenden Tabelle wird zusammengefasst, wie Bieter und untergeordnete Konten auf Ressourcen auf beiden Ebenen zugreifen können:
bidders.filterSets | bidders.accounts.filterSets | |
---|---|---|
Bieterkonto | Ein API-Aufruf, der sich nur auf Filtergruppen auf Bieterebene auswirkt. | Ein API-Aufruf, der sich nur auf Filtergruppen auf Kontoebene auswirkt. |
Kinderkonto | Dieser API-Aufruf gibt eine Fehlerantwort zurück. | Ein API-Aufruf, der sich nur auf Filtergruppen auf Kontoebene auswirkt. |
Filtergruppe erstellen
Beim Erstellen einer Filtergruppe müssen Sie einen Zeitraum als relativeDateRange
, absoluteDateRange
oder realtimeTimeRange
angeben. Beim Abrufen von Messwerten werden standardmäßig alle Daten für den gesamten Zeitraum bereitgestellt. Wenn Sie eine Zeitreihenaufschlüsselung für den Zeitraum erhalten möchten, können Sie timeSeriesGranularity
angeben, um HOURLY
- oder DAILY
-Intervalle anzugeben.
Wenn Sie einen Filter nur für kurze Zeit benötigen, können Sie den Abfrageparameter isTransient
auf true
setzen. Dies zeigt an, dass die Filtergruppe temporär ist, d. h. sie nicht auf unbestimmte Zeit gespeichert wird. Transiente Filtersätze sind nach ihrer Erstellung mindestens eine Stunde lang verfügbar, werden aber irgendwann gelöscht. Standardmäßig sind Filtersätze nicht temporär.
Beispiel auf Bieterebene
Wenn Sie eine neue Filtergruppe auf Bieterebene erstellen möchten, senden Sie eine POST
-Anfrage an den Ressourcen-URI bidders.filterSets
mit folgendem Format:
https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets
Warnung: Bei Filtersätzen auf Bieterebene kann nicht nach Creative- oder Deal-IDs gefiltert werden. Wenn Sie diese Filter beim Erstellen einer Filtergruppe auf Bieterebene angeben, erhalten Sie eine Fehlermeldung.
AnfrageHier ist ein Beispiel für eine POST
-Anfrage, mit der eine neue Filtergruppe auf Bieterebene erstellt wird:
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" }Antwort
Wenn die Anfrage erfolgreich ist, antwortet der Server mit dem Statuscode „200 OK“. Der Antworttext enthält die erstellte Filtersatzressource, die mit der in der Anfrage eingereichten Filtergruppe identisch ist.
Beispiel auf Kontoebene
Zum Erstellen einer neuen Filtergruppe auf Kontoebene senden Sie eine POST
-Anfrage an den Ressourcen-URI bidders.accounts.filterSets
mit folgendem Format:
https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets
Hinweis: Die für accounts
angegebene Ressourcen-ID kann die Konto-ID eines beliebigen Authorized Buyers-Kontos sein, auf das das im URI angegebene Bieterkonto zugreifen kann, einschließlich des Bieterkontos selbst.
Hier ist ein Beispiel für eine POST
-Anfrage, mit der eine neue nicht vorübergehende Filtergruppe auf Kontoebene erstellt wird:
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" }Antwort
Wenn die Anfrage erfolgreich ist, antwortet der Server mit dem Statuscode „200 OK“. Der Antworttext enthält die erstellte Filtersatzressource, die mit der in der Anfrage gesendeten Filtergruppe identisch ist.
Filtersatz abrufen
Mit der get-Methode kann nur ein Filtersatz auf derselben Ebene abgerufen werden, auf der er erstellt wurde. Beispielsweise sollte ein Bieterkonto bidders.accounts.filterSets.get
zum Abrufen einer Filtergruppe verwenden, die auf Kontoebene erstellt wurde, und nicht mit der Methode bidders.filterSets.get
.
Bieterebene
Sie können einen Filtersatz auf Bieterebene abrufen, indem Sie eine HTTP-GET-Anfrage an den Ressourcen-URI bidders.filterSets
mit folgendem Format senden:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}Anfrage
Beispiel:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/bidder-fsAntwort
Wenn die Anfrage erfolgreich ist, antwortet der Server mit dem HTTP-Statuscode 200 OK
und dem abgerufenen Filtersatz:
{ "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" }
Kontoebene
Sie können einen Filtersatz auf Kontoebene abrufen, indem Sie eine HTTP-GET
-Anfrage an den URI der Ressource bidders.accounts.filterSets
mit folgendem Format senden:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}Anfrage
Beispiel:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/account-fsAntwort
Wenn die Anfrage erfolgreich ist, antwortet der Server mit dem HTTP-Statuscode 200 OK
und dem abgerufenen Filtersatz:
{ "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" }
Filtergruppen auflisten
Die list-Methode gibt nur Filtersätze zurück, auf die von der aufgerufenen Ebene aus zugegriffen werden kann.
Ein Bieterkonto sieht beispielsweise keine Filtersätze, die über bidders.accounts.filterSets.create
für sich selbst erstellt wurden, wenn bidders.filterSets.list
aufgerufen wird.
Bieterebene
Sie können alle Filtersätze auf Bieterebene für einen bestimmten Bieter abrufen. Senden Sie dazu eine HTTP-GET
-Anfrage an den URI der Ressource bidders.filtersets
im folgenden Format:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSetsAnfrage
Hier sehen Sie ein Beispiel, das alle Filtersätze auf Bieterebene für einen Bieter mit der Konto-ID 12345678 auflistet:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSetsAntwort
{ "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" } ] }
Kontoebene
Sie können alle Filtersätze auf Kontoebene für ein bestimmtes Konto abrufen. Senden Sie dazu eine HTTP-GET
-Anfrage an den bidders.accounts.filtersets
-Ressourcen-URI im folgenden Format:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSetsAnfrage
Hier ein Beispiel, das alle Filtergruppen auf Kontoebene für ein untergeordnetes Konto mit der Konto-ID 87654321 auflistet:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSetsAntwort
{ "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" } ] }
Filtergruppe löschen
Mit der Methode delete
können Sie alle nicht transienten Filtersätze entfernen, die nicht mehr benötigt werden. Sie können nur Filtersätze entfernen, auf die von der aufgerufenen Ebene aus zugegriffen werden kann. Beispielsweise kann ein Bieterkonto keine Filtergruppe löschen, die mit bidders.accounts.filterSets.create
und bidders.filterSets.delete
erstellt wurde.
Bieterebene
Sie können einen Filter auf Bieterebene für ein bestimmtes Konto löschen. Senden Sie dazu eine HTTP-DELETE
-Anfrage an den URI der Ressource bidders.filtersets
im folgenden Format:
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}Anfrage
Hier sehen Sie ein Beispiel, wie eine Filtergruppe auf Bieterebene gelöscht wird:
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/test-b-2Antwort
Bei Erfolg ist der Anfragetext leer. Auf die angegebene Filtergruppe kann nicht mehr zugegriffen werden.
Kontoebene
Sie können eine Filtergruppe auf Kontoebene für ein bestimmtes Konto löschen. Senden Sie dazu eine HTTP-DELETE
-Anfrage an den Ressourcen-URI bidders.accounts.filtersets
im folgenden Format:
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}Anfrage
Hier sehen Sie ein Beispiel für das Löschen einer Filtergruppe auf Kontoebene:
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/test-a-1Antwort
Bei Erfolg ist der Anfragetext leer. Auf die angegebene Filtergruppe kann nicht mehr zugegriffen werden.
Messwerte zur Fehlerbehebung bei Echtzeitgeboten abrufen
Alle RTB-Ressourcen zur Fehlerbehebung, die zum Empfangen von Messwerten verwendet werden, funktionieren auf ähnliche Weise. Sie haben nur eine Methode, um Messwerte für die Filtergruppe aufzulisten, die durch einen filterSetName
-Pfadparameter angegeben wird. Die angegebene Filtergruppe bestimmt, welche Filter und Einstellungen bei der Abfrage der Messwerte angewendet werden. Wenn diese Ressourcen auf der Bieterebene aufgerufen werden, werden zusammengefasste Messwerte aus dem Bieterkonto und allen zugehörigen untergeordneten Konten zurückgegeben. Bei einem Aufruf auf Kontoebene werden hingegen nur Messwerte für ein einzelnes Konto zurückgegeben.
Gebotsmesswerte
Die Ressource bidMetrics
wird zum Abrufen von Messwerten verwendet, die in der Anzahl der Gebote gemessen werden. So lässt sich beispielsweise die Gesamtzahl Ihrer Gebote in einem bestimmten Zeitraum ermitteln und feststellen, wie viele davon nicht aus der Auktion herausgefiltert wurden, eine Impression gewonnen haben usw. Wie alle anderen Ressourcen zur Fehlerbehebung bei Echtzeitgeboten, die zum Erfassen von Messwerten verwendet werden, gibt es auch hier nur die Methode list
.
Gebotsmesswerte auf Bieterebene auflisten
Sie können Gebotsmesswerte auf Bieterebene für einen bestimmten Filtersatz auflisten, indem Sie eine HTTP-GET
-Anfrage an den URI der Ressource bidders.filtersets.bidMetrics
im folgenden Format senden:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}/bidMetricsAnfrage
Hier ist ein Beispiel für einen Eintrag von Gebotsmesswerten auf Bieterebene:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/bidder-fs/bidMetricsAntwort
Wenn die Anfrage erfolgreich ist, antwortet der Server mit dem Statuscode 200 OK
und einem Textkörper, der Zeilen mit Messwerten für die angegebenen Dimensionen und den Detaillierungsgrad enthält.
{ "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": {} } ] }
Hinweis: Felder, die für einen bestimmten Messwert auf 0 gesetzt sind, werden nicht in der Antwort angezeigt.
Die leeren Messwerte billedImpressions
und measurableImpressions
oben zeigen an, dass sowohl der Wert als auch die Varianz für diese Werte auf 0 gesetzt sind.
Warnung: Bei einer Datenaufschlüsselung in der Antwort enthält die Antwort keine Zeilen, wenn sie nicht mindestens einen Messwert ungleich null enthalten. Wenn beispielsweise ein timeSeriesGranularity
angegeben wird, enthält die Antwort im angegebenen Zeitraum der Filtergruppe keine Zeilen für timeInterval
, in denen alle Messwerte null sind.
Gebotsmesswerte auf Kontoebene auflisten
Sie können Gebotsmesswerte auf Kontoebene für einen bestimmten Filtersatz auflisten, indem Sie eine HTTP-GET
-Anfrage an den URI der Ressource bidders.accounts.filtersets.bidMetrics
im folgenden Format senden:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}/bidMetricsAnfrage
Hier sehen Sie ein Beispiel für Gebotsmesswerte auf Kontoebene:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/account-fs/bidMetricsAntwort
Wenn die Anfrage erfolgreich ist, antwortet der Server mit dem Statuscode 200 OK
und einem Textkörper, der Zeilen mit Messwerten für die angegebenen Dimensionen und den Detaillierungsgrad enthält.
{ "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": {} } ] }
Hinweis: Felder, die für einen bestimmten Messwert auf 0 gesetzt sind, werden nicht in der Antwort angezeigt. Die leeren obigen Messwerte billedImpressions
und measurableImpressions
zeigen an, dass sowohl der Wert als auch die Varianz dafür auf 0 festgelegt sind.
Warnung: Bei einer Datenaufschlüsselung in der Antwort enthält die Antwort keine Zeilen, wenn sie nicht mindestens einen Messwert ungleich null enthalten. Wenn beispielsweise ein timeSeriesGranularity
angegeben wird, enthält die Antwort im angegebenen Zeitraum der Filtergruppe keine Zeilen für timeInterval
, in denen alle Messwerte null sind.