例外処理と調査方法

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

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

サンプルコードでの記載

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

たとえば、Thing の登録の解説では、次のようなサンプルコードを扱っています。

ret = kii_thing_authenticate(&kii, VENDOR_THING_ID, PASSWORD);
if (ret != 0) {
  /* Handle the error. */
  return;
}

詳細情報の取得

SDK が Kii Cloud のサーバーに接続でき、サーバーからエラーが返された場合、その情報を取得することができます。詳細情報は、特に開発時において問題の原因を特定する作業に役立ちます。

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

#define VENDOR_THING_ID "rBnvSPOXBDF9r29GJeGS"
#define THING_TYPE "sensor"
#define PASSWORD "123ABC"

ret = kii_thing_register(&kii, VENDOR_THING_ID, THING_TYPE, PASSWORD);
if (ret != 0) {
  /* Handle the error. */
  printf("status code:%d\n", kii.kii_core.response_code);
  printf("error string:%s\n", kii.kii_core.response_body);
  return;
}

status code:409
error string:{
  "errorCode" : "THING_ALREADY_EXISTS",
  "message" : "Thing with vendorThingID rBnvSPOXBDF9r29GJeGS already exists",
  "value" : "rBnvSPOXBDF9r29GJeGS",
  "field" : "vendorThingID"
}

kii.kii_core.response_code には HTTP のステータスコードが格納されます。このコードは、REST API で定められたステータスコードです。ステータスコードの意味付けは、SDK の API が実行している REST API によって決まります。API の対応はソースコードを直接ご確認ください。また、REST API のステータスコードは、詳細ドキュメントをご覧ください。

kii.kii_core.response_body には、REST API のエラー情報が JSON 形式の文字列として格納されます。JSON 形式の文字列からフィールドを取得したい場合は、JSON の解析をご覧ください。

エラー情報のうち、特に重要なのは以下のフィールドです。

errorCode

実行に失敗した場合のエラーコードが返されます。プログラムでの判断に使用します。
message

エラーの詳細を人間が理解できる形式で出力した情報です。今回の例では、指定された Thing がすでに存在していたことが読み取れます。

エラーの内容によってプログラムを制御したい場合、REST API のリファレンスから HTTP ステータスコードの重複がないことを確認のうえ、 kii.kii_core.response_code を使用します。HTTP ステータスコードの重複などで、詳細な判断が必要な場合、kii.kii_core.response_body の JSON を解析し、errorCode フィールドによって処理を分岐させます。

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

エラーコードのリセット

リクエストを Kii Cloud に送信する前にエラーが発生した場合、エラー情報は設定されません。たとえば、送信しようとしている REST API のメッセージサイズに対してバッファーサイズが小さい場合、関数は 0 以外を返してエラー応答しますが、kii.kii_core.response_code と kii.kii_core.response_body は呼び出し前の値を保持します。

サーバーからの応答をプログラム側で判断する場合、API の呼び出し前に以下のような初期化処理を入れておくことをおすすめします。初期化処理を入れておくことで、リクエストを Kii Cloud に送信する前にエラーが発生した場合の検出が容易になります。

kii.kii_core.response_code = 0;
kii.kii_core.response_body = NULL;

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

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

開発者ログ

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

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

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

2016-06-17T14:08:21.000+09:00 [ERROR] thing.create description:New thing creation failed  exception:Thing with vendorThingID rBnvSPOXBDF9r29GJeGS already exists

データブラウザ

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