おすすめの方法

このガイドでは、AdWords API アプリケーションの効率とパフォーマンスを最適化するためのおすすめの方法をいくつかご紹介します。

継続的なメンテナンス

アプリが中断なく実行されるようにするには:

  • AdWords API センターに登録されているデベロッパーの連絡先メールアドレスを最新の状態に保ちましょう。 このメールアドレスは、AdWords API センターから連絡を取るために使用されます。API 利用規約の遵守に関して連絡が取れない場合、事前の通知なしに API へのアクセスを無効にさせていただく場合があります。個人のアカウントや普段チェックしていないアカウントに結び付けられた個人用メールアドレスの使用は避けてください。

  • 製品の変更、メンテナンスによるダウンタイム、サポート終了日などの情報を受け取るため、次のコンテンツにご登録ください。

フォーラムは AdWords API チームが定期的に確認しており、API に関する質問を投稿するには最適な場所です。

  • アプリは常に AdWords API の利用規約(T&C)と必須機能の要件(RMF)に準拠するようにしてください。必要に応じて、トークン審査およびコンプライアンス チームから連絡先メールアドレス宛にご連絡いたします。T&C や RMF についてご質問やご不明な点がある場合は、開発者トークンの承認審査の際に送信されたメールに返信して審査チームにお問い合わせください。

最適化

オペレーションをバッチ処理する

API へのリクエストには、往復ネットワーク遅延、シリアライゼーション処理、デシリアライゼーション処理、バックエンド システムの呼び出しなどの多くの固定費用が発生します。これらの固定費用の影響を減らし、全体的なパフォーマンスを向上するため、API の mutate() メソッドの大部分が、オペレーションの配列を受け取るよう設計されています。複数のオペレーションを 1 つのリクエストにまとめてバッチ処理すると、リクエストの数を減らして関連する固定費用を下げることができます。オペレーションが 1 つだけのリクエストはできるだけ避けてください。

たとえば、複数の広告グループでキャンペーンに 50,000 個のキーワードを追加する場合は、キーワードごとにリクエストを 50,000 回行うのではなく、キーワードを 500 個ずつに分けて 100 回のリクエストを、またはキーワードを 5,000 個ずつに分けて 10 回のリクエストを行います。1 回のリクエストで許可されるオペレーションの数には制限があります。また、最適なパフォーマンスを引き出すにはバッチ処理のサイズを適宜調整する必要があります。

リクエストの規模を大きくして回数を減らすと、アプリでリクエストに基づくレート制限を超過する頻度が下がるというメリットもあります。

オペレーションをまとめる

オペレーションの操作対象となる広告グループやキャンペーンがすべて同じである場合、複数の異なる広告グループやキャンペーンを操作対象とする場合に比べて処理が速くなります。このため、同じ広告グループやキャンペーンを操作対象とするオペレーションを 1 つのリクエストにまとめると、そのリクエストで操作対象となる広告グループやキャンペーンの合計数が減少し、全体的なパフォーマンスが向上します。

同じ広告グループやキャンペーンに同時にリクエストを行うと CONCURRENT_MODIFICATION エラーが発生する場合があります。同じ広告グループやキャンペーンに変更するオペレーションをすべて 1 つのリクエストにまとめると、こうした競合が生じるリスクを低減できます。

1 つのキャンペーンの複数の広告グループに 50,000 個のキーワードを追加する上記の例で考えると、シンプルなアプローチとしては、オペレーションをバッチに分ける前に、操作対象となる広告グループごとにキーワードを並び替えます。これにより、同じ広告グループ内のすべてのキーワードが 1 つの同じリクエストで処理される可能性が高まり、1 つのリクエストで操作対象となる広告グループの合計数を削減できます。このアプローチをさらに進めれば、バッチ処理の規模を大きく維持しながら、関係するオペレーションをできるだけ少ないリクエストにまとめることができます。

アクセス トークンを再利用する

同じ OAuth2 アクセス トークンをスレッドやプロセス間で再利用することで、トークンを定期的に更新することによる手間が減り、アプリで過剰なトークン更新によってレート制限を超過する可能性を抑えられます。詳しくは、OAuth2 リクエストの最適化をご覧ください。

スパース オブジェクトを送信する

オブジェクトを API に送信すると、フィールドのデシリアライゼーションと検証が行われ、データベースに保存されます。このため、一部のフィールドを更新するためだけにオブジェクト全体を渡すと、処理に余計な時間がかかり、パフォーマンスの低下につながります。この問題を軽減するため、AdWords API はスパース アップデートをサポートしています。スパース アップデートを使用すれば、オブジェクトで変更が必要なフィールドだけに値を入れることができます。値が入っていないフィールドや null 値のフィールドは変更されないため、リクエストのパフォーマンスが向上します。

