W tym przewodniku omawiamy zasoby dotyczące rozwiązywania problemów z określaniem stawek w czasie rzeczywistym (RTB), które umożliwiają automatyczny dostęp do danych kampanii z określaniem stawek w czasie rzeczywistym dostępnych w narzędziu Podział RTB w interfejsie Authorized Buyers. Obejmuje to bidders.filterSets
i bidders.accounts.filterSets
oraz wszystkie zasoby znajdujące się w hierarchii poniżej.
Korzystając z danych z zasobów dotyczących rozwiązywania problemów z określaniem stawek w czasie rzeczywistym, możesz uzyskać statystyki dotyczące wykorzystanych możliwości zdobywania wyświetleń i optymalizować kampanie z określaniem stawek w czasie rzeczywistym.
Dostosowania struktury i stylu interfejsu API
W zasobach dotyczących rozwiązywania problemów z RTB wprowadzono kilka zmian, które wyraźnie określają własność i dostęp, zapewniają bardziej szczegółową kontrolę nad danymi zwracanymi przez interfejs API i są lepiej dopasowane do metod projektowania interfejsów API Google.
Zasoby na poziomie licytującego i na poziomie konta
Zasoby znajdują się w grupie bidders
i bidders.accounts
. Dzięki nim możesz określić, czy wywołanie interfejsu API jest kierowane na licytującego (zwanego też kontem nadrzędnym) i wszystkie powiązane konta podrzędne, czy poszczególne konta Authorized Buyers. W kontekście rozwiązywania problemów z RTB zasoby w strukturze bidders.filterSets
zwracają dane zbiorcze dotyczące danego licytującego i wszystkich powiązanych kont podrzędnych. Z kolei konta w grupie bidders.accounts.filterSets
zwracają tylko dane z określonego konta niezależnie od tego, czy jest to konto licytującego, czy konto podrzędne.
Uwaga: konta, które przekazują ustalanie stawek innemu kupującemu, nie są kontami licytującego, więc nie mają dostępu do zasobów na poziomie licytującego. Poza tym konta nielicytujące nie mają dostępu do zasobów impressionMetrics
, filteredBidResponses
, bidResponseErrors
i bidResponsesWithoutBids
na poziomie konta.
Wprowadzamy nazwy zasobów jako unikalne identyfikatory
Nazwy zasobów są używane jako unikalne identyfikatory, a nie jako identyfikatory w postaci liczb całkowitych czy ciągów znaków. Podczas tworzenia nowej instancji zasobu danego typu musisz teraz określić względną nazwę zasobu, podając ścieżkę identyfikatora URI zasobu, po której następuje preferowany identyfikator zasobu. Oto przykłady nazw zasobów dotyczących rozwiązywania problemów z RTB:
Zasób | Przykład nazwy |
---|---|
bidders.filterSets | bidders/12345678/filterSets/fset_1 |
bidders.accounts.filterSets | bidders/12345678/accounts/87654321/filterSets/fset_2 |
Uwaga: identyfikator zasobu podany w nazwie elementu bidders
musi być identyfikatorem konta licytującego z Authorized Buyers. W przypadku accounts
identyfikator zasobu musi być identyfikatorem konta licytującego lub zarządzanego przez niego konta podrzędnego. Jeśli nie wiesz, które konta Authorized Buyers są powiązane z Twoim kontem Google, możesz je znaleźć, korzystając z metody accounts.list.
Zestawy filtrów
Zestaw filtrów reprezentuje dostępne opcje filtrowania i można go utworzyć na poziomie licytującego lub konta. Służy do filtrowania wyników na liście zasobów do rozwiązywania problemów z RTB, które pobierają wskaźniki z kampanii z określaniem stawek w czasie rzeczywistym.
Filtr zastosowany podczas pobierania danych stanowi część wspólną wszystkich filtrów w określonym zestawie filtrów. Filtry list, takie jak platforms
, są interpretowane jako połączenie każdego elementu na liście.
Zestawy filtrów na poziomie konta i licytującego różnią się od siebie i są dostępne tylko z poziomu, na którym zostały utworzone – niezależnie od konta użytego do ich utworzenia. Zestawy filtrów udziału licytującego i konta podrzędnego utworzone na poziomie konta, podczas gdy tylko licytujący ma dostęp do zasobów na poziomie licytującego. W tabeli poniżej znajdziesz podsumowanie dostępu do zasobów na poszczególnych poziomach systemu licytującego i kont podrzędnych:
bidders.filterSets | bidders.accounts.filterSets | |
---|---|---|
Konto licytującego | Wywołanie interfejsu API mające wpływ tylko na zestawy filtrów na poziomie licytującego. | Wywołanie interfejsu API mające wpływ tylko na zestawy filtrów na poziomie konta. |
Konto dziecka | To wywołanie interfejsu API zwróci odpowiedź o błędzie. | Wywołanie interfejsu API mające wpływ tylko na zestawy filtrów na poziomie konta. |
Tworzenie zestawu filtrów
Podczas tworzenia zestawu filtrów musisz podać zakres czasu jako relativeDateRange
, absoluteDateRange
lub realtimeTimeRange
. Podczas pobierania wskaźników domyślnym działaniem jest przesłanie wszystkich danych z całego zakresu czasu. Jeśli chcesz otrzymać podział ciągu czasowego na zakres czasowy, możesz określić timeSeriesGranularity
, aby wskazać przedziały HOURLY
lub DAILY
.
Jeśli potrzebujesz zestawu filtrów tylko przez krótki czas, możesz ustawić parametr zapytania isTransient
na true
. Sygnalizuje to, że zestaw filtrów jest tymczasowy, czyli nie będzie pozostawał trwały. Zestawy filtrów przejściowych będą dostępne przez co najmniej godzinę po utworzeniu, ale w końcu zostaną usunięte. Domyślnie zestawy filtrów nie są przejściowe.
Przykład na poziomie licytującego
Aby utworzyć nowy zestaw filtrów na poziomie licytującego, wyślij żądanie POST
do identyfikatora URI zasobu bidders.filterSets
w takim formacie:
https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets
Ostrzeżenie: zestawów filtrów na poziomie licytującego nie można filtrować według identyfikatorów kreacji ani umów. Jeśli określisz te filtry podczas tworzenia zestawu filtrów na poziomie licytującego, wyświetli się komunikat o błędzie.
Wyślij prośbęOto przykład żądania POST
, które tworzy nowy zestaw filtrów na poziomie stałego licytującego:
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" }Odpowiedź
Jeśli żądanie zostanie zrealizowane, serwer w odpowiedzi wysyła kod stanu 200 OK. Treść odpowiedzi będzie zawierać zasób utworzonego zestawu filtrów, który będzie identyczny z zestawem filtrów przesłanym w żądaniu.
Przykład na poziomie konta
Aby utworzyć nowy zestaw filtrów na poziomie konta, wyślij żądanie POST
do identyfikatora URI zasobu bidders.accounts.filterSets
w następującym formacie:
https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets
Uwaga: identyfikatorem zasobu określonym w polu accounts
może być identyfikator dowolnego konta Authorized Buyers dostępnego dla konta licytującego podanego w identyfikatorze URI, w tym konta licytującego.
Oto przykład żądania POST
, które tworzy nowy trwały zestaw filtrów na poziomie konta:
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" }Odpowiedź
Jeśli żądanie zostanie zrealizowane, serwer w odpowiedzi wysyła kod stanu 200 OK. Treść odpowiedzi będzie zawierać zasób utworzonego zestawu filtrów, który będzie identyczny z zestawem filtrów przesłanym w żądaniu.
Pobieranie zestawu filtrów
Metoda get może pobierać zestaw filtrów tylko na tym samym poziomie, na którym został utworzony. Na przykład konto licytującego powinno używać polecenia bidders.accounts.filterSets.get
do pobierania zestawu filtrów utworzonego na poziomie konta, a nie metody bidders.filterSets.get
.
Na poziomie licytującego
Aby pobrać zestaw filtra na poziomie licytującego, wyślij żądanie HTTP GET do identyfikatora URI zasobu bidders.filterSets
w takim formacie:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}Prośba
Oto przykład:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/bidder-fsOdpowiedź
Jeśli żądanie zostanie zrealizowane, serwer w odpowiedzi prześle kod stanu HTTP 200 OK
i pobrany zestaw filtrów:
{ "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" }
Poziom konta
Aby pobrać zestaw filtrów na poziomie konta, wyślij żądanie HTTP GET
do identyfikatora URI zasobu bidders.accounts.filterSets
w takim formacie:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}Prośba
Oto przykład:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/account-fsOdpowiedź
Jeśli żądanie zostanie zrealizowane, serwer w odpowiedzi prześle kod stanu HTTP 200 OK
i pobrany zestaw filtrów:
{ "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" }
Wyświetlenie listy zestawów filtrów
Metoda listy zwraca tylko zestawy filtrów dostępne z poziomu wywoływanego przez użytkownika.
Na przykład podczas wywoływania metody bidders.filterSets.list
konto licytującego nie zobaczy zestawów filtrów utworzonych samodzielnie za pomocą funkcji bidders.accounts.filterSets.create
.
Na poziomie licytującego
Aby pobrać wszystkie zestawy filtrów na poziomie licytującego dotyczące danego licytującego, wyślij żądanie HTTP GET
do identyfikatora URI zasobu bidders.filtersets
w takim formacie:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSetsProśba
Oto przykład z listą wszystkich zestawów filtrów na poziomie licytującego o identyfikatorze konta 12345678:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSetsOdpowiedź
{ "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" } ] }
Poziom konta
Możesz pobrać wszystkie zestawy filtrów na poziomie konta dla danego konta, wysyłając żądanie HTTP GET
do identyfikatora URI zasobu bidders.accounts.filtersets
w następującym formacie:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSetsProśba
Oto przykład z listą wszystkich zestawów filtrów na poziomie konta powiązanego z kontem podrzędnym o identyfikatorze 87654321:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSetsOdpowiedź
{ "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" } ] }
Usuwanie zestawu filtrów
Za pomocą metody delete
możesz usunąć wszystkie trwałe zestawy filtrów, które nie są już potrzebne. Może usuwać tylko zestawy filtrów dostępne z poziomu, które jest wywoływane. Na przykład konto licytującego nie może usunąć zestawu filtrów utworzonego za pomocą funkcji bidders.accounts.filterSets.create
za pomocą właściwości bidders.filterSets.delete
.
Na poziomie licytującego
Zestaw filtrów na poziomie licytującego możesz usunąć w przypadku danego konta, wysyłając żądanie HTTP DELETE
do identyfikatora URI zasobu bidders.filtersets
w takim formacie:
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}Prośba
Oto przykład usuwania zestawu filtrów na poziomie licytującego:
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/test-b-2Odpowiedź
Jeśli operacja się uda, treść żądania będzie pusta. Podany zestaw filtrów nie będzie już dostępny.
Poziom konta
Możesz usunąć zestaw filtrów na poziomie konta dla danego konta, wysyłając żądanie HTTP DELETE
do identyfikatora URI zasobu bidders.accounts.filtersets
w formacie:
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}Prośba
Oto przykład usuwania zestawu filtrów na poziomie konta:
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/test-a-1Odpowiedź
Jeśli operacja się uda, treść żądania będzie pusta. Podany zestaw filtrów nie będzie już dostępny.
Pobieranie danych dotyczących rozwiązywania problemów z RTB
Wszystkie zasoby do rozwiązywania problemów z RTB używane do odbierania wskaźników działają w podobny sposób – korzystają z jednej metody wyświetlania wskaźników z zestawu filtrów określonym za pomocą parametru ścieżki filterSetName
. Określony zestaw filtrów określa, które filtry i ustawienia będą stosowane podczas wysyłania zapytań dotyczących wskaźników. Wywołanie tych zasobów z poziomu licytującego spowoduje zwrócenie zagregowanych danych z konta licytującego i wszystkich powiązanych z nim kont podrzędnych, natomiast wywołanie z poziomu konta zwróci tylko dane dotyczące konta indywidualnego.
Dane o stawkach
Zasób bidMetrics
służy do pobierania wskaźników mierzonych w liczbie stawek. Możesz na przykład określić łączną liczbę stawek w danym przedziale czasu oraz liczbę z nich, które nie zostały odfiltrowane z aukcji, wygrały wyświetlenie itp. Podobnie jak wszystkie inne zasoby do rozwiązywania problemów z określaniem stawek w czasie rzeczywistym używane do zbierania danych, dostępna jest tylko metoda list
.
Wyświetlanie listy danych o stawkach na poziomie licytującego
Możesz wyświetlić dane o stawce na poziomie licytującego w przypadku danego zestawu filtrów, wysyłając żądanie HTTP GET
do identyfikatora URI zasobu bidders.filtersets.bidMetrics
w takim formacie:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}/bidMetricsProśba
Oto przykład danych o stawce na poziomie licytującego:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/bidder-fs/bidMetricsOdpowiedź
Jeśli żądanie się powiedzie, serwer w odpowiedzi wysyła kod stanu 200 OK
oraz treść zawierającą wiersze danych o określonych wymiarach i szczegółach.
{ "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": {} } ] }
Uwaga: pola z wartością 0 dla danego wskaźnika nie pojawią się w odpowiedzi.
Powyższe puste dane billedImpressions
i measurableImpressions
wskazują, że zarówno wartość, jak i wariancja dla nich mają wartość 0.
Ostrzeżenie: w przypadku podziału danych w odpowiedzi odpowiedź nie będzie zawierać wierszy, jeśli nie zawierają one co najmniej 1 wskaźnika niezerowego. Jeśli na przykład określisz właściwość timeSeriesGranularity
, odpowiedź nie będzie zawierać wierszy dla żadnej wartości timeInterval
w zakresie czasowym zestawu filtrów, w którym wszystkie dane mają wartość 0.
Wyświetlenie listy danych o stawkach na poziomie konta
Możesz wyświetlić dane o stawkach na poziomie konta dla danego zestawu filtrów, wysyłając żądanie HTTP GET
do identyfikatora URI zasobu bidders.accounts.filtersets.bidMetrics
w takim formacie:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}/bidMetricsProśba
Oto przykład danych o stawkach na poziomie konta:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/account-fs/bidMetricsOdpowiedź
Jeśli żądanie się powiedzie, serwer w odpowiedzi wysyła kod stanu 200 OK
oraz treść zawierającą wiersze danych o określonych wymiarach i szczegółach.
{ "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": {} } ] }
Uwaga: pola z wartością 0 dla danego wskaźnika nie pojawią się w odpowiedzi. Powyższe puste wskaźniki billedImpressions
i measurableImpressions
wskazują, że zarówno wartość, jak i wariancja dla nich mają wartość 0.
Ostrzeżenie: w przypadku podziału danych w odpowiedzi odpowiedź nie będzie zawierać wierszy, jeśli nie zawierają one co najmniej 1 wskaźnika niezerowego. Jeśli na przykład określisz właściwość timeSeriesGranularity
, odpowiedź nie będzie zawierać wierszy dla żadnej wartości timeInterval
w zakresie czasowym zestawu filtrów, w którym wszystkie dane mają wartość 0.