初期登録

Thing Interaction Framework の機能を利用するには、Thing を Framework に登録して、必要に応じてモバイルアプリ（より正確にはアプリ利用者）と紐付ける必要があります。この操作を初期登録と呼びます。

概要で説明されているように, 初期登録はモバイルアプリ経由で行うことも、Thing より直接行うこともできます。

オーナーによる初期登録：モバイルアプリ経由で初期登録する場合は、Thing オーナーのアクセストークンを使って初期登録を行います
Thing による初期登録：Thing より直接初期登録する場合は Basic 認証を使用します（Thing のトークンを使用することもできます）。

なお、Thing オーナーとアクセストークンの概要についてはそれぞれ Thing オーナーとアクセストークンをご覧ください。

オーナーによる初期登録

Thing の識別子として vendorThingID と thingID が利用可能です（詳しくはこちらをご参照ください）

vendorThingID を使う場合

Thing のオーナーが vendorThingID を使って初期登録を行う例を以下に挙げます。

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.OnboardingWithVendorThingIDByOwner+json" \
  "https://api-jp.kii.com/thing-if/apps/{APP_ID}/onboardings" \
  -d '{
    "vendorThingID": "{VENDOR_THING_ID}",
    "thingPassword": "{THING_PASSWORD}",
    "thingType": "{THING_TYPE}",
    "thingProperties": {
      "{PROPERTY_NAME}": "{PROPERTY_VALUE}"
    },
    "owner": "user:{USER_ID}",
    "dataGroupingInterval": "15_MINUTES"
  }'

Thing オーナーとしてユーザーを設定する場合は、このユーザーのアクセストークンを使用してください。Thing オーナーとしてグループを設定する場合は、このグループのメンバーのアクセストークンを使用してください。

リクエストのボディには以下の情報を指定します。

フィールド	必須項目か？	説明
vendorThingID	◯	ベンダーが定義した Thing の ID です。詳細はこちらをご覧ください。アプリケーション内で一意であれば、200 文字までの英数字、ハイフン、アンダースコアおよびピリオドが利用可能です。なお、このフィールド値は後で変更できません。
thingPassword	◯	Thing のパスワードです。Thing Interaction Framework 上に登録された Thing の領域をセキュアにするため、Thing ごとに異なるパスワードを設定するのが基本です。初回登録時に設定したパスワードが有効になります。二回目以降の初期登録では、初回に登録したパスワードを設定します。一旦設定したパスワードは変更できません。
owner	◯	Thing オーナーの ID。ユーザー ID かグループ ID のいずれかが指定可能。ユーザー ID の場合は user:、グループ ID の場合は group: をプレフィックスとしてつけてください。
thingType		Thing のタイプです。100 文字までの英数字、ハイフン、アンダースコアおよびピリオドが利用可能です。
thingProperties		Thing の属性です。既定フィールドと任意フィールドのいずれも設定可能です。フィールドの詳細は Thing の登録をご覧ください。
dataGroupingInterval		ステート履歴を保存する場合、履歴をグループ化する間隔を指定します。指定のない場合はステート履歴は保存されません。指定可能な値は 1_MINUTE、15_MINUTES、30_MINUTES、1_HOUR、12_HOURS のいずれかです。詳しくはこちらをご参照ください。

指定した vendorThingID を持つ Thing が存在しない場合、指定した情報を元に新たな Thing が Thing Interaction Framework に登録されます。すでに存在する場合は、指定した情報は無視されます（指定情報による更新などは行われません）。

なお、Thing の存在有無にかかわらず、オーナー登録は常に行われます。

初期登録が成功すると、Thing Interaction Framework は以下のような 200 応答を返します。

HTTP/1.1 200 OK
Content-Type: application/json
{
  "thingID":"{THING_ID}",
  "accessToken":"{THING_ACCESS_TOKEN}",
  "mqttEndpoint":{
    "installationID":"{INSTALLATION_ID}",
    "host":"{BROKER_HOST}",
    "mqttTopic","{MQTT_TOPIC}",
    "userName":"{USERNAME}",
    "password":"{PASSWORD}",
    "portSSL":{PORT_SSL},
    "portTCP":{PORT_TCP},
    "portWS" : {PORT_WS},
    "portWSS" : {PORT_WSS},
    "ttl":{MQTT_TTL}
  }
}

