エラーを解決する | Drive API和訳 [アプリ・開発]

この記事は、Google Drive™ APIに関する記事を和訳したものです。
原文: Resolve errors
元記事のライセンスは CC-BYで、この和訳記事のライセンスは CC-BYです。
自己責任でご利用ください。
和訳した時期は 2019年6月ころです。

Drive APIは、2つのレベルのエラー情報を返します:

ヘッダ内の、HTTPエラーコードおよびメッセージ
エラーを処理する方法を決定するに役立つ可能性がある追加の詳細を伴う、レスポンスボディ内の JSONオブジェクト

このページの残りの部分では、Driveエラーの参照を提供します、それは、あなたのアプリにてそれらを処理する方法についての幾つかのガイダンスを伴います。

エラーを処理する: 取り消された、あるいは、無効なトークン

Google Driveアプリは、Drive APIを呼び出すとき、HTTP 401あるいは HTTP 403レスポンスを返す APIについて考慮する必要があります。これらのエラーは、次のいずれかを示している可能性があります:

トークンの有効期限。
トークンが失効している。これは、アクセストークンおよびリフレッシュトークンの両方が動作を停止することを引き起こすでしょう。
トークンが、必要とされるスコープのために承認されていない。
リクエストが、OAuth 2.0プロトコルを用いて正しく承認されていない。

トークンの有効期限は、資格情報を更新することによって処理することができます。もしその呼び出しが "Invalid Credentials" エラーによって失敗したならば、問題は恐らくユーザがアクセスを取り消したことです。失効したアクセスおよびトークンの有効期限以外のすべての問題の場合、最善策は、アクセスを再び付与するために、OAuthダイアログを介してユーザをリダイレクトすることです。

APIエラーを処理する

Driveアプリは、REST APIを使用するときに遭遇するかもしれないすべてのエラーを、捕捉し、処理する必要があります。 APIによって返されるエラーのリファレンスについては、APIエラーを処理するを参照してください。

エラーおよび推奨されるアクション

このセクションでは、リストされたそれぞれのエラーの完全な JSON表現を見つけ、それを処理するために推奨されるアクションを示します。

400: Bad request

ユーザエラー。これは、必須フィールドあるいはパラメータが提供されていない、指定された値が無効である、あるいは、提供されるフィールドの組み合わせが無効であることを意味しています。

このエラーは、Driveのアイテムに重複した親を追加しようとしたときにスローされる可能性があります。さらには、ディレクトリグラフ内にサイクルを作成する親を追加しようとするときスローされる可能性があります。

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "badRequest",
        "message": "Bad Request"
      }
    ],
    "code": 400,
    "message": "Bad Request"
  }
}

400: Invalid sharing request

無効な共有リクエストは、幾つかの理由で発生する可能性があります。次の例は、一般的な発生であり、可能性のあるエラーの完全なリストではありません。

共有は成功しましたが、通知電子メールが正しく配信されませんでした。

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "invalidSharingRequest",
        "message": "Bad Request. User message: \"Sorry, the items were successfully shared but emails could not be sent to email@domain.com.\""
      }
    ],
    "code": 400,
    "message": "Bad Request"
  }
}

推奨されるアクション: 送信および受信ユーザの両方が中断していないこと、および電子メールを送信および受信できることをチェックしてください。

ACLの変更が、このユーザには許可されていません。

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "invalidSharingRequest",
        "message": "Bad Request. User message: \"ACL change not allowed.\""
      }
    ],
    "code": 400,
    "message": "Bad Request"
  }
}

推奨されるアクション: ファイルが所属する G Suite domainの共有設定をチェックしてください。

401: Invalid credentials

無効な承認ヘッダ。使用しているアクセストークンが、失効している、あるいは無効です。

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "authError",
        "message": "Invalid Credentials",
        "locationType": "header",
        "location": "Authorization",
      }
    ],
    "code": 401,
    "message": "Invalid Credentials"
  }
}

推奨されるアクション: 寿命の長いリフレッシュトークンを使用して、アクセストークンをリフレッシュします。もしこれが失敗したならば、Google Driveを用いてあなたのアプリを承認するに記載されているように、OAuthのフローにユーザを誘導してください。

403: Daily limit exceeded

あなたのプロジェクトの Courtesy APIの制限に達した。

{
  "error": {
    "errors": [
      {
        "domain": "usageLimits",
        "reason": "dailyLimitExceeded",
        "message": "Daily Limit Exceeded"
      }
    ],
    "code": 403,
    "message": "Daily Limit Exceeded"
  }
}

推奨されるアクション: プロジェクトの Quotasタブの下にある Google API Consoleにて、追加的なクォータをリクエストしてください。

403: User rate limit exceeded

ユーザごとの制限に到達しました。これは、Developer Consoleから制限された、あるいは、Driveバックエンドから制限されたのかもしれません。

{
 "error": {
  "errors": [
   {
    "domain": "usageLimits",
    "reason": "userRateLimitExceeded",
    "message": "User Rate Limit Exceeded"
   }
  ],
  "code": 403,
  "message": "User Rate Limit Exceeded"
 }
}

推奨されるアクション:

Developer Consoleプロジェクトにて、ユーザごとのクォータを増やします。
もし 1人のユーザが G Suiteドメインの多くのユーザに代わって多くのリクエストを行っているならば、権限移譲を伴う Service Accountを考慮してください(quotaUserパラメータをセットしている)。
リクエストをリトライするために、指数バックオフを使用します。