たとえば、キーワード単位で入札単価を更新するアプリケーションでは、値を入れる必要のあるフィールドが adGroupIDcriterionID入札単価に限られるため、スパース アップデートが役に立ちます。キーワード 150 個を使ったテストでは、全フィールドに値が入ったオブジェクトを渡す代わりにスパース アップデートを使用すると、パフォーマンスが 20% 向上しました。

圧縮を使用する

AdWords API はリクエストとレスポンスの両方で SOAP メッセージの gzip 圧縮をサポートしています。レスポンスで gzip 圧縮を有効にするには、リクエストに次の 2 つの HTTP ヘッダーを含めます。

  • User-Agent: 文字列「gzip」を含めます
  • Accept-Encoding: 値「gzip」を指定します

例:

User-Agent: My App (gzip)
Accept-Encoding: gzip

クライアント ライブラリをご利用の場合、圧縮を有効にする方法については、クライアント ライブラリのドキュメントをご覧ください。

エラーの処理と管理

開発にはエラーがつきものです。ここでは、アプリにエラー管理のしくみを構築する際の留意点と手法について説明します。

エラーの管理について詳しくは、トラブルシューティング ガイドもご覧ください。

リクエスト ソースを区別する

主にインタラクティブな処理を行うアプリでは、UI でユーザーが開始するアクションに応答して直接 API を呼び出します。オフライン処理が中心のアプリでは、API は定期的なバックエンド処理の一環として呼び出します。この 2 つを組み合わせたアプリも多くあります。エラー管理について検討する際は、このようなリクエストの違いを区別することをおすすめします。

ユーザーが開始するリクエストの場合、ユーザーの利便性を最優先にする必要があります。エラーが発生したときは、UI で状況をできるだけ詳しくユーザーに示します。可能な場合は、エラーを解決するための簡単な手順も示します(下記の提案を参照)。

バックエンドで開始されるリクエストの場合、アプリで発生する可能性のあるさまざまな種類のエラーについてハンドラを実装します(下記の提案を参照)。あまり発生しないエラーや過去に例のないエラーを処理するためのデフォルト ハンドラを必ず用意してください。デフォルト ハンドラでは、オペレーターが確認して適切な解決策を判断できるよう、失敗したオペレーションや発生したエラーをキューに追加すると便利です。

エラータイプを区別する

