トラブルシューティング

AdWords API にアクセスするソフトウェアを作成していると、エラー メッセージが発生する場合があります。その原因としては、ソフトウェアのバグやユーザーからの無効な入力が考えられます。いずれにしても、そのエラーの原因を突き止めて、コードを修正したり、ユーザーによるエラーを処理するロジックを追加したりする必要があります。このガイドでは AdWords API のエラーをトラブルシューティングするためのヒントについて説明します。

ステップ 1: 問題を正しく特定する

トラブルシューティングの最初のステップは、問題の詳細な情報を収集することです。通常、AdWords API はエラー メッセージを SOAP フォールトとして報告します(XML 自体が WSDL で検証されていない場合を除きます)。このフォールトには faultstring のほかに、フォールトが発生した理由を詳細に説明する detail が含まれています。このフォールトが問題を特定するための最初のヒントになります。

<soap:Fault>
 <faultcode>soap:Server</faultcode>
 <faultstring>
  [EntityNotFound.INVALID_ID @ operations[0].operand.campaignId; trigger:'CampaignId: 123']
 </faultstring>
 <detail>
  <ApiExceptionFault xmlns="https://adwords.google.com/api/adwords/cm/v201802">
   <message>
    [EntityNotFound.INVALID_ID @ operations[0].operand.campaignId; trigger:'CampaignId: 123']
   </message>
   <ApplicationException.Type>ApiException</ApplicationException.Type>
   <errors xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="EntityNotFound">
    <fieldPath>operations[0].operand.campaignId</fieldPath>
    <fieldPathElements>
      <field>operations</field>
      <index>0</index>
    </fieldPathElements>
    <fieldPathElements>
      <field>operand</field>
    </fieldPathElements>
    <fieldPathElements>
      <field>campaignId</field>
    </fieldPathElements>
    <trigger>CampaignId: 123</trigger>
    <errorString>EntityNotFound.INVALID_ID</errorString>
    <ApiError.Type>EntityNotFound</ApiError.Type>
    <reason>INVALID_ID</reason>
   </errors>
  </ApiExceptionFault>
 </detail>
</soap:Fault>

大部分のクライアント ライブラリは、SOAP フォールトをカプセル化して例外をスローします。多くの SOAP ツールキットはこれと同じように動作します。通常、このような例外は、後で検討できるようにアプリケーション ログに記録されますので、トラブルシューティングを開始するときは、まずログを確認するとよいでしょう。多くの大きなアプリケーション(特に第三者のライブラリを使用しているもの)では、問題の解決に役立つ追加情報もログに記録される場合があります。Google のクライアント ライブラリでは、SOAP リクエストのログ記録をサポートしています。詳しくは、ご使用のライブラリの README を参照してください。

何が発生したのかを特定できたら、次にエラーの意味を理解する必要があります。

ステップ 2: エラーを調査する

エラーの調査では、必ず最初に一般的なエラーのドキュメントを確認してください。このドキュメントでは、デベロッパーがよく目にするエラーの大部分が取り上げられています。また、エラー メッセージ、関連する API リファレンス、エラーの回避方法と処理方法が説明されています。

一般的なエラーのドキュメントに問題のエラーについての説明がない場合は、リファレンス ドキュメントを参照して、エラー文字列を探してください。

一般的なエラーなどのドキュメントを参照した後で、さらに詳しい情報が必要な場合は、その他の詳細なリソースが役に立ちます。Google のフォーラムには、大勢の AdWords API デベロッパーが集い、API に関連する経験を共有しています。アプリケーションの問題をトラブルシューティングする場合、フォーラムを検索するとよいでしょう。おそらく、同じ問題を経験しているデベロッパーがいるはずです。どこにも記載されていないエラーに遭遇した場合は、そのエラーについてフォーラムに投稿してください。最後の手段として、インターネットでエラー メッセージを検索することもできます。

ブログ投稿がアプリケーションのトラブルシューティングの参考になる場合もあります。また、検証やアカウントの制限についての問題をトラブルシューティングするときは、AdWords ヘルプセンターが役に立ちます。AdWords API は、AdWords の主要サービスのルールや制限を引き継いでいます。

エラーの詳細を理解したら、次に根本的な原因を調べます。

ステップ 3: エラー メッセージの原因を調べる

ログに戻って、エラーの原因を調べます。多くのライブラリでは、役立つ情報がデバッグ単位や情報単位でログに記録されます。クライアント ライブラリでは、送受信された実際の SOAP メッセージをログに記録するかどうかを選択できます。SOAP レスポンスを確認してから、SOAP リクエストを調べて、考えられる原因を探します。一部の API エラー メッセージには、リクエスト内のエラーが発生した場所を示す fieldPath も含まれています。

場合によっては、アプリケーションから誤った情報が API に渡されていることがあります。デバッグの役に立つ対話型の開発環境(IDE)の利用を強くおすすめします。たとえば、Eclipse は無償のオープンソース IDE で、主に Java での開発に使用されますが、その他の言語用のプラグインもあります。IDE では、ブレークポイントを設定したり、コードを 1 行ごとにステップ実行したりできます。

SOAP リクエストがアプリケーションの入力と一致していることを再度確認します(たとえば、キャンペーンの名前がリクエストに到達していない場合、一致しません)。リクエストのフィールドを追加したり、削除したりするのもよいでしょう。AdWords API では、スパース アップデートがサポートされています。省略したフィールドは、API で無視されます。オブジェクトを取り出し、変更を加えて元に戻すアプリケーションの場合、アップデートをサポートしていないフィールドに書き込んでいる場合があります。Google のリファレンス ドキュメントを確認してください。ReadOnly と表示されているフィールドをリクエストに送信しないでください。

サポートを求める場合

問題をすべて自力で特定し解決できるとは限りません。フォーラムで質問して、大勢のデベロッパーに疑問点を公開すれば、同じ問題に遭遇したことのあるデベロッパーから助言を得られる場合があります。

サポートを求めるときは、できるだけ多くの情報を提供するよう心がけてください。たとえば、次のような項目を含めることをおすすめします。

  • 不要な情報を削除した SOAP XML リクエストとレスポンス - 開発者トークンや AuthToken などの機密情報は必ず削除してください。リクエストやレスポンスの構造を示すと、他の人がトラブルシューティングするのに役立ちます。
  • コード スニペット - 言語固有の問題や API の操作についてのサポートを求めている場合は、コードのスニペットを提供すると、行おうとしていることの説明に役立ちます。
  • RequestId - 本番環境での最近 8 日以内のリクエストであれば、この情報は、Google Developer Relations チームのメンバーがリクエストを探し出すのに役立ちます。可能であれば SOAP XML ログも含めることをおすすめします。SOAP XML ログは requestId が含まれているだけでなく、requestId 単独の場合よりも多くの情報を得られるからです。ランタイムやインタープリターのバージョンやプラットフォームなどの補足情報もトラブルシューティングの役に立ちます。

ステップ 4: 問題を修正する

問題を特定でき、解決方法が判明したら、実際に修正を加えて修正箇所をテストします。このとき、できればテスト アカウントを使用することをおすすめします。ただし、特定の本番用アカウントのデータにのみ起こるバグの場合には、本番環境でテストする必要があります。

次のステップ

問題の解決の過程で、コードを改良してこの問題の発生を未然に防ぐ方法がみつかる場合があります。Google では、クライアント ライブラリの開発時に単体テストを作成しており、デベロッパーの方にもそうすることをおすすめしています。テストを作成しておけば、バグレポートを受け取ってから対処するよりも簡単にバグを特定して修正することができます。

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

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