英語で読む

次の方法で共有


Impression Bus API の使用上の制約

この記事では、API の使用中に直面する制約に関する情報を提供します。

入力と出力の調整

優れたパフォーマンスを確保するために、プラットフォーム上のサービスでは、ユーザー レベルとサービス レベルの両方でレート制限が実装されます。 サービスによって設定されるこれらの制限は、時間の経過と伴って変化する可能性があります。

ユーザーがレート制限付き要求を検出すると、API は 2 つの応答コードのいずれかと関連するヘッダーで応答し、理由と続行方法を示します。

  1. HTTP 429 (要求が多すぎます) は、ユーザーがこのサービスへの最大ユーザー呼び出し数を超えたかどうかを示します。

    1. これは常にレート制限応答を示しますが、具体的な詳細については、ヘッダーと応答を参照してください。 一部のアプリケーションでは、429 エラーをトリガーする追加の制限が課される場合がありますが、制限の場所と理由に関する追加情報が提供されます。

    2. 一般的なプラットフォーム レート制限付き要求には、 x-ratelimit-code ヘッダーが含まれます。

  2. HTTP 503 (サービス利用不可) は、サービスが要求に圧倒され、新しい要求を制限しているときに発生します。

    1. 503 がレート制限の場合は、 x-ratelimit-code ヘッダーが存在します。

予想以上にレート制限付き通話が発生している場合は、Xandr アカウントの担当者にお問い合わせください。

エラー メッセージ

調整の制限を超えた場合、API は HTTP 429 または HTTP 503 応答コードで応答します。

スクリプトを使用している場合は、x-ratelimit-code ヘッダーも含む 429 応答コードまたは 503 コードをチェックする必要があります。 このコードを受け取った場合は、応答ヘッダーの Retry-After フィールドに返された番号のスクリプトをスリープ状態にします。 このフィールドは、スロットル制限がリセットされるまでの時間を示し、API 要求の送信を続行できます。

429 個のエラー ヘッダー

ユーザー レベルで制限された要求では、次のレート制限ヘッダーを持つ 429 が返されます。

  1. x-ratelimit-code: 呼び出しがレート制限されたときに返される http コードに対応します。
  2. retry-after: 要求を再試行するまでの待機時間を秒単位で示します。
  3. x-ratelimit-count: これは、ユーザーが制限期間内に行った呼び出しの合計数を示します。 ユーザーはこの番号を参照して、レート制限付き要求を表示するときに通話パターンを調整できます。
  4. 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 エラー ヘッダー

サービス レベルで制限された要求は、次のレート制限ヘッダーを持つ 503 を返します。

  1. x-ratelimit-code: 呼び出しがレート制限されたときに返される http コードに対応します。
  2. 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

Debug パラメーター

応答コードと応答ヘッダーに加えて、API からのすべての応答には、 dbg_info パラメーターが含まれます。 このパラメーターには、API の呼び出しと応答に関する情報が含まれています。 このデバッグ出力の例を次に示します。これには、API から受信した警告、この応答を生成した呼び出しに使用される API バージョン、および使用されるサービスが含まれます。

{
  "response": {
    "status": "OK",
    ...
    "dbg_info": {
      "warnings": [],
      "version": "1.18.349",
      "output_term": "user"
    }
  }
  }

改ページ

指定された GET 応答で返すことができるオブジェクトの最大数は 100 です。 100 を超えるオブジェクトを取得するには、GET 要求のクエリ文字列に start_elementnum_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

FAQ

オブジェクトの制限に近づいているのはどうすればわかりますか?

オブジェクトの制限の 85% と 95% に達すると、電子メール通知が送信され、制限の 100% に達すると別のメールが送信されます。

オブジェクト制限の電子メール通知を受け取るユーザー

オブジェクト制限通知メールは、メンバー サービスの [sherlock_notify_email] フィールドで指定された電子メール アドレスに送信されます。 受信者はいつでも変更できます。 ただし、このフィールドでは、クリエイティブ監査メールの受信者も制御されることに注意してください。

オブジェクトの制限に達した場合はどうすればよいですか?

キャンペーン、広告申込情報、プレースメント、サイト、またはパブリッシャーの制限に近づくか上限に達した場合は、非アクティブ、未使用、または不要なインスタンスを削除して、制限を超えないようにする必要があります。 削除された広告申込情報、キャンペーン、クリエイティブ、パブリッシャー、サイト、プレースメントは引き続きレポートに表示されますが、削除することはできません。

クリエイティブにアプローチするか上限に達した場合は、期限切れでないクリエイティブを削除する必要があります。 期限切れでないクリエイティブには、[ is_expired ] フィールドが [ false] に設定されています。 期限切れのクリエイティブを削除した場合、クリエイティブの数には影響しません。

制限を既に超えている場合はどうすればよいですか?

追加のオブジェクトを作成する必要があるが、既に上記のように制限を満たしているか超えている場合は、未使用のオブジェクトを削除するか、サポートにお問い合わせください。 サポート チームは、削除する非アクティブなオブジェクトを特定するのに役立ちます。

制限は引き上げられますか?

例外的な場合、当社のエンジニアリング チームの裁量により、制限が一時的に少額解除される場合があります。 このオプションについては、Xandr の担当者にお問い合わせください。