以下に、エラーを大きく 4 つのカテゴリに分けて示します。エラーはカテゴリごとに別々に処理する必要があります。これらのカテゴリはすべてのエラーを網羅しているわけではなく、エラーによっては複数のカテゴリに当てはまるものもありますが、アプリのエラー処理を構築する第一歩として役に立ちます。特定のエラーについて詳しくは、一般的なエラーをご覧ください。

  1. 認証エラーと承認エラー

    • 認証とは、アプリがユーザーに代わって AdWords にアクセスして処理する権限を、ユーザーが許可することです。認証は、OAuth2 フローによって生成される認証情報を通じて管理されます。

    • 承認とは、認証済みのアプリに対して、ユーザーに代わって処理する特定の AdWords データの読み取りや書き込みを許可することです。

    認証エラーの制御できない原因で最も多いのは、認証したユーザーがアプリに許可した代理権限を取り消した場合です。たとえば、アプリでクライアントのアカウントを管理する際に、独立したクライアント別に AdWords アカウントを管理し、クライアントごとに認証を受けている場合、各クライアントはアプリのアクセス権をいつでも取り消すことができます。アクセス権が取り消されたタイミングによっては、API から直接 AuthenticationError.OAUTH_TOKEN_REVOKED エラーが返されたり、クライアント ライブラリに組み込みの認証情報オブジェクトからトークン失効の例外がスローされたりする場合があります。いずれの場合も、アプリにクライアント用の UI があれば、OAuth2 フローを再起動してアプリの代理権限を再確立するよう、クライアントに求める設計にすることが考えられます。

    承認エラーの制御できない原因でよくあるものとしては、クライアント センター(MCC)アカウントの階層の変更が挙げられます。通常、単一の MCC アカウント階層で動作するアプリは、階層中のすべてのサブアカウントにアクセスする権限を持つ、最上位の MCC アカウントの管理者ユーザーとして認証されます。サブアカウントのユーザーが MCC アカウントとのリンクを解除した場合、そのサブアカウントにアクセスしようとすると、アプリは AuthorizationError.USER_PERMISSION_DENIED エラーを受け取ることになります。ManagedCustomerService を使用すると、サブアカウントが実際に階層から削除されているかどうかを確認できます。

    承認エラーの他の原因として、アプリを認証したユーザーのアクセス権が変更されたことが考えられます。 たとえば、AdWords アカウントの管理者権限を持つ他のユーザーが、アプリを認証したユーザーの権限を読み取り専用に変更した場合は、すべての mutate リクエストが失敗し、AuthorizationError.USER_HAS_READONLY_PERMISSION エラーが発生します。

    いずれの例でも、アプリでユーザーに対処方法を示すか、問題をアカウント マネージャーにエスカレーションして解決を求めることが考えられます。

  2. 再試行可能なエラー

    エラーには一時的な問題であり、少し待ってリクエストを再試行すれば解決できるものもあります。これには、CONCURRENT_MODIFICATIONUNEXPECTED_INTERNAL_API_ERRORRATE_EXCEEDED が当てはまります。

    ユーザーが開始するリクエストの場合、すぐに UI にエラーを表示し、ユーザーに再試行する選択肢を示す方法が考えられます。また、最初はアプリでリクエストを自動的に再試行し、再試行の最大回数に達するか、一定の合計ユーザー待機時間が経過して初めて UI にエラーを表示するという方法も考えられます。

    バックエンドで開始されるリクエストの場合、アプリでリクエストを最大回数まで自動的に再試行する必要があります。

    リクエストの再試行では、指数バックオフ ポリシーを使用します。たとえば、最初の再試行の前に 5 秒待機した場合、2 回目の前には 10 秒、3 回目には 20 秒待機するようにします。指数バックオフは、API の過剰な呼び出しを防ぐことに役立ちます。

    RATE_EXCEEDED エラーの場合、アプリが再試行する前に待機する時間は、エラーの retryAfterSeconds フィールドの値より長い必要があります。詳しくは、レート制限ガイドをご覧ください。他の再試行可能なエラーの待ち時間はそれよりも短くできますが、指数バックオフ ポリシーに従ってください。

  3. 検証エラー

    検証エラーは、オペレーションへの入力が無効であることを示すエラーです。 PolicyViolationErrorDateErrorDateRangeErrorStringLengthErrorUrlError など、多くのエラーがこれに当てはまります。

    検証エラーは、ユーザーが開始するリクエストで入力内容が無効であった場合に最も多く発生します。この場合、受け取った API エラーに応じて、適切なエラー メッセージをユーザーに示す必要があります。API を呼び出す前にユーザー入力のよくある間違いを検証することで、アプリの応答時間を短縮し、より効率的に API を使用することもできます。

    バックエンドで開始されたリクエストの場合、失敗したオペレーションをキューに追加し、オペレーターが確認できるようにすることが考えられます。

  4. 同期関連のエラー

    AdWords アプリの多くにはローカル データベースがあり、AdWords オブジェクトが保存されています。この手法には、ローカル データベースと AdWords にある実際のオブジェクトが同期しなくなる場合があるという問題があります。たとえば、ユーザーが直接 AdWords から広告グループを削除しても、ローカル データベースでは変更が認識されず、その広告グループが存在しているものとして API 呼び出しを行ってしまう場合があります。 このような同期の問題は、INVALID_IDDUPLICATE_CAMPAIGN_NAMEDUPLICATE_ADGROUP_NAMEAD_NOT_UNDER_ADGROUPCANNOT_OPERATE_ON_REMOVED_ADGROUPAD などのさまざまなエラーとして現れます。

    ユーザーが開始するリクエストの場合、同期に問題がある可能性があることをユーザーに警告した直後に、AdWords オブジェクトの関連クラスを取得してローカル データベースを更新するジョブを開始し、ユーザーに UI を更新するよう促す方法が考えられます。

    バックエンドで開始されるリクエストの場合、エラーによっては、提供される情報を使用して、アプリが自動的にローカル データベースの増分を修正できます。たとえば、CANNOT_OPERATE_ON_REMOVED_ADGROUPAD を受け取ったら、アプリで該当の広告をローカル データベースから削除するようにマークを付ける必要があります。この方法で処理できないエラーの場合、アプリでより包括的な同期ジョブを開始するか、オペレーターが確認できるようエラーをキューに追加する方法が考えられます。

