Interfejs Ad Manager API udostępnia zbiory danych, najczęściej w postaci Listmetod. Kolekcje mogą mieć dowolny rozmiar i są dzielone na strony w odpowiedziach interfejsu API.
Podstawowe informacje
Żądania dotyczące kolekcji definiują opcjonalne pole liczb całkowitych pageSize, w którym można 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 0, interfejs API użyje wartości domyślnej 50. Jeśli ustawisz parametr na wartość ujemną, interfejs API zwróci błąd INVALID_ARGUMENT.
Wartość pageSize dla konkretnego zasobu znajdziesz w dokumentacji referencyjnej zasobu, np. AdBreaks.
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. Obecność pola nextPageToken wskazuje, czy w kolekcji są dodatkowe wyniki.
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 zbiór się zakończy, pole nextPageToken będzie puste. To jedyny sposób, aby określić, czy dotarłeś/doszłaś do końca kolekcji.
Wiadomości z prośbą o kolekcje definiują opcjonalne pole ciągu znaków pageToken, aby przejść do następnej strony kolekcji. Zmiany w parametry pageSize w żądaniu dotyczącego kolejnych stron są dozwolone. Wszystkie inne argumenty muszą być takie same. Jeśli którykolwiek z nich jest inny, interfejs API zwraca błąd INVALID_ARGUMENT.
Przykład
cURL
Wstępna prośba
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 odpowiedzi dotyczące kolekcji zawierają liczbę całkowitą totalSize, która odpowiada łącznej liczbie 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
Zamawianie wyników
W wiadomościach z prośbami o kolekcje definiuje się pole ciągu znaków orderBy, aby określić kolejność sortowania.
Wartości powinny być listą pól rozdzielonych przecinkami. Na przykład: foo,bar. Domyślna kolejność sortowania to rosnąco. Aby określić pole w kolejności malejącej, dodaj sufiks desc, np. foo desc, bar. Zbędne spacje 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ą oznaczane za pomocą znaku ., np. foo.bar lub address.street.
Sortowanie jest obsługiwane tylko w przypadku pól prymitywnych.
Pomijanie wyników
Metody operacji po stronie serwera definiują pole całkowitoliczbowe skip, aby pominąć wyniki. Wartość skip odnosi się do liczby poszczególnych zasobów, które mają zostać pominięte, a nie do liczby stron.
Na przykład:
Żądanie bez tokenu strony i z wartością pominięcia 30 zwraca jedną stronę wyników, zaczynając od 31. wyniku.
Zapytanie z tokenem strony odpowiadającym 51. wynikowi (ponieważ pierwsze 50 wyników zostało zwróconych na pierwszej stronie) i wartością pominięcia 30 zwraca jedną stronę wyników, zaczynając od 81. wyniku.
Jeśli podana wartość pominięcia powoduje, że kursor przesuwa się poza koniec zbioru wyników, odpowiedzią jest 200 OK z pustym zbiorem wyników bez wartości nextPageToken.