Interfejs Ad Manager API udostępnia zbiory danych, najczęściej w Listmetodach. Kolekcje mogą mieć dowolny rozmiar i są dzielone na strony w odpowiedziach API.
Podstawowe informacje
W wiadomościach z żądaniami dotyczącymi kolekcji można zdefiniować opcjonalne pole pageSize z liczbą całkowitą, aby określić maksymalną liczbę wyników do zwrócenia.
Ustaw parametr pageSize na liczbę dodatnią mniejszą niż 1000. Jeśli nie ustawisz żadnej wartości lub ustawisz parametr na zero, interfejs API użyje wartości domyślnej 50. Jeśli ustawisz parametr na wartość ujemną, interfejs API zwróci błąd INVALID_ARGUMENT.
W dokumentacji referencyjnej zasobów, np. AdBreaks, znajdziesz wartość pageSize dla konkretnego zasobu.
Interfejs API może zwrócić mniej wyników niż żądana liczba (w tym 0 wyników), nawet jeśli nie jest to koniec kolekcji. Sprawdź, czy w kolekcji są dodatkowe wyniki, korzystając z pola nextPageToken.
Wiadomości odpowiedzi dotyczące kolekcji definiują pole ciągu znaków nextPageToken, którego można użyć do pobrania następnej strony. Gdy osiągnięty zostanie koniec kolekcji, pole nextPageToken będzie puste. To jedyny sposób, aby sprawdzić, czy dotarłeś(-aś) do końca kolekcji.
Wiadomości z prośbą o kolekcje definiują opcjonalne pole tekstowe pageToken, które umożliwia przejście do następnej strony w kolekcji. Zmiany w parametrze pageSize w prośbie o kolejne strony są dozwolone. Wszystkie pozostałe argumenty muszą być takie same. Jeśli którykolwiek z argumentów jest inny, interfejs API zwraca błąd INVALID_ARGUMENT.
Przykład
cURL
Pierwotne żądanie
curl https://admanager.googleapis.com/v1/networks/123456/adUnits?pageSize=500
{
"adUnits": [ ... ],
"nextPageToken": "eCGwAcs6hUerggzd2DGv"
}
Żądanie następnej strony
curl https://admanager.googleapis.com/v1/networks/123456/adUnits?pageSize=500&pageToken=eCGwAcs6hUerggzd2DGv
{
"adUnits": [ ... ]
}
Całkowity rozmiar
Wiadomości z odpowiedzią dotyczące kolekcji zawierają liczbę całkowitą totalSize, która reprezentuje łączną liczbę elementów po zastosowaniu filtrowania. To pole jest wypełniane tylko wtedy, gdy jest wymagane w masce pola.
GET https://admanager.googleapis.com/v1/networks/123456/adUnits?$fields=adUnits,nextPageToken,totalSize
Wyniki zamówienia
W wiadomościach z prośbą o kolekcje zdefiniuj pole tekstowe orderBy, aby określić kolejność sortowania.
Wartości powinny być listą pól rozdzielonych przecinkami. Przykład: foo,bar. Domyślna kolejność sortowania to rosnąca. Aby określić kolejność malejącą dla pola, dodaj sufiks desc, np. foo desc, bar. Nadmiarowe znaki spacji w składni są ignorowane. Wartości orderBy – foo, bar desc, foo , bar desc i foo,bar desc są równoważne. Pola podrzędne są określane za pomocą znaku ., np. foo.bar lub address.street.
Sortowanie jest obsługiwane tylko w przypadku pól prostych.
Pomiń wyniki
Metody operacji podzielonej na strony definiują pole liczby całkowitej skip, aby pominąć wyniki. Wartość pomijania odnosi się do liczby poszczególnych zasobów do pominięcia, a nie do liczby stron.
Na przykład:
Żądanie bez tokena strony i wartości pominięcia równej 30 zwraca jedną stronę wyników zaczynającą się od 31 wyniku.
Żądanie z tokenem strony odpowiadającym 51 wynikowi (ponieważ pierwsze 50 wyników zostało zwróconych na pierwszej stronie) i wartością pominięcia równą 30 zwraca jedną stronę wyników zaczynającą się od 81 wyniku.
Jeśli podana wartość pomijania spowoduje przesunięcie kursora poza koniec kolekcji wyników, odpowiedź będzie 200 OK z pustym zbiorem wyników bez nextPageToken.