Thing 管理

Kii Cloud は Thing を管理するために以下の機能を提供します。

Thing の登録

Thing を Kii Cloud で使用するにはまずこれを登録する必要があります。登録を行うことで Kii Cloud はこの Thing を認識します。

Thing を登録する際には、属性情報を Thing 情報のフィールド値として設定することができます。各フィールド値の詳細については 概要 を参照してください。

Thing を登録する例を以下に挙げます。

curl -v -X POST \
  -H "Authorization: Basic {BASE64_ENCODED_APPID_AND_APPKEY}" \
  -H "Content-Type: application/vnd.kii.ThingRegistrationAndAuthorizationRequest+json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/things" \
  -d '{
        "_vendorThingID": "nbvadgjhcbn",
        "_thingType": "CAMERA",
        "_password": "123456",
        "freeFormField1": "freeFormValue1",
        "freeFormField2": "freeFormValue2",
        "freeFormField3": "freeFormValue3"
      }'

登録は Basic 認証 を使って行います。{BASE64_ENCODED_APPID_AND_APPKEY} には AppID と任意の値をコロン（:） で連結した文字列を Base64 エンコードしたものを入れてください。

Kii Cloud は次のような 201 応答を返します。

201

Content-Type: application/vnd.kii.ThingRegistrationAndAuthorizationResponse+json
{
    "_thingID" : "th.dfa848a00022-faea-4e11-dacb-0614e078",
    "_accessToken" : "X7BGXok7oDDNSIEXo-sNdhMIq1qNpd1DWNrrpifjPY4",
    "_vendorThingID" : "nbvadgjhcbn",
    "_thingType" : "CAMERA",
    "_created" : 1411490350034,
    "freeFormField1" : "freeFormValue1",
    "freeFormField2" : "freeFormValue2",
    "freeFormField3" : "freeFormValue3"
}

Kii Cloud は thingID を "_thingID" フィールドの値、（non-persistent な）アクセストークンを "_accessToken" フィールドの値として返します。さらに登録処理を行った時間（UNIX 時間、ミリ秒、UTC）を "_created" フィールドの値として返します。

Thing 登録時にアクセストークンの取得が不要の場合は、Thing 登録リクエスト送信時に Content-type として application/vnd.kii.ThingRegistrationRequest+json を指定してください。

登録が完了すると、以後 Thing は thingID で識別可能となります。なお、いくつかの Thing 関連 API では、thingID の代わりに vendorThingID を使用することもできます。

ガイドでは thingID を使った curl 実行例を紹介します。thingID の代わりに vendorThingID を使用する場合は、実行例の {THING_ID} を VENDOR_THING_ID:{VENDOR_THING_ID} に読み替えてください。

Thing の登録確認

Thing が Kii Cloud に登録済みかどうかは誰でも確認できます。

curl -v -X HEAD \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/things/{THING_ID}"

Kii Cloud は、Thing が登録済みの場合は 204 応答を、未登録の場合は 404 応答を返します。

アクセストークンの取得

ユーザー名とパスワードを引数にユーザーのアクセストークンを取得できるように、vendorThingID とパスワードを引数に Thing のアクセストークンが取得できます。

curl -v -X POST \
  -H "Authorization: Basic {BASE64_ENCODED_APPID_AND_APPKEY}" \
  -H "Content-Type: application/vnd.kii.OauthTokenRequest+json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/oauth2/token" \
  -d '{
        "grant_type": "password",
        "username": "VENDOR_THING_ID:KQgn3WEIXDffAoU5ZZgA",
        "password": "p455w0rd"
      }'

アクセストークンの取得は Basic 認証 を使って行います。{BASE64_ENCODED_APPID_AND_APPKEY} には AppID と任意の値をコロン（:） で連結した文字列を Base64 エンコードしたものを入れてください。

ここで取得可能なトークンは non-persistent トークンです。Non-persistent トークンは、Thing が無効化された場合や有効期限が切れた場合に無効化します。このため、たとえば Thing を再度有効化した際に、新たなアクセストークンを別途取得する必要があります。

Thing によっては、パスワードを安全に保管できないケースが考えられます。この場合、当然ながらアクセストークンの再取得が行えません。このようなケースに対応するために、Kii Cloud は persistent トークンを提供します。Persistent トークンは有効期限を持たず、Thing が登録解除されるまで有効であり続けます。Thing が無効化された場合は一時的に無効化されますが、Thing が再度有効化されたタイミングでまた有効になります。たとえば Thing に persistent トークンを埋め込んでおき、毎回このトークンを使い続けるようなことが可能です。

Persistent トークンを取得するには、次の例のように Thing 登録時に "_persistentToken" フィールドを true に設定します。なお persistent トークンを取得できるのはアプリケーション管理者のみです。

