Digital Platform API - 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 応答コードで応答します。

スクリプトを使用している場合は、ヘッダーも含む 429 応答コードまたは 503 コードをチェックするx-ratelimit-code必要があります。 このコードを受け取った場合は、応答ヘッダーのフィールドに 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 要求のクエリ文字列に と num_elements をstart_element指定して、結果を改ページ処理できます。 たとえば、次の要求は、応答の最初の 50 個のオブジェクトを返します。

$ curl -b cookies -c cookies 'https://api.appnexus.com/creative?start_element=0&num_elements=50'

次の 50 を取得するには、 を設定 start_element=50するだけです。

• 最初の要素は要素 0 です。
• すべての GET 応答には、その GET 要求に一致する要素の合計数を示す "count" プロパティがあります。
• これは、GET 以外の方法で要求されるクリエイティブ検索サービスなどのレポート以外のサービスにも適用されます。

例

$ curl -b cookies -c cookies 'https://api.appnexus.com/segment?start_element=0&num_elements=100'
$ curl -b cookies -c cookies 'https://api.appnexus.com/user?start_element=0&num_elements=100'

認証頻度

認証後、トークンは 2 時間有効なままになります。 この時間内に再認証する必要はありません。 再認証を行う場合は、次の制限事項に注意してください。API を使用すると、5 分間に 10 回正常に認証できます。 この 5 分以内にそれ以降の認証が試行されると、エラーが発生します。

オブジェクトの制限

Xandr では、プラットフォームで使用できる広告申込情報、キャンペーン、クリエイティブ、パブリッシャー、サイト、プレースメントの数が制限されます。 さらに、Xandr では、1 つのドメイン リストで使用できるドメインの数と、1 つのプロファイルで使用できる特定のターゲットの数が制限されます。 オブジェクト制限サービスを使用すると、制限を表示し、使用状況を事前に監視できます。

ほとんどのクライアントでは、既定のオブジェクト制限は次のとおりです。

FAQ

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

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

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

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

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

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

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

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

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

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

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