Excel API のエラー処理
この記事では、API を介して送信された要求が失敗したときに Microsoft Graph の Excel API によって返されるエラーを処理するための一般的な手順と提案について説明します。
エラー応答の種類
Microsoft Graph の Excel API は、2 種類のエラーを返します。 1 つは、次のような通常のエラー応答です。
HTTP/1.1 <HTTP status code>
Content-type: application/json
Retry-After: <Cooldown duration in seconds> (optional)
{
"error": <Error object>
}
2 つ目は、次の例のように、HTTP 状態コードとfailed操作状態を200 OK応答本文で返すことができる実行時間の長い操作パターンです。
HTTP/1.1 200 OK
Content-type: application/json
{
"status": "failed",
"error": <Error object>
}
どちらのエラー応答でも、error オブジェクトは次の構造を持ちます。
注:
エラー応答は、エラー応答に対する OData v4 仕様の定義に従います。
{
"code": "string",
"message": "string",
"innerError": { "@odata.type": "odata.error" }
}
innerError オブジェクトには、より具体的な追加のエラー コードを含む、より多くの innerError オブジェクトが再帰的に含まれる場合があります。 たとえば、エラー オブジェクトには、次に示すように、第 2 レベルのエラー コードとメッセージに、より詳細なエラー情報が含まれている場合があります。
{
"code": "Top-level error code",
"message": "Top-level error message",
"innerError": {
"code": "Second-level error code",
"message": "Second-level error message",
"innerError": { "@odata.type": "odata.error" }
}
}
エラー応答を処理する手順
Microsoft Graph クライアントは、次の手順を使用して、Excel API で発生するエラーを処理することが期待されます。
1. 実行時間の長い操作エラーかどうかを判断する
エラーを処理する前に、最初の手順は、エラー応答が実行時間の長い操作パターンまたは通常のパターンからのかどうかを判断することです。 実行時間の長い操作エラーは、応答本文で 200 OK HTTP 状態コードと failed 操作状態を返します。 通常のエラー応答では、対応する HTTP エラー状態コードが返されます。
2. 第 2 レベルのエラー コードを解析する
実行時間の長い操作パターンと通常のパターンの両方で、クライアントは最初に必要な第 2 レベルのエラー コードを解析し、指示に従って処理する必要があります。 必要に応じて、クライアントは他の第 2 レベルのエラー コードを処理することも、 最上位のエラー コード または 状態コードにフォールバックすることもできます。
エラー コードでは大文字と小文字が区別されません。
必要な第 2 レベルのエラー コード
次の表に、Microsoft Graph クライアントが処理する必要がある 2 番目のレベルのエラー コードの手順を示します。 サービスは、いつでも新しいエラー コードを追加する場合があります。
| コード | 手順 |
|---|---|
accessConflict |
失敗した要求は、ブックにアクセスしている他のクライアントと競合します (たとえば、別のクライアントがブックを編集のためにロックしています)。 競合が解決されるまで、Microsoft Graph クライアントは失敗した要求を再送信する必要はありません。 エンド ユーザーは、Excel Online で同じ操作を手動で実行して、競合の詳細を取得できます。 |
badRequestUncategorized |
失敗した要求に指定されていないエラーが見つかりました。 Microsoft Graph クライアントは、失敗した要求を再送信する必要はありません。 |
conflictUncategorized |
失敗した要求は、特定のサーバーの状態と競合します。 競合が解決されるまで、Microsoft Graph クライアントは失敗した要求を再送信する必要はありません。 エンド ユーザーは、Excel Online で同じ操作を手動で実行して、競合の詳細を取得できます。 |
forbiddenUncategorized |
失敗した要求は許可されません。 Microsoft Graph クライアントは、失敗した要求を再送信する必要はありません。 エンド ユーザーは、Excel Online で同じ操作を手動で実行して、制限の詳細を取得できます。 |
gatewayTimeoutUncategorized |
制限時間内にサービスが要求を完了できませんでした。 |
internalServerErrorUncategorized |
不明なエラーが発生しました。 Microsoft Graph クライアントは、失敗した要求を再送信する必要はありません。 失敗した要求でセッションが指定されている場合、セッションへのそれ以上のアクセスも予期されません。 |
invalidSessionAccessConflict |
要求で指定されたセッションは、ブックにアクセスしている他のクライアントと競合するため無効です (たとえば、別のクライアントがブックを編集のためにロックしている場合など)。 失敗した要求で指定されたセッションへのそれ以上のアクセスは予期されません。 競合が解決されるまで、同じ createSession 要求を使用してセッションを再作成することは予期されません。 別の createSession 要求を使用してセッションを再作成すると、成功する場合と失敗する可能性があります。 エンド ユーザーは、Excel Online で同じ操作を手動で実行して、競合の詳細を取得できます。 |
invalidSessionAuthentication |
認証エラーのため、要求で指定されたセッションが無効です。 失敗した要求で指定されたセッションへのそれ以上のアクセスは予期されません。 適切な認証情報が提供されるまで、同じ createSession 要求を使用してセッションを再作成することは予期されません。 |
invalidSessionNotFound |
ブックが見つからないため、要求で指定されたセッションが無効です。 失敗した要求で指定されたセッションへのそれ以上のアクセスは予期されません。 同じ createSession 要求を使用してセッションを再作成することは想定されていません。 |
invalidSessionReCreatable |
要求で指定されたセッションが存在しないか、一時的なエラーが原因で無効です。 Microsoft Graph クライアントは、セッションの再作成と作業の再開を試みることができます。 失敗した要求で指定されたセッションへのそれ以上のアクセスは予期されません。 |
invalidSessionRestricted |
要求で指定されたセッションは、サービスの構成または制限のために無効です。 失敗した要求で指定されたセッションへのそれ以上のアクセスは予期されません。 要求をブロックする制限または構成が変更されるまで、同じ createSession 要求を使用してセッションを再作成することは予期されません。 別の createSession 要求を使用してセッションを再作成すると、成功する場合と失敗する可能性があります。 エンド ユーザーは、Excel Online で同じ操作を手動で実行して、制限の詳細を取得できます。 |
invalidSessionUnexpected |
予期しない問題が発生したため、要求で指定されたセッションが無効です。 失敗した要求で指定されたセッションへのそれ以上のアクセスは予期されません。 同じ createSession 要求を使用してセッションを再作成することは想定されていません。 別の createSession 要求を使用してセッションを再作成すると、成功する場合と失敗する可能性があります。 |
invalidSessionUnsupportedWorkbook |
ブックにサポートされていない機能が含まれているか、サイズ制限を超えているため、要求で指定されたセッションが無効です。 通常、サポートされていない要素は、ブックにアクセスする別のクライアントによって導入されます。 失敗した要求で指定されたセッションへのそれ以上のアクセスは予期されません。 サポートされていない要素が削除されるまで、同じ createSession 要求を使用してセッションを再作成することは予期されません。 別の createSession 要求を使用してセッションを再作成すると、成功する場合と失敗する可能性があります。 エンド ユーザーは、Excel Online で同じ操作を手動で実行して、サポートされていない要素の詳細を取得したり、ブックがサポートされる Excel Desktop を使用したりできます。 |
methodNotAllowedUncategorized |
要求で指定された HTTP メソッドは、リソースでは許可されません。 Microsoft Graph クライアントは、失敗した要求を再送信する必要はありません。 |
notFoundUncategorized |
要求されたリソースが見つかりません。 Microsoft Graph クライアントは、失敗した要求を再送信する必要はありません。 |
notImplementedUncategorized |
要求された機能は現在実装されていません。 Microsoft Graph クライアントは、失敗した要求を再送信する必要はありません。 |
payloadTooLargeUncategorized |
要求ペイロードがサイズ制限を超えています。 Microsoft Graph クライアントは、失敗した要求を再送信する必要はありません。 |
serviceUnavailableUncategorized |
サービスが一時的に使用できないか、過負荷になっています。 Microsoft Graph クライアントは、指定されたクールダウン期間が経過するまで、失敗した要求を再送信することは想定されていません。 |
tooManyRequestsUncategorized |
失敗した要求が特定の頻度制限を超えています。 Microsoft Graph クライアントは、指定されたクールダウン期間が経過するまで、失敗した要求を再送信することは想定されていません。 調整を減らすベスト プラクティスについては、「調整 エラーを減らす」を参照してください。 |
transientFailure |
一時的なエラーが原因で要求が失敗しました。 Microsoft Graph クライアントは、指定されたクールダウン期間が経過するまで、失敗した要求を再送信することは想定されていません。 |
unauthorizedUncategorized |
リソースに必要な認証情報が見つからないか無効です。 Microsoft Graph クライアントは、失敗した要求を再送信する必要はありません。 |
unsupportedWorkbook |
要求が失敗しました。 ブックにサポートされていない機能が含まれているか、サイズ制限を超えています。 Microsoft Graph クライアントは、サポートされていない要素が削除されるまで、失敗した要求を再送信することは想定されていません。 |
注:
通常のパターンの場合、失敗した要求は応答に対応する要求として定義されます。 実行時間の長い操作パターンの場合、失敗した要求は失敗した操作をトリガーする要求です。
オプションの 2 番目のレベルのエラー コードの例
次の表に、各エラー コードの対応する処理手順を含む、省略可能な 2 番目のレベルのエラー コードの例を示します。 サービスは、いつでも新しいエラー コードを追加する場合があります。
| コード | 手順 |
|---|---|
accessDenied |
要求された操作 (たとえば、ロックされたセルへの変更の実行) を実行することはできません。 Microsoft Graph クライアントは、失敗した要求を再送信する必要はありません。 |
filteredRangeConflict |
フィルター処理された範囲と競合するため、操作は失敗しました。 Microsoft Graph クライアントは、失敗した要求を再送信する必要はありません。 |
generalException |
要求の処理中に内部エラーが発生しました。 Microsoft Graph クライアントは、失敗した要求を再送信する必要はありません。 |
insertDeleteConflict |
試行された挿入操作または削除操作で競合が発生しました。 Microsoft Graph クライアントは、失敗した要求を再送信する必要はありません。 エンド ユーザーは、Excel Online で同じ操作を手動で実行して、競合の詳細を取得できます。 |
invalidArgument |
引数が無効であるか、見つからないか、正しくない形式です。 Microsoft Graph クライアントは、失敗した要求を再送信する必要はありません。 |
invalidReference |
この参照は、現在の操作に対して無効です。 Microsoft Graph クライアントは、失敗した要求を再送信する必要はありません。 |
itemAlreadyExists |
作成中のリソースはすでに存在しています。 Microsoft Graph クライアントは、失敗した要求を再送信する必要はありません。 |
itemNotFound |
要求されたリソースは存在しません。 Microsoft Graph クライアントは、失敗した要求を再送信する必要はありません。 |
methodNotAllowed |
要求で指定された HTTP メソッドは、リソースでは許可されません。 Microsoft Graph クライアントは、失敗した要求を再送信する必要はありません。 |
nonBlankCellOffSheet |
ワークシートの末尾から空でないセルをプッシュするため、新しいセルを挿入できません。 Microsoft Graph クライアントは、失敗した要求を再送信する必要はありません。 エンド ユーザーは、行または列を削除して、コンテンツを挿入するスペースを作成してから、もう一度やり直すことができます。 |
rangeExceedsLimit |
範囲内のセル数が、サポートされている最大数を超えています。 Microsoft Graph クライアントは、より小さい範囲のサイズで要求を送信しようとすることができます。 詳細については、「 Office アドインのリソース制限とパフォーマンスの最適化」を参照してください。 |
requestAborted |
要求は実行時に中止されました。これは通常、ブック内の関数からの長時間の計算が原因でした。 Microsoft Graph クライアントは、失敗した要求を再送信する必要はありません。 |
unsupportedOperation |
試行中の操作はサポートされていません。 Microsoft Graph クライアントは、失敗した要求を再送信する必要はありません。 |
注:
通常のパターンの場合、失敗した要求は応答に対応する要求として定義されます。 実行時間の長い操作パターンの場合、失敗した要求は失敗した操作をトリガーする要求です。
3. 最上位のエラー コードを解析する
既知の第 2 レベルのエラー コードが見つからない場合は、最上位レベルのエラーに関する説明に従う必要があります。 最上位のエラー コードは状態コードにバインドされ、対応する状態コードに従ってアクションを実行できます。 最上位のエラー コードとメッセージの詳細については、「 エラー コードとメッセージ」を参照してください。
4. 状態コードを解析する
通常のパターンでは、既知の第 2 レベルのエラー コードまたは最上位のエラー コードが見つからない場合は、HTTP 状態コードに従ってアクションを実行する必要があります。
5. エラー回復のクールダウン
通常のパターンの応答の一部では、ヘッダーを介して Retry-After 回復クールダウン期間が秒単位で提供される場合があります。 復旧のクールダウン期間が存在する場合、Microsoft Graph クライアントは、指定した期間が経過する前にフォローアップ要求を送信することは想定されません。 ヘッダーと調整に関連する Retry-After ベスト プラクティスについては、「 調整エラーを減らす」を参照してください。
診断情報
前の手順で使用しなかった応答のすべての内容は、診断目的でのみ使用されます (メッセージ フィールドの文字列を含む)。 これらのコンテンツは予告なく変更される可能性があるため、これらのコンテンツに依存することはお勧めしません。
特殊なケース処理
セッションフル要求の場合、既知の第 2 レベルのエラー コードが見つかったときにまたは503/serviceUnavailableエラーが発生502/badGatewayした場合は、対応する手順に従います。それ以外の場合は、セッションを直接再作成する必要があります。