REST API の実行

Thing SDK Embedded では、任意の REST API を実行する機能を提供しています。Thing SDK Embedded でサポートされていない機能でも、REST API を実行することによって利用することができます。

REST API の実行に必要なパラメーターは、REST リファレンスガイドの curl コマンドや、詳細ドキュメントの API 仕様をご覧ください。

ここでは、Object の検索を行う REST API の curl コマンドを、Thing SDK Embedded によって実行する例を示します。

curl -v -X POST \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Kii-AppID: {APP_ID}" \
  -H "X-Kii-AppKey: {APP_KEY}" \
  -H "Content-Type: application/vnd.kii.QueryRequest+json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/things/VENDOR_THING_ID:{VENDOR_THING_ID}/buckets/myBucket/query" \
  -d '{
       "bucketQuery": {
         "clause": {
           "type": "range", "field": "temperature",
           "lowerLimit": 20
         },
         "orderBy": "temperature", "descending": false
       },
       "bestEffortLimit": 5
     }'

これは、REST API で Object の検索を行うコマンドの例です。ここでは、Thing スコープ上で temperature が 20 以上の Object を降順で最大 5 件ずつ取得する条件を指定しています。REST API の仕様の詳細は KiiObject の検索をご覧ください。

今回の例に挙げた bestErrortLimit のように通信量に影響するパラメーターは、SDK の初期化の際に指定したバッファー kii.kii_core.http_context のサイズを考慮しながら決定してください。レスポンスの通信データがバッファーに入りきらない場合はエラーとなります。

この curl コマンドと同等の処理を SDK から実行するには、次のようなコードを実装します。

int ret;

#define RESOURCE_PATH "/api/apps/" EX_APP_ID "/things/VENDOR_THING_ID:rBnvSPOXBDF9r29GJeGS/buckets/myBucket/query"
#define CONTENT_TYPE "application/vnd.kii.QueryRequest+json"

/* Start to create a REST API request. */
ret = kii_api_call_start(&kii, "POST", RESOURCE_PATH, CONTENT_TYPE, KII_TRUE);
if (ret != 0) {
  /* Handle the error. */
  return;
}

/* Set HTTP headers if needed. */
/* ret = kii_api_call_append_header(&kii, "X-MY-HEADER1", "MyHeaderValue"); */
/* ret = kii_api_call_append_header(&kii, "X-MY-HEADER2", "MyHeaderValue"); */

#define HTTP_BODY "{" \
                  "  \"bucketQuery\": {" \
                  "    \"clause\": {" \
                  "      \"type\": \"range\", \"field\": \"temperature\"," \
                  "      \"lowerLimit\": 20" \
                  "    }," \
                  "    \"orderBy\": \"temperature\", \"descending\": false" \
                  "  }," \
                  "  \"bestEffortLimit\": 5" \
                  "}"

/* Append the request body. */
ret = kii_api_call_append_body(&kii, HTTP_BODY, strlen(HTTP_BODY));
if (ret != 0) {
  /* Handle the error. */
  return;
}

/* Send the created REST API request. */
ret = kii_api_call_run(&kii);
if (ret != 0) {
  /* Handle the error. */
  return;
}

printf("status:%d\n", kii.kii_core.response_code);
printf("result:%s\n", kii.kii_core.response_body);

REST API の実行時は、Thing SDK Embedded の次の API を順に呼び出します。

kii_api_call_start()

初めに、REST API の定義を開始するための関数を呼び出します。引数には次の値を指定します。
- kii_t
  
  初期化済みの kii_t を指定します。
  
  今回の例では検索の実行時にアクセストークンが必要なため、kii_t に Thing のアクセストークンが設定済みになっている想定です。
- HTTP の動詞
  
  REST API で使用する HTTP の動詞（GET/POST など）を指定します。ここでは、curl コマンドのパラメーターを元に、POST を指定しています。
- リソースパス
  
  REST API のアクセス先 URL のパスを指定します。curl コマンドのアクセス先 URL から、サーバー名を除いた残りのパスを指定します。
  
  なお、このサンプルでは、vendorThingID rBnvSPOXBDF9r29GJeGS の Thing スコープの Bucket にアクセスしています。kii_t に、この Thing のアクセストークンが設定されている前提です。
- Content-Type
  
  REST API の HTTP リクエストで使用する Content-Type です。リファレンスガイドの curl コマンドの例に Content-Type の指定がない場合は、詳細ドキュメントをご確認ください。
- Authorization ヘッダーの有無
  
  KII_TRUE を指定すると、Authorization ヘッダーに kii_t から取得したアクセストークンを設定します。KII_FALSE を指定した場合は、リクエストに Authorization ヘッダーを追加せず匿名アクセスを行います。
kii_api_call_append_header()

特殊な HTTP ヘッダーが必要な REST API では、この関数で HTTP ヘッダーを追加できます。不要な場合、この関数を呼び出す必要はありません。
kii_api_call_append_body()

HTTP ボディーを追加します。GET メソッドを利用する場合、呼び出しは不要です。

引数として、HTTP ボディーに指定する文字列やバイナリデータへのポインタと、その長さを指定します。複数回に分けて追加することができますが、リクエスト全体のサイズが kii.kii_core.http_context に指定したサイズを超えるとエラーになります。

追加した HTTP ボディーの長さに応じて、Content-Length ヘッダーが自動的に設定されます。
kii_api_call_run()

必要なデータを用意した後、この関数を呼び出すと Kii Cloud にリクエストを行います。

REST API の実行の結果は kii_t 構造体より取得できます。kii.kii_core.response_code からは HTTP のステータスコードが、kii.kii_core.response_body からは HTTP ボディーのデータが、それぞれ取得できます。

サンプルコードに示した検索の例の場合、HTTP ボディーのテキストデータは、REST API の仕様に基づいて以下のような結果となります。プログラムから使用するには、JSON の解析に示す kii_json ライブラリーを使ってフィールド値を取得できます。

{
  "queryDescription": "WHERE ( 20 <= temperature ) ORDER BY temperature ASC",
  "results": [
    {
      "_created": 1465959304473,
      "_id": "8f7ce090-32a4-11e6-b38c-22000a7f900d",
      "_modified": 1465959304473,
      "_owner": "702b5ba64301b42bc82318ae5a0459b3",
      "_version": "1",
      "power": true,
      "status": "ECO-MODE",
      "temperature": 22
    },
    {
      "_created": 1465959311501,
      "_id": "93ad43d0-32a4-11e6-83ca-22000aaf0c30",
      "_modified": 1465959311501,
      "_owner": "702b5ba64301b42bc82318ae5a0459b3",
      "_version": "1",
      "power": true,
      "status": "NORMAL",
      "temperature": 28
    }
  ]
}