ページ分割とフィルター処理の調整 - インプレッション バス API
API サービスの悪用を防ぐために、サービスごとにレート制限が適用されます。 特定のレート制限は、ユーザーによって呼び出されるエンドポイントによって異なります。 この方法は、クライアントの制限に焦点を当てた以前のレート制限とは異なります。 これらの制限は時間の経過と同時に調整されるため、具体的な詳細は提供されません。 ただし、レート制限応答は、呼び出しまたはスクリプトを適切に調整するために必要な情報を提供します。
調整の制限を超えた場合、API は HTTP 429 (ユーザーがこのサービスに対して呼び出しを行いすぎることを示す要求が多すぎる) または HTTP 503 (サービス利用不可 - つまり、サービスが要求に圧倒され、それ以上の応答コードを受け取ることができない) のいずれかで応答します。 また、これが発生した理由と次に何を行うかを理解するのに役立つ関連ヘッダーも提供されます。
429 エラーが発生すると、要求がレート制限されたことを示します。 503 応答の場合は、ヘッダーをチェックして、レート制限が原因であるかどうかを確認する必要があります。 503がレート制限によって引き起こされたことを示す、以下の最初の一覧のヘッダーを探します。
-
x-ratelimit-code
: これは、呼び出しがレート制限されたときに返される HTTP コードに対応します。- 429 は、ユーザーがサービスによって設定されたユーザーごとの制限を超えたことを示します。
- 503 は、サービスがその時点の呼び出しの合計に基づいてレート制限を適用していることを示します。
- どちらのコードでも、要求を再試行するタイミングを指定する 'retry-after' ヘッダーが含まれます。
-
retry-after
: 要求を再試行するまでの待機時間を秒単位で示します。 -
x-ratelimit-count
: 制限期間内にユーザーが行った通話の合計数が表示されます。 ユーザーは、この情報を使用して、レート制限付き要求が発生した場合の呼び出しパターンを調整できます。- このヘッダーは、状態コードが 429 の場合にのみ含まれます。
API は、要求に対する応答を 100 個のオブジェクトに制限します。 改ページでは、複数の要求を使用して合計 100 を超えるオブジェクトを取得できますが、各要求は 100 個のオブジェクトに制限されます。 これは、 start_element
と num_elements
クエリ文字列パラメーターを使用して実現されます。 次の例では、複数の HTTP GET
呼び出しを使用して、多くのクリエイティブを取得します。
注意
出力は、領域を節約するために省略されています。
$ curl -c cookies -b cookies 'https://api.adnxs.com/creative?start_element=0&num_elements=100'
{
"response": {
"status": "OK",
"creatives": [...],
"count": 203151,
"start_element": 0,
"num_elements": 100
}
}
$ curl -c cookies -b cookies 'https://api.adnxs.com/creative?start_element=100&num_elements=100'
{
"response": {
"status": "OK",
"creatives": [...],
"count": 203151,
"start_element": 100,
"num_elements": 100
}
}
$ curl -c cookies -b cookies 'https://api.adnxs.com/creative?start_element=200&num_elements=100'
{
"response": {
"status": "OK",
"creatives": [...],
"count": 203151,
"start_element": 200,
"num_elements": 100
}
}
フィルター処理を使用すると、API から返されるオブジェクトのサブセットを指定できます。 最も一般的で、おそらく最も便利なフィルターは min_last_modified
です。これは、指定された日付以降に変更されたオブジェクトのみを返します。 次の例では、API GET
要求でフィルター処理を使用して、2013 年 5 月 14 日 00:00:00 UTC 以降に変更されたクリエイティブのみを返します。
注意
API 呼び出しの出力は、スペースを節約するために省略されています。
$ curl -b cookies -c cookies 'https://api.adnxs.com/creative?min_last_modified=2013-05-14+00:00:00'
{
"response": {
"status": "OK",
"creatives": [
{
"id": 298390,
"last_modified": "2011-07-13 16:08:32",
...
},
{
"id": 298391,
"last_modified": "2011-07-13 16:08:32",
...
},
{
"id": 317677,
"last_modified": "2011-07-13 04:44:04",
...
},
{
"id": 317678,
"last_modified": "2011-07-13 04:12:57",
...
},
{
"id": 328516,
"last_modified": "2011-07-13 18:18:21",
...
},
{
"id": 328531,
"last_modified": "2011-07-13 18:57:12",
...
}
],
"count": 1740,
"start_element": 0,
"num_elements": 6
}
}