Pagination

Ad Manager API は、データのコレクションを提供します。最も一般的な形式は List メソッドです。コレクションのサイズは任意に設定でき、API レスポンスでページングされます。

基本

コレクションのリクエスト メッセージでは、返される結果の最大数を指定するために、オプションの整数 pageSize フィールドを定義します。

pageSize パラメータを 1000 未満の正の数に設定します。値を設定しないか、パラメータをゼロに設定した場合、API はデフォルト値 50 を使用します。パラメータを負の値に設定すると、API から INVALID_ARGUMENT エラーが返されます。

リソース固有の pageSize 値については、リソースのリファレンス ドキュメント（AdBreaks など）をご覧ください。

コレクションの最後でなくても、API からリクエストされた数よりも少ない結果（結果がゼロの場合を含む）が返されることがあります。nextPageToken フィールドの有無を使用して、コレクションに追加の結果があるかどうかを判断します。

コレクションのレスポンス メッセージでは、文字列 nextPageToken フィールドが定義されています。これは、次のページの取得に使用できます。コレクションの終わりに達すると、nextPageToken フィールドは空になります。これは、コレクションの終わりに達したかどうかを判断する唯一の方法です。

コレクションのリクエスト メッセージでは、コレクションの次のページに移動するためのオプションの文字列 pageToken フィールドを定義します。後続のページのリクエストで pageSize を変更することは許可されています。他の引数はすべて同じである必要があります。引数が異なる場合、API は INVALID_ARGUMENT エラーを返します。

例

cURL

最初のリクエスト

curl https://admanager.googleapis.com/v1/networks/123456/adUnits?pageSize=500

{
  "adUnits": [ ... ],
  "nextPageToken": "eCGwAcs6hUerggzd2DGv"
}

次のページのリクエスト

curl https://admanager.googleapis.com/v1/networks/123456/adUnits?pageSize=500&pageToken=eCGwAcs6hUerggzd2DGv

{
  "adUnits": [ ... ]
}

合計サイズ

コレクションのレスポンス メッセージには、フィルタ適用後のエンティティの合計数を表す整数 totalSize が含まれます。このフィールドは、フィールドマスクでリクエストされた場合にのみ入力されます。

GET https://admanager.googleapis.com/v1/networks/123456/adUnits?$fields=adUnits,nextPageToken,totalSize

結果の並べ替え

コレクションのリクエスト メッセージでは、文字列 orderBy フィールドを定義して並べ替え順序を指定します。

値は、フィールドのカンマ区切りリストにする必要があります。例: foo,bar。デフォルトの並べ替え順序は昇順です。フィールドに対して降順を指定するには、desc 接尾辞を追加します（例: foo desc, bar）。構文内の余分な空白文字は無視されます。orderBy の値 foo, bar desc、foo , bar desc、foo,bar desc はすべて同義です。サブフィールドは、foo.bar や address.street などの . 文字で指定します。

並べ替えはプリミティブ フィールドでのみサポートされます。

検索結果をスキップする

ページネーション オペレーションのメソッドでは、結果をスキップする整数 skip フィールドを定義します。skip 値は、スキップする個々のリソースの数を指します。ページ数ではありません。

次に例を示します。

ページトークンがなく、スキップ値が 30 のリクエストは、31 番目の結果から始まる 1 ページの結果を返します。

51 番目の結果に対応するページトークンと、スキップ値 30 のリクエストでは、81 番目の結果から始まる 1 ページの結果が返されます（最初の 50 個の結果が最初のページで返されたため）。

カーソルが結果のコレクションの末尾を越えるスキップ値が指定されている場合、レスポンスは 200 OK で、nextPageToken のない空の結果セットが返されます。

重要: skip フィールドは、ページネーションの代わりに使用しないでください。ページ設定トークンにより、レスポンスが同じ初期結果セットから取得されることが保証されます。