レート制限

Advertiser API は、こちらに記載された REST API Rate Limiting in v1.1 と同様にレート制限されます。REST API v1.1 とは異なり、プログラム的にエンドポイントごとの制限を取得するインデックスはありません。エンドポイントのレート制限とリセットウィンドウは、HTTP レスポンスヘッダーで通知されます。Ads API のすべてのレート制限は OAuth 1.0A を利用します。

ユーザーレベルと広告アカウントレベルの制限

レート制限には 2 種類あります: ユーザートークンレベルと広告アカウントレベルです。一部のエンドポイントは、広告アカウントレベルのレート制限を利用できるようになっています。ユーザートークンとは、Ads API に認証・呼び出しを行うために使用する OAuth アクセストークンのことです。各ユーザートークンは、1 つ以上の広告アカウントにアクセスできます。開発者はレスポンスヘッダーで返される場合は広告アカウントレベルのレート制限を利用し、広告アカウントレベルの制限が見つからない場合のみユーザーレベルの制限を利用してください。ユーザーレベルのレート制限は、以下のヘッダーで表されます: x-rate-limit-limit、x-rate-limit-remaining、x-rate-limit-reset。広告アカウントレート制限が有効なエンドポイントでは、レート制限は次のヘッダーで表されます: x-account-rate-limit-limit、x-account-rate-limit-remaining、x-account-rate-limit-reset。広告アカウントレベルのレート制限は、1 つのユーザートークンで複数の広告アカウントにアクセスするアプリケーションが、エンティティデータ(キャンペーンや line item オブジェクトなど)を同期できるようにするために、GET エンドポイントに対してのみ提供されます。書き込みアクションは、同じ広告アカウントレベルのレート制限を使用することが保証されません。広告アカウントレベルのレート制限が適用されるエンドポイントでは、ユーザーレベルのレート制限はアプリケーション全体のグローバル割り当てを表す高い値に設定されています。利用可能な場合は、リクエスト量の制御において広告アカウントレベルのレート制限を優先すべきです。

ベストプラクティス

最終同期タイムスタンプをデータベースに保存し、可能な場合はデータのリクエスト時に sort_by=updated_at-desc オプションを指定することで、最終同期タイムスタンプより古いデータに達した時点で同期プロセスを停止できるようにします。これにより、同じデータの冗長な同期を避けられます。
1 回のリクエストで複数エンティティを取得する: 一部のエンドポイントでは、カンマ区切りの値リストを指定して、複数の同種データを取得できます。これにより全体的な呼び出し回数を減らし、レート制限をより効率的に活用できます。
リクエストで最大の「count」を指定する: GET accounts/:account_id/targeting_criteria のような一部のエンドポイントでは、デフォルトの 200 ではなく 1000 個のオブジェクトを返すために、最大の count 値で呼び出すことが強く推奨されます。

Analytics 同期

analytics エンドポイントのレート制限の詳細については、Analytics Rate Limiting Guide を参照してください。

FAQ

特定の広告アカウントや自社アプリケーションのレート制限を引き上げることは可能ですか? 一般に、レート制限を引き上げることはできず、最大級の広告アカウントをサポートできる値に設定されています。まず本ドキュメントに記載されたベストプラクティスを実装してください。それでもレート制限がスケールやビジネス目標達成に支障をきたす場合は、ユースケースや対象リクエストの完全な詳細を添えて、X Ads API の担当者にご連絡ください。