curl -v -X POST \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/vnd.kii.ThingRegistrationAndAuthorizationRequest+json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/things" \
  -d '{
        "_persistentToken": true,
        "_vendorThingID": "nbvadgjhcbn",
        "_thingType": "CAMERA",
        "_password": "123456",
        "freeFormField1": "freeFormValue1",
        "freeFormField2": "freeFormValue2",
        "freeFormField3": "freeFormValue3"
      }'

Thing 情報の操作

Thing 情報の取得

Thing、Thing オーナーおよびアプリケーション管理者は、Thing 情報が取得できます。

curl -v -X GET \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/things/{THING_ID}"

Kii Cloud は、Thing 情報を 200 応答として次のように返します。

200

Content-Type: application/vnd.kii.ThingRetrievalResponse+json

{
    "_thingID": <thingID>,
    "_vendorThingID": <vendorThingID>,
    "_created": 1337039114613,
    "_thingType": "CAMERA",
    "freeFormField1": "freeFormValue1",
    "freeFormField2": "freeFormValue2",
    "freeFormField3": "freeFormValue3",
    "_online": true,
    "_onlineStatusModifiedAt": 1431611669239
}

Thing 情報の各フィールドに加え、さらに 2 つのフィールド（_online と _onlineStatusModifiedAt) が返されます。これらのフィールドは現在の Thing の状態 を示しています。

  • _online フィールドは現在の Thing の状態を表します。オンラインである場合は true、オフラインである場合は false になります。

  • _onlineStatusModifiedAt フィールドは Thing の状態が最後に変更した時刻です（UNIX 時間、ミリ秒）。

Thing 情報の更新

Thing、Thing オーナーおよびアプリケーション管理者は、Thing 情報を更新できます。

curl -v -X PATCH \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/vnd.kii.ThingUpdateRequest+json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/things/{THING_ID}" \
  -d '{
        "_thingType": "New Thing Type",
        "freeFormField1": "freeFormValue1",
        "freeFormField2": "freeFormValue2"
      }'

既定フィールドは、指定したフィールドのみが更新されます。リクエスト内で指定しなかったフィールドの値はそのままキープされます。なお、すでに存在するフィールドは削除できません。

カスタムフィールドは、指定した内容でそのまま上書きされます。すなわち、リクエスト内で指定が行われなかったカスタムフィールドは削除されます。

更新に成功すると、Kii Cloud は更新時間（UNIX 時間、ミリ秒、UTC）を 200 応答で返します。

200

Content-Type: application/vnd.kii.ThingUpdateResponse+json

{
  "modifiedAt" : 1411553060944
}

thingID と vendorThingID の変換

thingID から vendorThingID を取得したいとき、またはその逆の操作が必要なときは、Thing 情報の取得機能を利用できます。

  • thingID から vendorThingID を取得

    URL を https://api-jp.kii.com/api/apps/{APP_ID}/things/{THING_ID} として Thing 情報を取得し、結果の _vendorThingID を参照します。

  • vendorThingID から thingID を取得

    URL を https://api-jp.kii.com/api/apps/{APP_ID}/things/VENDOR_THING_ID:{VENDOR_THING_ID} として Thing 情報を取得し、結果の _thingID を参照します。

Thing 状態の操作（有効化/無効化）

Thing オーナーとアプリケーション管理者は Thing を無効化できます。無効化すると Thing は「ロック」状態になり、以後スコープ内のデータ（Bucket および Object）にアクセスできなくなります。Thing が無効化されてもデータ自体は Kii Cloud に残り、Thing オーナーとアプリケーション管理者はデータにアクセス可能です。この機能は、たとえば Thing が盗難にあったり紛失したりした場合において、一時的に Thing の利用を停止したい場合などに有効です。

もちろん Thing オーナーとアプリケーション管理者は、後ほど Thing を有効化できます。有効化すると Thing は「ロック解除」状態になり、以後スコープ内のデータにアクセス可能となります。

Thing の無効化/有効化

Thing を無効化する例を以下に挙げます。

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/vnd.kii.ThingStatusUpdateRequest+json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/things/{THING_ID}/status" \
  -d '{"disabled": true}'

無効化に成功すると Kii Cloud は 204 応答を返します。

Thing を有効化する場合は "disabled" フィールドを false に設定します。

Thing が無効化されているか確認

Thing、Thing オーナーおよびアプリケーション管理者は、Thing が無効化されているか確認できます。

Thing が無効化されているか確認する例を以下に挙げます。

curl -v -X GET \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/things/{THING_ID}/status"

Kii Cloud は次のように 200 応答を返します。

200

Content-Type: application/vnd.kii.ThingStatusRetrievalResponse+json

{
    "disabled": true
}

Thing の登録解除

Thing、Thing オーナー、およびアプリケーション管理者は Thing を登録解除できます。登録が解除されると、スコープ内のすべてのデータ（Bucket や Object）が Kii Cloud より削除されます。

