Impression Bus API の使用上の制約
この記事では、API の使用中に直面する制約に関する情報を提供します。
優れたパフォーマンスを確保するために、プラットフォーム上のサービスでは、ユーザー レベルとサービス レベルの両方でレート制限が実装されます。 サービスによって設定されるこれらの制限は、時間の経過と伴って変化する可能性があります。
ユーザーがレート制限付き要求を検出すると、API は 2 つの応答コードのいずれかと関連するヘッダーで応答し、理由と続行方法を示します。
HTTP 429 (要求が多すぎます) は、ユーザーがこのサービスへの最大ユーザー呼び出し数を超えたかどうかを示します。
これは常にレート制限応答を示しますが、具体的な詳細については、ヘッダーと応答を参照してください。 一部のアプリケーションでは、429 エラーをトリガーする追加の制限が課される場合がありますが、制限の場所と理由に関する追加情報が提供されます。
一般的なプラットフォーム レート制限付き要求には、
x-ratelimit-code
ヘッダーが含まれます。
HTTP 503 (サービス利用不可) は、サービスが要求に圧倒され、新しい要求を制限しているときに発生します。
- 503 がレート制限の場合は、
x-ratelimit-code
ヘッダーが存在します。
- 503 がレート制限の場合は、
予想以上にレート制限付き通話が発生している場合は、Xandr アカウントの担当者にお問い合わせください。
調整の制限を超えた場合、API は HTTP 429 または HTTP 503 応答コードで応答します。
スクリプトを使用している場合は、x-ratelimit-code
ヘッダーも含む 429 応答コードまたは 503 コードをチェックする必要があります。 このコードを受け取った場合は、応答ヘッダーの Retry-After
フィールドに返された番号のスクリプトをスリープ状態にします。 このフィールドは、スロットル制限がリセットされるまでの時間を示し、API 要求の送信を続行できます。
ユーザー レベルで制限された要求では、次のレート制限ヘッダーを持つ 429 が返されます。
-
x-ratelimit-code
: 呼び出しがレート制限されたときに返される http コードに対応します。 -
retry-after
: 要求を再試行するまでの待機時間を秒単位で示します。 -
x-ratelimit-count
: これは、ユーザーが制限期間内に行った呼び出しの合計数を示します。 ユーザーはこの番号を参照して、レート制限付き要求を表示するときに通話パターンを調整できます。 -
x-an-user-id
: 制限されたユーザー ID。
例 429 レート制限付き要求ヘッダー:
< HTTP/1.1 429 Too Many Requests
< Server: nginx/1.11.10
< Date: Fri, 02 Feb 2024 15:58:18 GMT
< Content-Type: application/json; charset=utf-8
< Content-Length: 358
< Connection: keep-alive
< Retry-After: 9
< x-b3-traceid: 9f53184f6e2c3cb9
< x-ratelimit-code: 429
< x-an-user-id: 1234
< x-ratelimit-count: 1000
< retry-after: 24
サービス レベルで制限された要求は、次のレート制限ヘッダーを持つ 503 を返します。
-
x-ratelimit-code
: 呼び出しがレート制限されたときに返される http コードに対応します。 -
retry-after
: 要求を再試行するまでの待機時間を秒単位で示します。
例 503 レート制限付き要求ヘッダー:
< HTTP/1.1 429 Too Many Requests
< Server: nginx/1.11.10
< Date: Fri, 02 Feb 2024 15:58:18 GMT
< Content-Type: application/json; charset=utf-8
< Content-Length: 358
< Connection: keep-alive
< Retry-After: 9
< x-b3-traceid: 9f53184f6e2c3cb9
< x-ratelimit-code: 503
< retry-after: 24
応答の次のヘッダーは非推奨となり、今後削除される予定です。 関連する情報は提供されなくなりました。 上記のように、スクリプトを使用して新しいヘッダーを使用するように調整してください。
- x-count-read
- x-count-write
- x-rate-limits
- x-ratelimit-read
- x-ratelimit-write
- x-ratelimit-system
応答コードと応答ヘッダーに加えて、API からのすべての応答には、 dbg_info
パラメーターが含まれます。 このパラメーターには、API の呼び出しと応答に関する情報が含まれています。 このデバッグ出力の例を次に示します。これには、API から受信した警告、この応答を生成した呼び出しに使用される API バージョン、および使用されるサービスが含まれます。
{
"response": {
"status": "OK",
...
"dbg_info": {
"warnings": [],
"version": "1.18.349",
"output_term": "user"
}
}
}
指定された GET 応答で返すことができるオブジェクトの最大数は 100 です。 100 を超えるオブジェクトを取得するには、GET 要求のクエリ文字列に start_element
と num_elements
を指定して結果を改ページ処理できます。 たとえば、次の要求は、応答の最初の 50 個のオブジェクトを返します。
$ curl -b cookies -c cookies 'https://api.adnxs.com/creative?start_element=0&num_elements=50'
次の 50 を取得するには、 start_element=50
を設定するだけです。
- 最初の要素は要素 0 です。
- すべての GET 応答には、その GET 要求に一致する要素の合計数を示す "count" プロパティがあります。
- これは、GET 以外の方法で要求されるクリエイティブ検索サービスなどのレポート以外のサービスにも適用されます。
$ curl -b cookies -c cookies 'https://api.adnxs.com/segment?start_element=0&num_elements=100'
$ curl -b cookies -c cookies 'https://api.adnxs.com/user?start_element=0&num_elements=100'
認証後、トークンは 2 時間有効なままになります。 この時間内に再認証する必要はありません。 再認証を行う場合は、次の制限事項に注意してください。API を使用すると、5 分間に 10 回正常に認証できます。 この 5 分以内にそれ以降の認証が試行されると、エラーが発生します。
ヒント
呼び出し応答で "NOAUTH" error_idをリッスンし、受信した後にのみ再認証することをお勧めします。
Xandr では、プラットフォームで使用できる広告申込情報、キャンペーン、クリエイティブ、パブリッシャー、サイト、プレースメントの数が制限されます。 さらに、Xandr では、1 つのドメイン リストで使用できるドメインの数と、1 つのプロファイルで使用できる特定のターゲットの数が制限されます。 オブジェクト制限サービスを使用すると、制限を表示し、使用状況を事前に監視できます。
ヒント
クリエイティブを除くすべてのオブジェクト タイプでは、アクティブオブジェクトと非アクティブオブジェクトの両方が制限に対してカウントされます。 クリエイティブの場合、期限切れでないオブジェクトのみが制限に対してカウントされます。 クリエイティブは、45 日以内に配信も変更もされていない場合に有効期限が切れます。
ほとんどのクライアントでは、既定のオブジェクト制限は次のとおりです。
オブジェクト | 極限 |
---|---|
メンバーごとのクリエイティブ 注: 期限切れでないクリエイティブのみが、この制限に対してカウントされます。 |
10,000 |
メンバーごとのキャンペーン | 10,000 |
メンバーごとの行項目 | 3,000 |
メンバーごとの配置 | 20,000 |
メンバーあたりのサイト数 | 10,000 |
メンバーあたりのパブリッシャー数 | 3,000 |
ドメインごとのドメインの一覧 | 30,000 |
プロファイルごとに対象となるセグメント | 400 |
プロファイルごとに対象となるセグメント グループ | 400 |
プロファイルごとに対象となるコンテンツ カテゴリ | 300 |
プロファイルごとに対象となるプラットフォーム コンテンツ カテゴリ | 300 |
プロファイルごとに対象となる郵便番号 | 4000 |
プロファイルごとに対象となるインベントリ ソース | 非推奨 |
プロファイルごとに対象となるパブリッシャー | 300 |
プロファイルごとのターゲットグループ配置 | 100 |
プロファイルごとのターゲット配置 | 250 |
メンバーごとに対象となる取引 (注: プロファイルに関する取引のみがこの制限に対してカウントされます) | 1000 |
メンバーごとに対象となるプロファイル | 100 |
オブジェクトの制限の 85% と 95% に達すると、電子メール通知が送信され、制限の 100% に達すると別のメールが送信されます。
オブジェクト制限通知メールは、メンバー サービスの [sherlock_notify_email
] フィールドで指定された電子メール アドレスに送信されます。 受信者はいつでも変更できます。 ただし、このフィールドでは、クリエイティブ監査メールの受信者も制御されることに注意してください。
キャンペーン、広告申込情報、プレースメント、サイト、またはパブリッシャーの制限に近づくか上限に達した場合は、非アクティブ、未使用、または不要なインスタンスを削除して、制限を超えないようにする必要があります。 削除された広告申込情報、キャンペーン、クリエイティブ、パブリッシャー、サイト、プレースメントは引き続きレポートに表示されますが、削除することはできません。
クリエイティブにアプローチするか上限に達した場合は、期限切れでないクリエイティブを削除する必要があります。 期限切れでないクリエイティブには、[ is_expired
] フィールドが [ false
] に設定されています。 期限切れのクリエイティブを削除した場合、クリエイティブの数には影響しません。
追加のオブジェクトを作成する必要があるが、既に上記のように制限を満たしているか超えている場合は、未使用のオブジェクトを削除するか、サポートにお問い合わせください。 サポート チームは、削除する非アクティブなオブジェクトを特定するのに役立ちます。
例外的な場合、当社のエンジニアリング チームの裁量により、制限が一時的に少額解除される場合があります。 このオプションについては、Xandr の担当者にお問い合わせください。