例外処理と調査方法

Kii Cloud SDK の API には、呼び出しによって例外が発生するものがあります。ここでは、例外への対処の方法や障害の調査方法の概略を示します。

サンプルコードでの記載
詳細情報の取得
API 共通のエラー
各種ツールによる障害の調査

サンプルコードでの記載

本ガイドのサンプルコードでは、エラーハンドリングの必要箇所のみを示し、詳細（メッセージの出力やエラーからの回復処理など）は省略しています。

たとえば、新規ユーザー作成の解説では、次のようなサンプルコードを扱っています。

ブロッキング API

ブロッキング API では NSError オブジェクトのポインタを渡すと、発生したエラーの情報が戻ります。nil 以外の場合はエラーの発生を意味します。

Swift:

let user = KiiUser(username: "user_123456", andPassword: "123ABC")
do{
  try user.performRegistrationSynchronous()
} catch let error as NSError {
  // Handle the error.
  return
}

Objective-C:

NSError *error = nil;
KiiUser *user = [KiiUser userWithUsername:@"user_123456"
                              andPassword:@"123ABC"];
[user performRegistrationSynchronous:&error];
if (error != nil) {
  // Handle the error.
  return;
}

ノンブロッキング API

ノンブロッキング API で問題が発生すると、コールバックメソッドの引数としてエラーオブジェクトが渡されます。問題が発生しない場合、エラーオブジェクトは nil となります。

Swift:

let user = KiiUser(username: "user_123456", andPassword: "123ABC")
user.performRegistration { (user :KiiUser?, error : Error?) -> Void in
  if (error != nil) {
    // Handle the error.
    return
  }
}

Objective-C:

KiiUser *user = [KiiUser userWithUsername:@"user_123456"
                              andPassword:@"123ABC"];
[user performRegistrationWithBlock:^(KiiUser *user, NSError *error) {
  if (error != nil) {
    // Handle the error.
    return;
  }
}];

詳細情報の取得

NSError では、エラーの詳細情報を取得できる場合があります。クライアント SDK は、REST API 経由で Kii Cloud に接続します。サーバーからエラーが返された場合、その情報を NSError のプロパティを通して取得することができます。詳細情報は、特に開発時において問題の原因を特定する作業に役立ちます。

たとえば、ユーザー登録でユーザー "user_123456" がすでに登録されていた場合、以下のコードを実行すると、ユーザーの重複によってエラーとなります。この場合に取得できる詳細情報は次のとおりです。

Swift:

let user = KiiUser(username: "user_123456", andPassword: "123ABC")

do{
  try user.performRegistrationSynchronous()
} catch let error as NSError {
  // Handle the error.

  // Print the error code.
  print("Error code : \(error.code) ")
  // Print the error description.
  print("Error userInfo \(error.userInfo["description"]) ")
  // Print the HTTP status.
  print("Error HTTP status : \(error.kiiHttpStatus()) ")
  // Print the error summary.
  print("Error summary : \(error.kiiErrorSummary()) ")
  // Print the error message from the server.
  print("Error Server error message : \(error.kiiErrorMessage()) ")
  return
}

Objective-C:

NSError *error = nil;
KiiUser *user = [KiiUser userWithUsername:@"user_123456"
                              andPassword:@"123ABC"];
[user performRegistrationSynchronous:&error];
if (error != nil) {
  // Handle the error.

  // Print the error code.
  NSLog(@"Error code : %ld", (long)error.code);
  // Print the error description.
  NSLog(@"Error userInfo : %@", error.userInfo[@"description"]);
  // Print the HTTP status.
  NSLog(@"Error HTTP status : %@", error.kiiHttpStatus);
  // Print the error summary.
  NSLog(@"Error summary : %@", error.kiiErrorSumary);
  // Print the error message from the server.
  NSLog(@"Error Server error message : %@", error.kiiErrorMessage);
  return;
}

Error code : 503
Error description : Duplicate entry exists
Error HTTP status : 409
Error summary : USER_ALREADY_EXISTS
Error Server message : User with loginName user_123456 already exists

