ベスト プラクティス

このページでは、Google Ad Manager API を使ったアプリケーションを開発する際に考慮すべきさまざまなおすすめの方法について説明します。

実行中にサービス クライアント/スタブを再利用する

新しいサービス クライアント/スタブの作成には、WSDL の取得とリソースの割り当てに関連する限界コストがかかります。可能であれば、実行の開始時にサービス クライアント/スタブを 1 回作成し、必要に応じてクラスと関数で使用できるようにします。

オブジェクトの取得時にページングを使用する

すべてのサービスは get*ByStatement() メソッドをサポートしています。これにより、PQL 構文を使用して結果をフィルタリングできます。LIMIT 句と OFFSET 句を使用すると、サイズの大きい結果セットをページに分割できます。これにより、タイムアウトを防ぎ、レスポンスのページサイズを適度に保つことができます。推奨されるページサイズは 200 ～ 500 で、オブジェクトの複雑さによって異なります。

バッチ アップデート リクエスト

同じタイプの複数のオブジェクトを変更する場合は、同じ update*() リクエストですべてのオブジェクトを送信することで、パフォーマンスを向上させることができます。リクエストごとにクライアントとサーバーでわずかなオーバーヘッドがあるため、バッチ処理はリクエスト数を減らす効果的な手段です。たとえば、updateOrders を使用して、呼び出しごとに 1 つの注文ではなく、注文のバッチを更新します。

PQL でバインド パラメータを使用する

バインド パラメータは、PQL クエリ ステートメントに変数を入れる方法です。PQL では、コロンで始まるスペースを含まない名前でバインド変数を参照します。例::name。コード例については、PQL 構文のページをご覧ください。

バインド変数を使用することをおすすめします。バインド変数を使用すると、文字列と変数をクエリ ステートメントに連結する必要がないため、コードが読みやすくなります。また、バインド パラメータ値を置換することで新しいクエリを作成できるため、PQL ステートメントの再利用が容易になります。

ユーザー権限は慎重に付与する

UserService を使用してユーザーロールを作成または更新するときは、不要な権限をユーザーに付与しないように注意してください。ユーザーに管理者ロールを割り当てるのではなく、ロールの組み合わせで API の多くの機能にアクセスできます。ユーザーに割り当てるロールを決定する際は、権限に関するドキュメントをご覧ください。また、サードパーティ アプリケーション デベロッパーは、ネットワークにユーザーの作成を依頼する際に、アプリケーションに必要なアクセスレベルを決定しておく必要があります。管理者よりも権限の少ない役割で十分な場合もあります。

割り当て上限を超えないようにする

Ad Manager API では、堅牢性を確保するためにいくつかの割り当て上限が適用されます。アプリケーションをこれらの上限内に収め、API が返す割り当てエラーへの対処方法を理解しておくことが重要です。

API 割り当て

API リクエストに適用される最初の割り当ては、ネットワーク レベルの割り当てです。リクエスト数の上限は、アド マネージャー 360 アカウントの場合は 1 秒あたり 8 件、アド マネージャー アカウントの場合は 1 秒あたり 2 件です。この上限を超えると、 QuotaError.EXCEEDED_QUOTA エラーが発生します。ネットワーク上で行われたすべての API リクエストは、この割り当てに適用されます。これには、ユーザーまたは社内の他のユーザーがネットワークへの API アクセスを許可したサードパーティ アプリケーションも含まれます。

システム固有の割り当て

アド マネージャー内でリソースを大量に消費するシステムを適切に保護するには、API の割り当てだけでは不十分です。レポート作成システムと予測システムでは、API エラーを引き起こす可能性がある独自の割り当て（それぞれ QuotaError.REPORT_JOB_LIMIT と ForecastError.EXCEEDED_QUOTA）が定義されています。

割り当てエラーの処理

アプリケーションで上記の割り当てエラーが発生した場合は、API リクエストを再試行してください。最初は少なくとも 5 秒間待機し、エラーが続く場合は 指数バックオフを使用して再試行間隔を長くすることをおすすめします。再試行が成功しない場合は、API アプリケーションの監査を実行して、ネットワーク上のユーザーが割り当てを消耗していないかどうかを確認します。