レート制限

Advertiser API には、REST API v1.1 のレート制限に記載されている REST API v1.1 と同様のレート制限が適用されます。REST API v1.1 と異なり、エンドポイントごとの制限を示すプログラムから利用可能なインデックスはありません。エンドポイントごとのレート制限とリセットウィンドウは、HTTP レスポンスヘッダーを通じて伝達されます。Ads API におけるすべてのレート制限は OAuth 1.0a を利用しています。

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

レート制限には、ユーザートークンレベルと広告アカウントレベルの 2 種類があります。エンドポイントの一部は、広告アカウントレベルのレート制限を使用できるように有効化されています。ユーザートークンとは、Ads API を認証して呼び出すために使用する OAuth access token を指します。各ユーザートークンは、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。広告アカウントレベルのレート制限は、アプリケーションが単一のユーザートークンから複数の広告アカウントにアクセスしつつ、エンティティデータ (キャンペーンやラインアイテムオブジェクトなど) を同期できるようにするため、GET エンドポイントに対してのみ提供されます。書き込みアクションについては、同じ広告アカウントレベルのレート制限が使用されることは保証されません。広告アカウントレベルのレート制限が適用されるエンドポイントでは、ユーザーレベルのレート制限は、アプリケーション全体に対するグローバルなクォータを表す高い値に設定されています。利用可能な場合は、リクエスト量を制御する際に、広告アカウントレベルのレート制限を優先して使用する必要があります。

ベストプラクティス

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

アナリティクスの同期

アナリティクスエンドポイントに対するレート制限の詳細については、Analytics Rate Limiting Guide を参照してください。

FAQ

特定の広告アカウントまたは自社アプリケーションのレート制限を増やすことは可能ですか？ 通常、レート制限を引き上げることはできません。レート制限は、最大規模の広告アカウントにも対応できるように設定されています。まずは本ドキュメントに記載されているベストプラクティスを実装してください。それでもなおレート制限によってスケールやビジネス目標の達成に支障が生じる場合は、ユースケースおよび関連するリクエストの詳細な情報を添えて、X Ads API の担当窓口までご連絡ください。