403: Rate limit exceeded

ユーザが Google APIの最大リクエスト率に達しました。制限はリクエストの種類によって異なります。

{
 "error": {
  "errors": [
   {
    "domain": "usageLimits",
    "message": "Rate Limit Exceeded",
    "reason": "rateLimitExceeded",
   }
  ],
  "code": 403,
  "message": "Rate Limit Exceeded"
 }
}

推奨されるアクション:

リクエストをバッチします。
リクエストをリトライするために、指数バックオフを使用します。

403: Sharing rate limit exceeded

ユーザが共有の制限に達しました。これは、しばしば、電子メールの制限とリンクします。

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "message": "Rate limit exceeded. User message: \"These item(s) could not be shared because a rate limit was exceeded: filename",
    "reason": "sharingRateLimitExceeded",
   }
  ],
  "code": 403,
  "message": "Rate Limit Exceeded"
 }
}

推奨されるアクション:

たくさんのファイルを共有するとき、電子メールを送信しない。
もし 1人のユーザが G Suiteドメインの多くのユーザに代わって多くのリクエストを行っているならば、共有するためのそれぞれのドキュメントの所有者を偽装するために、権限移譲を伴う Service Accountを考慮してください(quotaUserパラメータをセットしている)。

403: The user has not granted the app {appId} {verb} access to the file {fileId}

リクエストしているアプリがファイルの ACL上にありません。ユーザは、この Driveアプリを用いてファイルを明示的に開くことはありません。

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "appNotAuthorizedToFile",
        "message": "The user has not granted the app {appId} {verb} access to the file {fileId}."
      }
    ],
    "code": 403,
    "message": "The user has not granted the app {appId} {verb} access to the file {fileId}."
  }
}

推奨されるアクション: ピッカーを開き、ユーザにファイルを開くよう促す、あるいは、ユーザに、アプリを用いてファイルを開くことを Driveに指示させます。

403: The user does not have sufficient permissions for file {fileId}

ユーザがファイルへの書き込みアクセスを持っておらず、アプリがそのファイルを修正しようとしています。

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "insufficientFilePermissions",
        "message": "The user does not have sufficient permissions for file {fileId}."
      }
    ],
    "code": 403,
    "message": "The user does not have sufficient permissions for file {fileId}."
  }
}

推奨されるアクション: ファイルへの編集アクセスをリクエストするよう、ユーザに伝えます。また、files.getによって取得されたメタデータ内のユーザアクセスレベルをチェックし、権限がない時には、読み込み専用 UIを表示することもできます。

403: App with id {appId} cannot be used within the authenticated user's domain

ユーザのドメインのポリシーは、あなたのアプリによる Google Driveへのアクセスを許可していません。

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "domainPolicy",
        "message": "The domain administrators have disabled Drive apps."
      }
    ],
    "code": 403,
    "message": "The domain administrators have disabled Drive apps."
  }
}

推奨されるアクション: ドメインが、あなたのアプリが Drive内のファイルにアクセスできるようにしていないことを、ユーザに伝えます。彼らが、あなたのアプリのためにアクセスをリクエストするよう、ドメイン管理者にコンタクトすることを推奨します。

404: File not found: {fileId}

ユーザがファイルへの読み取りアクセスを持っていない、あるいは、ファイルが存在しません。

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "notFound",
        "message": "File not found {fileId}"
      }
    ],
    "code": 404,
    "message": "File not found: {fileId}"
  }
}

推奨されるアクション: 彼らがファイルへの読み取りアクセスを持っていない、あるいはファイルが存在しないことを、ユーザに伝えます。所有者に、ファイルのパーミッションを求めることをお勧めします。

429: Too many requests

ユーザが、与えられた時間内に、あまりに多くのリクエストを送信しました。

{
  "error": {
    "errors": [
      {
        "domain": "usageLimits",
        "reason": "rateLimitExceeded",
        "message": "Rate Limit Exceeded"
      }
    ],
    "code": 429,
    "message": "Rate Limit Exceeded"
  }
}

推奨されるアクション: リクエストをリトライするために、指数バックオフを使用します。

500: Backend error

リクエストの処理中に予期しないエラーが発生しました。

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "backendError",
    "message": "Backend Error",
   }
  ],
  "code": 500,
  "message": "Backend Error"
 }
}

推奨されるアクション: リクエストをリトライするために、指数バックオフを使用します。

エラーを解決するたために失敗したリクエストをリトライする

レート制限、ネットワークボリューム、あるいは応答時間に関連するエラーを処理するために、失敗したリクエストを時間を増加させながら定期的にリトライすることができます。例えば、失敗したリクエストを、1秒後、それから、2秒後、それから 4秒後にリトライするかもしれません。この方法は、指数バックオフと呼ばれ、帯域幅の使用量を改善し、並行環境内のリクエストのスループットを最大化します。

エラーの後、少なくとも 1秒後に、リトライ期間を開始します。もし試行されたリクエストが、リクエストを作成するといった変更を導入したならば、何も重複していないことを確認するためのチェックを追加します。無効な承認情報、あるいは、"file not found" エラーといった幾つかのエラーは、リクエストをリトライすることによって解決されません。