Boxアプリのデバッグ

​

体系的なアプローチ

1. 認証。アプリでアクセストークンを取得できますか? そのトークンは、使用している認証方式 (OAuth 2.0、JWT、またはクライアント資格情報許可) に適合したタイプですか?
2. 承認。トークンには、エンドポイントが必要とするスコープが含まれていますか? サービスアカウントやユーザーは、対象の項目にアクセスできますか?
3. リクエストの作成。URL、HTTPメソッド、ヘッダーの設定、および本文は、APIリファレンスで指定されている内容と完全に一致していますか?
4. サーバーのレスポンス。どのようなHTTPステータスコードとBoxエラーコードが返されましたか? 一過性のエラーであった場合、リクエストは正しく再試行されましたか?
5. ダウンストリームへの副次的影響。Webhookやワーカーから他のシステムを呼び出した場合、正常に実行されましたか?

​

APIレスポンスの調査

{
  "type": "error",
  "status": 403,
  "code": "access_denied_insufficient_permissions",
  "help_url": "/guides/api-calls/permissions-and-errors/common-errors/",
  "message": "Access denied - insufficient permission",
  "request_id": "abcdef123456"
}

​

再試行とタイムアウトの処理

​

再試行すべきレスポンス

​

ジッターによる指数バックオフの使用

import random, time

def backoff_seconds(attempt: int, base: float = 1.0, cap: float = 60.0) -> float:
    delay = min(cap, base * (2 ** attempt))
    return delay + random.uniform(0, delay * 0.1)

retry-after: 100

​

適切なリクエストタイムアウトの設定

​

安全な再試行の実施

• 分割アップロードの場合、既存のアップロードセッションを再利用し、影響を受けた部分のみを再アップロードします。を参照してください。
• 再試行した作成リクエストで409 item_name_in_useが返された場合、それが処理フローに合致するのであれば、実際の競合ではなく元のリクエストがすでに成功していると見なします。たとえば、POST /files/contentを再試行してitem_name_in_useが返された場合は、親フォルダを表示して、先ほどアップロードしようとしたファイルを探します。ほとんどの場合、レスポンスが失われる前に最初の試行は正常に保存されています。
• GET以外のリクエストを再試行する際には、再試行の前にそのリソースがすでに存在していることを確認してください。たとえば、ファイルを再アップロードする前に、宛先フォルダに対してGET /folders/:id/itemsを呼び出し、ファイル名とサイズを比較します。コラボレーションを再作成する前に、GET /folders/:id/collaborationsを呼び出します。

​

App Diagnosticsツールの使用

• Boxが返したHTTPステータスコード。
• APIリクエストの継続時間。
• API Request ID — これをBoxサポートに送れば、対象のリクエストを確認できます。
• リソース、サブリソース、HTTPメソッド、およびタイムスタンプ。

• リクエストがBoxに届いたかどうかを確認する。
• ユーザー自身のログに記録されなかった、失敗した呼び出しのリクエストIDを特定する。
• 呼び出し量を予想されるパターンと比較する (例: 再試行が急増していないかを確認する)。
• Boxサポートチームに対し、調査に必要な正確な呼び出し情報を提供する。

​

Boxサポートに提供するリクエストIDの取得

• エラーレスポンス本文に含まれるrequest_idの値。
• 失敗した呼び出しのbox-request-idレスポンスヘッダー。
• App DiagnosticsレポートのAPI Request ID列。

​

よくあるシナリオのデバッグ

​

認証およびトークンの問題

​

権限およびアクセスの問題

​

レート制限と容量の問題

​

Webhookの問題

​

Boxステータスページの確認

​

次の手順

• で、エラーコードの詳細なリストを確認します。
• の設定に合わせて、再試行ポリシーを調整します。
• 次回に予期せぬエラーが発生した際は、を実行してください。