Die Ad Manager API stellt Datensammlungen bereit, am häufigsten in List-Methoden. Sammlungen können beliebig groß sein und werden in API-Antworten paginatiert.
Grundlagen
In Anfragenachrichten für Sammlungen wird ein optionales Ganzzahlfeld pageSize definiert, um die maximale Anzahl der zurückzugebenden Ergebnisse anzugeben.
Legen Sie für den Parameter pageSize eine positive Zahl fest, die kleiner als 1000 ist. Wenn Sie keinen Wert festlegen oder den Parameter auf null setzen, verwendet die API den Standardwert 50. Wenn Sie den Parameter auf einen negativen Wert festlegen, gibt die API den Fehler INVALID_ARGUMENT zurück.
Einen ressourcenspezifischen pageSize-Wert finden Sie in der Referenzdokumentation der jeweiligen Ressource, z. B. AdBreaks.
Die API gibt möglicherweise weniger Ergebnisse als die angeforderte Anzahl zurück (einschließlich null Ergebnisse), auch wenn Sie sich nicht am Ende der Sammlung befinden. Anhand des Vorhandenseins des Felds nextPageToken können Sie feststellen, ob es weitere Ergebnisse in der Sammlung gibt.
Antwortnachrichten für Sammlungen definieren ein String-nextPageToken-Feld, mit dem die nächste Seite abgerufen werden kann. Das Feld nextPageToken ist leer, wenn das Ende der Sammlung erreicht ist. So können Sie feststellen, ob Sie das Ende einer Sammlung erreicht haben.
In Anfragenachrichten für Sammlungen wird ein optionales StringpageToken-Feld definiert, um zur nächsten Seite in der Sammlung zu gelangen. Änderungen an der pageSize in einer Anfrage für nachfolgende Seiten sind zulässig. Alle anderen Argumente müssen gleich sein. Andernfalls gibt die API einen INVALID_ARGUMENT-Fehler zurück.
Beispiel
cURL
Erste Anfrage
curl https://admanager.googleapis.com/v1/networks/123456/adUnits?pageSize=500
{
"adUnits": [ ... ],
"nextPageToken": "eCGwAcs6hUerggzd2DGv"
}
Anfrage für die nächste Seite
curl https://admanager.googleapis.com/v1/networks/123456/adUnits?pageSize=500&pageToken=eCGwAcs6hUerggzd2DGv
{
"adUnits": [ ... ]
}
Gesamtgröße
Antwortnachrichten für Sammlungen enthalten die Ganzzahl totalSize, die die Gesamtzahl der Entitäten nach dem Filtern darstellt. Dieses Feld wird nur ausgefüllt, wenn es in der Feldmaske angefordert wird.
GET https://admanager.googleapis.com/v1/networks/123456/adUnits?$fields=adUnits,nextPageToken,totalSize
Ergebnisse sortieren
In Anfragenachrichten für Sammlungen wird ein Stringfeld orderBy definiert, um die Sortierreihenfolge anzugeben.
Die Werte müssen eine durch Kommas getrennte Liste von Feldern sein. Beispiel: foo,bar. Standardmäßig werden die Einträge aufsteigend sortiert. Wenn Sie ein Feld absteigend sortieren möchten, hängen Sie das Suffix desc an, z. B. foo desc, bar. Überflüssige Leerzeichen in der Syntax werden ignoriert. Die orderBy-Werte foo, bar desc, foo , bar desc und foo,bar desc sind alle äquivalent. Unterfelder werden mit einem .-Zeichen angegeben, z. B. foo.bar oder address.street.
Die Sortierung wird nur für primitive Felder unterstützt.
Ergebnisse überspringen
Methoden für einen paginaten Vorgang definieren ein Ganzzahlfeld skip, um Ergebnisse zu überspringen. Der Wert „Überspringen“ bezieht sich auf die Anzahl der einzelnen Ressourcen, die übersprungen werden sollen, nicht auf die Anzahl der Seiten.
Beispiel:
Eine Anfrage ohne Seitentoken und einem Überspringwert von 30 gibt eine einzelne Ergebnisseite zurück, beginnend mit dem 31. Ergebnis.
Eine Anfrage mit einem Seitentoken, das dem 51. Ergebnis entspricht (weil die ersten 50 Ergebnisse auf der ersten Seite zurückgegeben wurden) und einem Überspringwert von 30 ergibt eine einzelne Ergebnisseite, beginnend mit dem 81. Ergebnis.
Wenn ein Wert für „Überspringen“ angegeben wird, durch den der Cursor über das Ende der Ergebnisliste hinaus bewegt wird, ist die Antwort 200 OK mit einem leeren Ergebnissatz ohne nextPageToken.