Partial Failure を処理する

デフォルトでは、API のリクエストは最小単位として処理されます。リクエストのオペレーションは 1 つでもエラーが発生すると、すべてが中止されます。こうした原子性は安全のためですが、オペレーションがそれぞれ独立で、失敗したものだけを確認する必要があるような場合など、多くの場合に不都合が生じます。このデフォルトの動作に対処するには 2 つの方法があります。

1 つ目の方法は、応答時にエラーを確認し、そのエラーをスローしたオペレーションと関連付け、エラーをスローしなかったオペレーションだけを含む新しいリクエストを行うことです。これでエラーをスローしなかったオペレーションは正常に実行できます。 エラーをスローしたオペレーションをエラー処理メカニズム(上記を参照)に渡すか、オペレーターが確認できるようキューに追加することも考えられます。

2 つ目の方法は、API リクエストで Partial Failure フラグを有効にすることです。このフラグを有効にすると各オペレーションは独立して扱われ、1 つでエラーが発生しても他のオペレーションの実行は妨げられません。特定のオペレーションでのエラーは通常どおり返されます。 このフラグはすべてのクライアント ライブラリでサポートされています。

Partial Failure フラグを使用する主なメリットは、有効なオペレーションについては再試行しなくても自動的に実行されることで、処理がシンプルになり API 呼び出しが減ることです。ほとんどのアプリでは Partial Failure の使用が適切です。

ただし、アプリによってはエラー処理をより詳細に制御する方が有益な場合もあります。たとえば、ある広告でポリシーエラーが起こっても他の広告を止めないものの、他の(より重大な問題を示すような)エラーが起こったらリクエスト全体を中止したい場合です。このしくみを実装するには、上記の 1 つ目の方法を使用する必要があります。

いずれの場合も、エラーによっては、どちらかが単独で有効なオペレーション間の依存関係を反映している場合があることに注意してください。たとえば、AdGroupAdError.ENTITY_REFERENCED_IN_MULTIPLE_OPSAdParamError.AD_PARAM_CANNOT_BE_SPECIFIED_MULTIPLE_TIMES などです。

バックエンドを同期する

アプリのユーザーが AdWords アカウントに直接アクセスできる場合、行われた変更をアプリで認識できず、ローカル データベースの同期が失われる場合があります。上記のとおり、同期関連のエラーの発生後に対処することはできますが、事前に防ぐ方法を模索することもできます。事前の対処法の 1 つは、毎晩、すべてのアカウントで同期ジョブを実行し、アカウントの AdWords オブジェクトを取得してローカル データベースと比較することです。効率よく取得するために、通常の API サービスではなく構成レポートの使用を検討してください。

エラーをログに記録する

デバッグと確認を容易にするため、エラーはすべてログに記録しておく必要があります。少なくとも、リクエスト ID、エラーが発生したオペレーション、エラー自体は記録します。他には、お客様 ID、API サービス、往復リクエスト遅延、試行回数、未処理の SOAP リクエストとレスポンスなどの情報を記録します。

クライアント ライブラリには、SOAP をログに記録する組み込み機能のほか、requestId ヘッダーを取得する機能も用意されています。

アプリの問題を検出して対処できるよう、API エラーの傾向を確認するようにします。ここでは、独自のソリューションの構築、またはログを使用したインタラクティブなダッシュボードの作成やアラートの自動送信を可能にする市販ツールの導入を検討してください。

その他

テスト アカウントを使用する

テスト アカウントは、実際には広告を配信しない AdWords アカウントです。テスト アカウントを使用すると、AdWords API をテストしたり、アプリの接続、キャンペーン管理ロジック、その他の処理が期待どおりに動作するかどうかをテストしたりできます。テスト アカウントでは開発者トークンの承認は不要なため、開発者トークンをリクエストした後、アプリがまだ審査されていなくても、すぐに AdWords API を使った開発を開始できます。

ターゲット候補をバッチ処理する

TargetingIdeaService を使用してターゲット候補を生成する場合、TargetingIdeaSelectorRequestType には IDEASSTATS のどちらも使用できます。STATS リクエストは既知のキーワードの統計情報を取得するのに使用できます。複数のキーワードについて統計情報を取得するには、RelatedToQuerySearchParameter にキーワードを指定して単一のリクエストにまとめます。 各キーワードに対して 1 つの TargetingIdea が返されるため、キーワードごとに別々のリクエストを行うよりも効率的です。

フィードバックを送信...

ご不明な点がありましたら、Google のサポートページをご覧ください。