この例はユーザー重複が発生した場合の実行結果です。記載されているすべてのエラー情報はすべての状況で常に取得できるとは限らないため、プログラムから利用する場合は nil 等の応答も想定してください（たとえば、クライアント SDK 内でエラーと判断された場合、REST API 関連は nil となります）。

code プロパティ

KiiError クラスで定められたエラーコードを返します。たとえば、ユーザーが登録済みの場合、503（Duplicate entry exists）となります。

一部の API では 0 を返します。
userInfo プロパティの description

エラーの原因を示すエラーメッセージを返します。
kiiHttpStatus プロパティ

クライアント SDK の内部で呼び出した REST API の HTTP ステータスコードを取得できます。HTTP ステータスコードをプログラムで積極的に使用することはまれですが、詳細はメソッドに対応する REST API の詳細ドキュメントで確認できます。
kiiErrorSummary プロパティ

REST API の結果に含まれるエラーコードです。プログラム内でエラーの詳細原因から何か処理を振り分けたい場合、この戻り値の文字列を使用できます。
kiiErrorMessage プロパティ

REST API を呼び出した結果、応答のメッセージに含まれるエラーの詳細情報です。開発者が見て、内容を判断することを想定しています。

サポートに問い合わせを行う際には、これらの情報も提示することをおすすめします。

エラーの原因によってプログラムを制御したい場合、iOS では code プロパティの値を利用することをおすすめします。code プロパティが 0 を返した場合、kiiErrorSummary や kiiHttpStatus プロパティを参照することで制御できます。

API 共通のエラー

リフレッシュトークンや負荷集中時のエラーなど、API に依存せず、共通して発生するエラーがあります。

アクセストークンのリフレッシュエラー

アクセストークンのリフレッシュ機能を使用する設定にした場合、アプリ全体の設計として [KiiError codeRefreshTokenFailed] エラーへの対処方法を検討しておくことをおすすめします。

リフレッシュ時のエラーへの対処に示すとおり、KiiError.codeRefreshTokenFailed() エラーを受け取った場合は、アプリ側でユーザー名とパスワードを使った再ログイン処理が必要な状態になっています。エラーに適切に対処するには、初期画面に戻る遷移や、再ログイン画面を提示する処理などが必要です。これらの処理は、ネットワークアクセスを伴う API すべてで共通するため、事前に対処方法を検討しておくのが適切です。

負荷集中時のエラー

サーバーに対して、一定時間内に通常の負荷を大きく超えるアクセスが発生した場合、そのアプリケーションでは API がエラーを返します。この制限値は、利用契約に基づいてアプリケーションごとに定められます。

この制限値には余裕があるため、通常の運用負荷の変動では問題なく動作する設計ですが、例えば特定の時刻にアクティブユーザーが一斉にリクエストを行うような機能はエラーの発生につながります。

上限に達した場合、各 API はエラーを返します。この際、kiiHttpStatus プロパティから取得できる HTTP ステータスは 429 です。その他のプロパティからは有効な値を取得できません。

通常、モバイルアプリでは、このエラーをサーバーでの想定外エラーとして処理できますが、輻輳を防止するため、API の再試行は避けるように実装してください。

各種ツールによる障害の調査

モバイルアプリの側で例外処理を行うのと同時に、Kii Cloud のいくつかの機能によって問題の原因を調査できます。

開発者ログ

開発者ログには、API を呼び出したときのエラー情報が記録されます。

開発工程での問題発生時や、アプリ公開後のトラブルの調査で詳細な情報が必要になった際は、開発者ログの閲覧の情報をご覧ください。

たとえば、上記のユーザー重複の場合、開発者ログには以下のような情報が出力されます。

2015-04-21T11:45:11.783+09:00 [ERROR] user.register description:User registration failed userID: login-name:user_123456 email-address:user_123456@example.com phone-number:+819012345678 exception:User with loginName user_123456 already exists

データブラウザ

データブラウザを使って、プログラムから書き込まれた値が正しく更新されていることを確認できます。詳細は、データ、ユーザー、グループの確認と更新をご覧ください。