例外処理と調査方法

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

サンプルコードでの記載
詳細情報の取得
負荷集中時のエラー
各種ツールによる障害の調査

サンプルコードでの記載

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

たとえば、新規ユーザー作成の解説では、次のようなサンプルコードを扱っています。API で問題が発生すると、failure として定義されたコールバック関数が呼び出されたり、Promise の catch ブロックが動作したりします。

var user = KiiUser.userWithUsername("user_123456", "123ABC");
user.register().then(
  function(theUser) {
    // Do something.
  }
).catch(
  function(error) {
    var theUser = error.target;
    var errorString = error.message;
    // Handle the error.
  }
);

var user = KiiUser.userWithUsername("user_123456", "123ABC");
user.register({
  success: function(theUser) {
    // Do something.
  },
  failure: function(theUser, errorString) {
    // Handle the error.
  }
});

詳細情報の取得

JavaScript では、コールバック関数が呼び出された際、上記サンプルコードの errorString のように、エラーメッセージが文字列として渡されます。

クライアント SDK は、REST API 経由で Kii Cloud のサーバーに接続します。サーバーからエラーが返された場合、その情報が文字列に含まれています。詳細情報は、特に開発時において問題の原因を特定する作業に役立ちます。

たとえば、ユーザー登録でユーザー user_123456 がすでに登録されていた場合、ユーザーの重複によってエラーとなります。この場合に渡されるエラー文字列は次のとおりです。

USER_ALREADY_EXISTS: User with loginName user_123456 already exists

これらのエラーメッセージは人間が読んでエラーの内容を理解するには有益ですが、プログラムでエラーを処理する場合にはエラーメッセージの解析が必要です。KiiErrorParser を使うと、エラメッセージをプログラムが扱いやすいオブジェクト形式に変換できます。

var user = KiiUser.userWithUsername("user_123456", "123ABC");
user.register().then(
  function(theUser) {
    // Do something.
  }
).catch(
  function(error) {
    var err = KiiErrorParser.parse(error);
    if (err.status == 0) {
      // The error is related to network.
    } else if (err.status == -1) {
      // The error is not related to network.
      // It might be an argument error or an illegal state error.
    } else if (err.status == -2) {
      // The error is unknown.
      // Confirm the latest version of the SDK is used.
    } else {
      console.log(err.status);
      console.log(err.code);
      console.log(err.message);
    }
  }
);

var user = KiiUser.userWithUsername("user_123456", "123ABC");
user.register({
  success: function(theUser) {
    // Do something.
  },
  failure: function(theUser, errorString) {
    var err = KiiErrorParser.parse(errorString);
    if (err.status == 0) {
      // The error is related to network.
    } else if (err.status == -1) {
      // The error is not related to network.
      // It might be an argument error or an illegal state error.
    } else if (err.status == -2) {
      // The error is unknown.
      // Confirm the latest version of the SDK is used.
    } else {
      console.log(err.status);
      console.log(err.code);
      console.log(err.message);
    }
  }
});

コールバック関数で渡されたエラーメッセージ（エラーオブジェクト）を KiiErrorParser.parse(error) メソッドに指定すると、エラー情報がオブジェクトに変換されます。

オブジェクトには status、code、message の3つのプロパティが定義されています。

status: REST API を呼び出した結果としてサーバーから返された HTTP ステータスコードです。

通常は 400 や 404 などの値が返されます。ネットワークエラーなどが原因でリクエストがサーバーに到達していない場合は 0 が、解析しようとしたエラーメッセージが引数エラーなどサーバーが返したエラー以外の場合は -1 が、SDK で認識できないエラーの場合は -2 が返されます。-2 が返された場合、最新の SDK に更新すると、エラーの詳細情報を取得できるはずです。

0 が取得された場合、リクエストの再試行は行わないように実装してください。下記の負荷集中時のエラーのとおり、輻輳が発生する可能性があります。
code: REST API の結果に含まれるエラーコードです。

プログラム内で、エラーの詳細原因を元に処理を振り分けたい場合などに、この戻り値の文字列を使用できます。ユーザー重複のエラーの場合、USER_ALREADY_EXISTS を取得できます。
message: REST API を呼び出した結果としてサーバーから返された応答の HTTP ボディーに含まれるエラー詳細情報です。

アプリ開発者が見て内容を判断することを想定しています。ユーザー重複のエラーの場合、User with loginName user_123456 already exists のようなメッセージを取得できます。

なお、パラメータエラーを含め、Kii Cloud SDK では例外の throw を行わず、すべてコールバック関数または Promise のハンドラーでエラーを通知します。

負荷集中時のエラー

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

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

上限に達した場合、各 API はエラーを返します。この際、KiiErrorParser.parse() メソッドで取得できる status プロパティは、通信エラーなどと同様、0 になります。0 が取得された場合、輻輳を防止するため、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

データブラウザ

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