レスポンスには thingID と Thing のアクセストークンが含まれます。また MQTT コネクション確立に必要な MQTT エンドポイント情報も含まれます（詳細はこちらをご覧ください）。

thingID を使う場合

Thing のオーナーが thingID を使って初期登録を行う例を以下に挙げます。

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.OnboardingWithThingIDByOwner+json" \
  "https://api-jp.kii.com/thing-if/apps/{APP_ID}/onboardings" \
  -d '{
    "thingID": "{THING_ID}",
    "thingPassword": "{THING_PASSWORD}",
    "owner": "user:{USER_ID}"
  }'

リクエストもレスポンスも、以下の点を除き基本的には vendorThingID を使う場合と同様です。

指定した thingID を持つ Thing がすでに存在する必要があります。
対象となる Thing はすでに存在するため、"thingType" や "thingProperties" フィールドの指定は不要です。指定した場合は無視されます。
Content-Type は "application/vnd.kii.OnboardingWithThingIDByOwner+json" を指定します。

Thing による初期登録

Thing の識別子として vendorThingID と thingID が利用可能です（詳しくはこちらをご参照ください）

vendorThingID を使う場合

Thing 自身が vendorThingID を使って初期登録を行う例を以下に挙げます。

curl -v -X POST \
  -H "Authorization: Basic {BASE64_ENCODED_APPID_AND_APPKEY}" \
  -H "X-Kii-AppID: {APP_ID}" \
  -H "X-Kii-AppKey: {APP_KEY}" \
  -H "Content-Type: application/vnd.kii.OnboardingWithVendorThingIDByThing+json" \
  "https://api-jp.kii.com/thing-if/apps/{APP_ID}/onboardings" \
  -d '{
    "vendorThingID": "{VENDOR_THING_ID}",
    "thingPassword": "{THING_PASSWORD}",
    "thingType": "{THING_TYPE}",
    "thingProperties": {
      "{PROPERTY_NAME}": "{PROPERTY_VALUE}"
    }
  }'

リクエストもレスポンスも、以下の点を除き基本的には vendorThingID を使う場合と同様です。

Basic 認証を使用します。{BASE64_ENCODED_APPID_AND_APPKEY} には AppID と任意の値をコロン（:）で連結した文字列を Base64 エンコードしたものを入れてください。Thing のトークンを使用することもできます。
Content-Type は "application/vnd.kii.OnboardingWithVendorThingIDByThing+json" を指定します。
"owner" フィールドは指定しないでください。

thingID を使う場合

Thing 自身が thingID を使って初期登録を行う例を以下に挙げます。

curl -v -X POST \
  -H "Authorization: Basic {BASE64_ENCODED_APPID_AND_APPKEY}" \
  -H "X-Kii-AppID: {APP_ID}" \
  -H "X-Kii-AppKey: {APP_KEY}" \
  -H "Content-Type: application/vnd.kii.OnboardingWithThingIDByThing+json" \
  "https://api-jp.kii.com/thing-if/apps/{APP_ID}/onboardings" \
  -d '{
    "thingID": "{THING_ID}",
    "thingPassword": "{THING_PASSWORD}"
  }'

リクエストもレスポンスも、以下の点を除き基本的には vendorThingID を使う場合と同様です。

Basic 認証を使用します。{BASE64_ENCODED_APPID_AND_APPKEY} には AppID と任意の値をコロン（:）で連結した文字列を Base64 エンコードしたものを入れてください。Thing のトークンを使用することもできます。
指定した thingID を持つ Thing がすでに存在する必要があります。
対象となる Thing はすでに存在するため、"thingType" や "thingProperties" フィールドの指定は不要です。指定した場合は無視されます。
Content-Type は "application/vnd.kii.OnboardingWithThingIDByThing+json" を指定します。
"owner" フィールドは指定しないでください。