Thing を登録解除する例を以下に挙げます。

curl -v -X DELETE \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/things/{THING_ID}"

登録解除に成功すると Kii Cloud は 204 応答を返します。

所有する Thing 一覧の取得

認証済みユーザーは、自分がオーナーである thing のリストを取得できます（オーナー管理の詳細は Thing オーナー管理をご覧ください）。

自分がオーナーである thing の一覧を取得する例を以下に挙げます。

curl -v -X POST \
  -H "Authorization: Bearer {OWNER_ACCESS_TOKEN}" \
  -H "Content-Type: application/vnd.kii.ThingQueryRequest+json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/things/query" \
  -d '{
    "thingQuery" : {
      "clause" : {
        "type" : "contains",
        "field" : "userOwners",
        "value" : "{USER_ID}"
      }
    }
  }'

Thing の一覧は次のように返されます。

200 OK
Content-Type: application/vnd.kii.ThingQueryResponse+json

{
  "queryDescription" : "WHERE ( userOwners = '{USER_ID}' )",
  "results" : [ {
    "_thingID" : "{THING_ID_OF_THING_01}",
    "_vendorThingID" : "{VENDOR_THING_ID_OF_THING_01}",
    "_thingType" : "{THING_TYPE_OF_THING_01}",
    "_firmwareVersion" : "{FIRMWARE_VERSION_OF_THING_01}",
    "_created" : {CREATED_DATE_OF_THING_01},
    "_disabled" : false
  }, {
    "_thingID" : "{THING_ID_OF_THING_02}",
    "_vendorThingID" : "{VENDOR_THING_ID_OF_THING_02}",
    "_thingType" : "{THING_TYPE_OF_THING_02}",
    "_firmwareVersion" : "{FIRMWARE_VERSION_OF_THING_02}",
    "_created" : {CREATED_DATE_OF_THING_02},
    "_disabled" : false
  } ]
}

所有する thing が存在しない場合は空のリストが返されます。

さらなる例

ユーザーは、自分がユーザーおよびグループメンバーとして所有する thing の一覧を同時に取得できます。

次のように or 条件を使ってユーザー ID とグループ ID を指定してください。

{
  "thingQuery" : {
    "clause" : {
      "type" : "or",
      "clauses": [ {
        "type" : "contains",
        "field" : "userOwners",
        "value" : "{USER_ID}"
      }, {
        "type" : "contains",
        "field" : "groupOwners",
        "value" : "{GROUP_ID}"
      } ]
    }
  }
}

また、ユーザーは thing の 既定フィールド に条件を加えて thing を絞り込むことができます。

次の例のように and 条件を使って条件を指定してください。

{
  "thingQuery" : {
    "clause" : {
      "type" : "and",
      "clauses": [ {
        "type" : "contains",
        "field" : "userOwners",
        "value" : "{USER_ID}"
      }, {
        "type" : "eq",
        "field" : "_thingType",
        "value" : "{THING_TYPE}"
      } ]
    }
  }
}

いずれにおいても contains フィールドは必須フィールドです。

条件指定の詳細については Query Requset オブジェクト を参照してください。thingQuery の設定は bucketQuery と同様に行います。

ページネーション

一覧に含まれる thing の個数が一回の応答で返すことが出来る件数を超えた場合、取得結果はページネーションされます。この場合、一部の thing と共にページネーションキーが返されます。

ページネーションの利用方法の詳細については Query Requset オブジェクト および ページネーション（Object 検索） を参照してください。Object 検索時と同様に、ページネーションが利用できます。

オーナーではない thing も含む一覧の取得

ここで紹介した API で取得可能な thing は、ユーザーがオーナーであるもののみです。ユーザーがオーナーではない thing を含んだ一覧が必要な場合、アプリ側での実装が必要となります。一覧が必要な場合は、アプリケーションスコープに Thing の一覧情報を格納するなどの方法をとれます。実装方法は、ユーザー一覧の実装方法 を参考にしてください。

Thing パスワードの強制変更

アプリケーション管理者は、Thing パスワードを強制変更できます。これは、Thing のパスワード漏洩が発生したケースなどを想定した機能です。

curl -v -X PUT \
  -H "Authorization: Bearer {APP_ADMIN_TOKEN}" \
  -H "Content-Type: application/vnd.kii.ChangeThingPasswordRequest+json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/things/{THING_ID}/password" \
  -d '{
        "newPassword": "{NEW_PASSWORD}"
      }'

パスワードの変更に成功すると、Kii Cloud は 204 応答を返します。

トークンの無効化

Thing パスワードが変更されると、それまでに払い出されていた Thing の non-perisistent トークンは無効化されます。

ただし、Thing の persistent トークンは無効化されません。また Thing オーナーのトークンも無効化されません。