エラーは大まかに以下のカテゴリに分けられます。
- 認証
- 再試行可能
- 検証
- 同期関連
これらのカテゴリはすべてのエラーを網羅しているわけではなく、エラーによっては複数のカテゴリに当てはまるものもありますが、アプリケーションのエラー処理を構築する第一歩として役に立ちます。特定のエラーについて詳しくは、一般的なエラーをご覧ください。
認証エラー
認証とは、アプリケーションがユーザーに代わって Google 広告にアクセスして処理する権限を、ユーザーが許可することです。認証は、OAuth2 フローによって生成される認証情報を通じて管理されます。
認証エラーの制御不能な原因で最も多いのは、認証したユーザーがアプリケーションに許可した代理権限を取り消した場合です。たとえば、アプリケーションでクライアントのアカウントを管理する際に、独立したクライアント別に Google 広告アカウントを管理し、クライアントごとに認証を受けている場合、各クライアントはアプリケーションのアクセス権をいつでも取り消すことができます。アクセスが取り消されたタイミングによっては、API が AuthenticationError.OAUTH_TOKEN_REVOKED エラーを直接返す場合と、クライアント ライブラリの組み込みの認証情報オブジェクトがトークン取り消しの例外をスローする場合があります。いずれの場合も、アプリケーションにクライアント用の UI があれば、OAuth2 フローを再起動してアプリケーションの代理権限を再確立するよう、クライアントに求める設計にする方法が考えられます。
再試行可能なエラー
TRANSIENT_ERROR や INTERNAL_ERROR などの一部のエラーは一時的な問題を示している可能性がありますが、しばらく一時停止してからリクエストを再試行することで解決できる場合があります。
ユーザーが開始するリクエストの場合、すぐに UI にエラーを表示し、ユーザーに再試行する選択肢を示す方法が考えられます。また、最初はアプリケーションでリクエストを自動的に再試行し、再試行の最大回数に達するか、一定の合計ユーザー待機時間が経過して初めて UI にエラーを表示するという方法も考えられます。
バックエンドで開始されるリクエストの場合、アプリケーションでリクエストを最大回数まで自動的に再試行する必要があります。
リクエストの再試行では、指数バックオフ ポリシーを使用します。たとえば、最初の再試行の前に 5 秒待機した場合、2 回目の前には 10 秒、3 回目には 20 秒待機するようにします。指数バックオフは、API の過剰な呼び出しを防ぐことに役立ちます。
検証エラー
検証エラーは、オペレーションへの入力が受け入れられないことを示します。たとえば、PolicyViolationError、DateError、DateRangeError、StringLengthError、UrlFieldError です。
検証エラーは、ユーザーが開始するリクエストで入力内容が無効であった場合に最も多く発生します。この場合、受け取った API エラーに応じて、適切なエラー メッセージをユーザーに示す必要があります。API を呼び出す前にユーザー入力のよくある間違いを検証することで、アプリケーションの応答時間を短縮し、より効率的に API を使用することもできます。バックエンドで開始されたリクエストの場合、失敗したオペレーションをキューに追加し、オペレーターが確認できるようにする方法が考えられます。
同期関連のエラー
Google 広告アプリケーションの多くにはローカル データベースがあり、Google 広告オブジェクトが保存されています。この手法には、ローカル データベースと Google 広告にある実際のオブジェクトが同期しなくなる場合があるという問題があります。たとえば、ユーザーが Google 広告で直接広告グループを削除しても、アプリケーションとローカ ルデータベースがその変更を認識せず、広告グループが存在するかのように API 呼び出しを発行し続けます。これらの同期の問題は、DUPLICATE_CAMPAIGN_NAME、DUPLICATE_ADGROUP_NAME、AD_NOT_UNDER_ADGROUP、CANNOT_OPERATE_ON_REMOVED_ADGROUPAD などのさまざまなエラーとして現れる可能性があります。
ユーザーが開始するリクエストの場合、同期に問題がある可能性があることをユーザーに警告した直後に、Google 広告オブジェクトの関連クラスを取得してローカル データベースを更新するジョブを開始し、ユーザーに UI を更新するよう促す方法があります。
バックエンドで開始されるリクエストの場合、エラーによっては、提供される情報を使用して、アプリケーションが自動的にローカル データベースの増分を修正できます。たとえば、CANNOT_OPERATE_ON_REMOVED_ADGROUPAD は、アプリがその広告をローカル データベースで削除済みとしてマークするようにします。この方法で処理できないエラーの場合、アプリケーションでより包括的な同期ジョブを開始するか、オペレーターが確認できるようエラーをキューに追加する方法が考えられます。