本文へジャンプします。

ニフティクラウド ユーザーガイド

リソース

ユーザー

プロジェクトの登録済みエンドユーザー。

ユーザー作成

ニフティクラウドIoTデバイスハブ上でプロジェクトを作成する際に、開発者はユーザーアカウントの管理方法を指定する必要があります。デフォルトでは、プロジェクトはIoTデバイスハブが提供する組み込みのユーザーアカウントシステムを使用します。
一方、プロジェクト独自のアカウントシステムをプロジェクトのユーザーのために別途実装することもできます。プロジェクトのタイプに基づいて、このAPI呼び出しは次のいずれかを行います。

組み込みのアカウントシステムを利用するプロジェクト(電話番号ベース)

新規ユーザーを登録します。リクエストボディは、projectId、phoneNumber、およびnameの各フィールドを含む有効なユーザーオブジェクトであることが必要です。
電話番号は、プロジェクトの既存ユーザーによって使用されていないことが必要です。
登録を確認するために確認コードを含むSMSテキストがユーザーに送信されます。

組み込みのアカウントシステムを利用するプロジェクト(メールアドレスベース)

新規ユーザーを登録します。リクエストボディは、projectId、email、およびnameの各フィールドを含む有効なユーザーオブジェクトであることが必要です。 さらに、パスワードフィールドも存在している必要があります。
メールアドレスは、プロジェクトの既存ユーザーによって使用されていないことが必要です。
登録を確認するために、確認URLを含むメールメッセージがユーザーに送信されます。

BYOU("Bring-Your-Own-Users")プロジェクト

プロジェクト独自のアカウントシステムに存在するユーザーに対応するエントリーを、IoTデバイスハブ内に作成します。リクエストオブジェクトに含まれている必要があるものは、projectIdフィールドのみです。
また、リクエストにはプロジェクトのAPIキーを使用したAuthorizationヘッダが必要です。キーのパーミッションにはBYOU対応を設定しておく必要があります。
呼び出し元は、以後のAPI呼び出しのためにこのユーザーIDを保管する必要があります。

API Endpoint

POST /users

Headers
Header Description Required
Authorization
string
プロジェクトのAPIキーを含んでいる必要があります。BYOUプロジェクトの場合のみ必須。 No
Request Body

User (JSON)

Response
Code Body Description
201 User ユーザーは正常に作成されました。作成されたオブジェクトが応答本文で返されます。
403 Error データが無効か、権限が無いことが原因で、要求が失敗しました。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。
ユーザーの取得

指定したIDのユーザーを返します。

API Endpoint

GET /users/{userId}

URI Parameters
Field Description Required
userId
integer
ユーザーID Yes
Headers
Header Description Required
Authorization
string
ユーザーのAPIキーを使用する必要があります。 Yes
Response
Code Body Description
200 User 要求したユーザーが応答本文で返されます。
401   認証に失敗しました。
403 Error 権限が無いことが原因で、要求が失敗しました。
404 Error 要求したユーザーが存在しないか、アクセスが不可です。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。
ユーザーの更新

指定したIDのユーザーを更新します。

API Endpoint

PATCH /users/{userId}

URI Parameters
Field Description Required
userId
integer
ユーザーID Yes
Headers
Header Description Required
Authorization
string
ユーザーのAPIキーを使用する必要があります。 Yes
Request Body

User (JSON)

Response
Code Body Description
204   ユーザーは正常に更新されました。
401   認証に失敗しました。
403 Error データが無効か、権限が無いことが原因で、要求が失敗しました。
404 Error 要求したユーザーが存在しないか、アクセスが不可です。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。
ユーザーの削除

指定したIDのユーザーを削除します。

API Endpoint

DELETE /users/{userId}

URI Parameters
Field Description Required
userId
integer
ユーザーID Yes
Headers
Header Description Required
Authorization
string
ユーザーのAPIキーを使用する必要があります。 Yes
Response
Code Body Description
204   ユーザーは正常に削除されました。
401   認証に失敗しました。
403 Error データが無効か、権限が無いことが原因で、要求が失敗しました。
404 Error 要求したユーザーが存在しないか、アクセスが不可です。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。

ホーム

「ホーム」はデバイスのコンテナーを表し、1人以上のユーザーによって所有/管理されます。

ホームリストの取得

ユーザーが属するホームのリストを取得します。

API Endpoint

GET /homes

Headers
Header Description Required
Authorization
string
ユーザーまたはプロジェクトのAPIキーを含んでいる必要があります。 Yes
Query Parameters
Field Description Required
userId
integer
指定したユーザーがメンバーであるホームを返します。 Yes
Response
Code Body Description
200 Array of Homes ホームオブジェクトのリストが応答本文で返されます。
401   認証に失敗しました。
403 Error 権限が無いことが原因で、要求が失敗しました。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。
ホームの作成

ユーザーのホームを新しく作成します。
リクエストボディは"name"フィールドを含んでいる必要があります。

API Endpoint

POST /homes

Headers
Header Description Required
Authorization
string
ユーザーのAPIキーを使用する必要があります。 Yes
Request Body

Home (JSON)

Response
Code Body Description
201 Home ホームは正常に作成されました。作成されたオブジェクトが応答本文で返されます。
401   認証に失敗しました。
403 Error データが無効か、権限が無いことが原因で、要求が失敗しました。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。
ホームの取得

指定したIDのホームを返します。

API Endpoint

GET /homes/{homeId}

URI Parameters
Field Description Required
homeId
integer
ホームID Yes
Headers
Header Description Required
Authorization
string
ユーザーまたはプロジェクトのAPIキーを含んでいる必要があります。 Yes
Response
Code Body Description
200 Home 要求したホームが応答本文で返されます。
401   認証に失敗しました。
403 Error 権限が無いことが原因で、要求が失敗しました。
404 Error 要求したホームが存在しないか、アクセスが不可です。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。
ホームの更新

指定したIDのホームを更新します。ホームのdeactivatedフィールドに関しては、「管理タスク実行」権限が付与されたプロジェクトAPIキーによるリクエストでのみ、変更することができます。

API Endpoint

PATCH /homes/{homeId}

URI Parameters
Field Description Required
homeId
integer
ホームID Yes
Headers
Header Description Required
Authorization
string
ユーザーのAPIキーを使用する必要があります。 Yes
Request Body

Home (JSON)

Response
Code Body Description
204   ホームは正常に更新されました。
401   認証に失敗しました。
403 Error データが無効か、権限が無いことが原因で、要求が失敗しました。
404 Error 要求したホームが存在しないか、アクセスが不可です。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。
ホームの削除

指定したIDのホームを削除します。

API Endpoint

DELETE /homes/{homeId}

URI Parameters
Field Description Required
homeId
integer
ホームID Yes
Headers
Header Description Required
Authorization
string
ユーザーのAPIキーを使用する必要があります。 Yes
Response
Code Body Description
204   ホームは正常に更新されました。
401   認証に失敗しました。
403 Error データが無効か、権限が無いことが原因で、要求が失敗しました。
404 Error 要求したホームが存在しないか、アクセスが不可です。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。
ホームメンバーの取得

指定したホームに属するすべてのメンバーを取得します。

API Endpoint

GET /homes/{homeId}/members

URI Parameters
Field Description Required
homeId
integer
ホームID Yes
Headers
Header Description Required
Authorization
string
ユーザーあるいはプロジェクトのAPIキーを含んでいる必要があります。 Yes
Response
Code Body Description
200 Array of Home Members メンバーオブジェクトのリストが応答本文で返されます。
401   認証に失敗しました。
403 Error 権限が無いことが原因で、要求が失敗しました。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。
ホームメンバーの追加

プロジェクトのタイプに基づいて、このAPI呼び出しは次のいずれかを行います。

組み込みのアカウントシステムを利用するプロジェクト(電話番号ベース)

ホームにメンバーを追加します。メンバーの電話番号を指定する必要があります。
メンバーが既存のユーザーでない場合は、返されるメンバーオブジェクトの"verified"フィールドがfalseになります。招待するメンバーへのSMS送信は、アプリが行います。

組み込みのアカウントシステムを利用するプロジェクト(メールアドレスベース)

ホームにメンバーを追加します。メンバーのメールアドレスを指定する必要があります。
メンバーが既存のユーザーでない場合は、返されるメンバーオブジェクトの"verified"フィールドがfalseになります。招待するメンバーにメールが送信されます。

BYOU("Bring-Your-Own-Users")プロジェクト

指定したユーザーIDを持つ既存のユーザーをホームに追加します。

API Endpoint

POST /homes/{homeId}/members

URI Parameters
Field Description Required
homeId
integer
ホームID Yes
Headers
Header Description Required
Authorization
string
ユーザーのAPIキーを使用する必要があります。 Yes
Request Body

Web Form:

Field Description Required
phoneNumber
string
電話番号ベースのユーザーアカウントを使用するプロジェクトの場合は必須。 No
email
string
メンバーのメールアドレス。メールアドレスベースのユーザーアカウントを使用するプロジェクトの場合は必須。 No
userId
integer
有効なユーザーID。BYOUプロジェクトの場合に必須。 No
Response
Code Body Description
201 Home Member メンバーは正常に作成されました。作成されたオブジェクトが応答本文で返されます。
401   認証に失敗しました。
403 Error データが無効か、権限が無いことが原因で、要求が失敗しました。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。
ホームメンバーの取得

指定したユーザーIDを持つホームメンバーを取得します。

API Endpoint

GET /homes/{homeId}/members/{userId}

URI Parameters
Field Description Required
houmeId
integer
ホームID Yes
userId
integer
ユーザーID Yes
Headers
Header Description Required
Authorization
string
ユーザーあるいはプロジェクトのAPIキーを含んでいる必要があります。 Yes
Response
Code Body Description
200 Home Member 要求したユーザーが応答本文で返されます。
401   認証に失敗しました。
403 Error 権限が無いことが原因で、要求が失敗しました。
404 Error 要求したユーザーが存在しないか、アクセスが不可です。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。
ホームメンバーの削除

指定したユーザーをホームのメンバーから削除します。

API Endpoint

DELETE /homes/{homeId}/members/{userId}

URI Parameters
Field Description Required
homeId
integer
ホームID Yes
userId
integer
ユーザーID Yes
Headers
Header Description Required
Authorization
string
ユーザーのAPIキーを使用する必要があります。 Yes
Response
Code Body Description
204   メンバーは正常に削除されました。
401   認証に失敗しました。
403 Error データが無効か、権限が無いことが原因で、要求が失敗しました。
404 Error 要求したユーザーが存在しないか、アクセスが不可です。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。
スマートモジュールリストの取得

ホームに対して使用可能なスマートモジュールのリストを取得します。

API Endpoint

GET /homes/{homeId}/smartModules

URI Parameters
Field Description Required
homeId
integer
ホームID Yes
Headers
Header Description Required
Authorization
string
ユーザーあるいはプロジェクトのAPIキーを含んでいる必要があります。 Yes
Response
Code Body Description
200 Array of Smart Modules スマートモジュールオブジェクトのリストが応答本文で返されます。
401   認証に失敗しました。
403 Error 権限が無いことが原因で、要求が失敗しました。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。
スマートモジュールの取得

指定したスマートモジュールに関する情報を取得します。

API Endpoint

GET /homes/{homeId}/smartModules/{moduleId}

URI Parameters
Field Description Required
homeId
integer
ホームID Yes
moduleId
string
モジュールID Yes
Headers
Header Description Required
Authorization
string
ユーザーあるいはプロジェクトのAPIキーを含んでいる必要があります。 Yes
Response
Code Body Description
200 Smart Module 要求したスマートモジュールが返されます。説明などの公開された情報のみが含まれます。
401   認証に失敗しました。
403 Error 権限が無いことが原因で、要求が失敗しました。
404 Error 要求したスマートモジュールが存在しないか、アクセスが不可です。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。
ホームへのイベント送信

指定されたホームへイベントを送信し、該当するリスナーにイベントを伝播します。
プロジェクトのAPIキーを使用して送信します。

API Endpoint

PUT /homes/{homeId}/event

URI Parameters
Field Description Required
homeId
integer
ホームID Yes
Headers
Header Description Required
Authorization
string
イベントを送信できるプロジェクトのAPIキーを含んでいる必要があります。 Yes
Request Body

Event (JSON)
Example:

{
  "eventType": "sprinkler-status",
  "eventData": {
   "zones": [0,0,0,0,0,0,0,1],
   "serial": 12,
   "timestamp": 1402313424,
   "appSerial": 14,
   "appTimestamp": 14243423423
  }
}
Response
Code Body Description
204   データは正常に送信されました。
401   認証に失敗しました。
403 Error データが無効か、権限が無いことが原因で、要求が失敗しました。
404 Error 要求したスマートモジュールが存在しないか、アクセスが不可です。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。
オンデマンドデバイスのプロビジョニングの開始

プロジェクトのオンデマンドデバイスプロビジョニングが有効になっている場合、このAPIを使用して、ホームメンバーがホームに新しいデバイスを追加するプロセスを開始できます。
APIを呼び出すと、プロビジョニングを行うためのトークンが返却されるので、トークンをWi-FiやBluetoothなどを介してデバイスに渡します。
デバイスは受け取ったトークンをDevice APIに渡して、プロビジョニングプロセスを完了する必要があります。

API Endpoint

POST /homes/{homeId}/deviceProvisioning

URI Parameters
Field Description Required
homeId
integer
ホームID Yes
Headers
Header Description Required
Authorization
string
ユーザーのAPIキーを使用する必要があります。 Yes
Request Body

Web Form:

Field Description Required
deviceClass
string
デバイスを追加するデバイスクラスID。 Yes
deviceTag
string
追加されるデバイスに割り当てられる任意のタグ。 No
Response
Code Body Description
200 Device Provisioning Token デバイスのプロビジョニングトークンデータは返却されました。
401   認証に失敗しました。
403 Error データが無効か、権限が無いことが原因で、要求が失敗しました。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。

デバイス

ホームに登録されたクラウド対応のデバイスを管理します。
デバイスによって、クラウドに直接接続するものと、ゲートウェイなどの制御下に置かれるものがあります。

デバイスリストの取得

ホームのデバイスのリストを取得します。

API Endpoint

GET /devices

Headers
Header Description Required
Authorization
string
ユーザーあるいはプロジェクトのAPIキーを含んでいる必要があります。 Yes
Query Parameters
Field Description Required
homeId
integer
指定したホームに属するデバイスを返します。 Yes
Response
Code Body Description
200 Array of Devices デバイスオブジェクトのリストが応答本文で返されます。
401   認証に失敗しました。
403 Error 権限が無いことが原因で、要求が失敗しました。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。
ホームへのデバイスの追加

ユーザーのホームにデバイスを追加します。
プロジェクトの設定によって以下の2つの方法があります。

デバイスが事前プロビジョニングされる場合

すべてのデバイスを事前プロビジョニングをするようにプロジェクトが構成されている場合は、ホームにデバイスを追加すると既存のデバイスの所有権が要求され、指定したホームにデバイスが登録されます。
このシナリオでは、ユーザーがこのメソッドを呼び出す前に、指定のデバイスを登録可能にする必要があります。

デバイスがオンデマンドでプロビジョニングされる場合

オンデマンドデバイスプロビジョニングを許可するようにプロジェクトが構成されている場合、ユーザーはまず始めにオンデマンドデバイスプロビジョニング開始APIを呼び出し、プロビジョニングトークンを取得する必要があります。
プロビジョニングトークンをデバイスに渡し、このAPIをデバイスから呼び出すことでプロビジョニングプロセスを完了できます。
返却されるDeviceオブジェクトにはAPIキーが含まれています。デバイスIDとAPIキーをデバイスに保持することで、IoTデバイスハブのAPIと直接通信を開始できます。

API Endpoint

POST /devices

Headers
Header Description Required
Authorization
string
ユーザーのAPIキーを使用する必要があります。デバイスが事前プロビジョニングされている場合必須。 No
Request Body

Web Form:

Field Description Required
homeId
integer
デバイスを追加するホームのID。デバイスが事前プロビジョニングされる場合は必須。 No
claimCode
string
追加するデバイスに割り当てられる固有のクレームコード。デバイスが事前プロビジョニングされる場合は必須。 No
token
string
追加するデバイス用に発行されたデバイスプロビジョニングトークン。オンデマンドデバイスプロビジョニングの場合に必須。 No
Response
Code Body Description
201 Device デバイスは正常に作成されました。作成されたオブジェクトが応答本文で返されます。
401   認証に失敗しました。
403 Error データが無効か、権限が無いことが原因で、要求が失敗しました。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。
デバイス情報の取得

指定したIDのデバイスを返します。

API Endpoint

GET /devices/{deviceId}

URI Parameters
Field Description Required
deviceId
integer
デバイスID Yes
Headers
Header Description Required
Authorization
string
ユーザー、プロジェクトあるいはデバイスのAPIキーを含んでいる必要があります。 Yes
Response
Code Body Description
200 Device 要求したデバイスが応答本文で返されます。
401   認証に失敗しました。
403 Error 権限が無いことが原因で、要求が失敗しました。
404 Error 要求したデバイスが存在しないか、アクセスが不可です。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。
デバイス情報の更新

指定したIDのデバイスを更新します。

API Endpoint

PATCH /devices/{deviceId}

URI Parameters
Field Description Required
deviceId
integer
デバイスID Yes
Headers
Header Description Required
Authorization
string
ユーザーのAPIキーを使用する必要があります。 Yes
Request Body

Device (JSON)

Response
Code Body Description
204 デバイスは正常に更新されました。
401   認証に失敗しました。
403 Error データが無効か、権限が無いことが原因で、要求が失敗しました。
404 Error 要求したデバイスが存在しないか、アクセスが不可です。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。
デバイスの削除

指定したIDのデバイスを削除します。

API Endpoint

DELETE /devices/{deviceId}

URI Parameters
Field Description Required
deviceId
integer
デバイスID Yes
Headers
Header Description Required
Authorization
string
ユーザーのAPIキーを使用する必要があります。 Yes
Response
Code Body Description
204   デバイスは正常に削除されました。
401   認証に失敗しました。
403 Error データが無効か、権限が無いことが原因で、要求が失敗しました。
404 Error 要求したデバイスが存在しないか、アクセスが不可です。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。
コマンドの送信

指定したデバイスにコマンドを発行します。

API Endpoint

PUT /devices/{deviceId}/command

URI Parameters
Field Description Required
deviceId
integer
デバイスID Yes
Headers
Header Description Required
Authorization
string
ユーザーあるいはプロジェクトのAPIキーを含んでいる必要があります。 Yes
Request Body

Device Command (JSON)
Example:

{
  "action": "sprinkler-on",
  "parameters": {
    "zone": 2,
    "duration": 120
  }
}
Response
Code Body Description
204   データは正常に送信されました。
401   認証に失敗しました。
403 Error データが無効か、権限が無いことが原因で、要求が失敗しました。
404 Error 要求したデバイスが存在しないか、アクセスが不可です。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。
コマンドの受信

WebSocket接続を確立し、コマンドを受信します。
この呼び出しを行うことができるのは、WebSocketに対応するデバイスに限られます。
WebSocket以外の要求はすべて拒否されます。
一旦接続が確立されると、クライアントはPUTメソッドで使用されるデバイスコマンドJSONオブジェクト形式の着信メッセージを要求することができます。
WebSocketクライアントの実装によっては、Authorization HTTPヘッダーを設定できないことがありますが、その場合はデバイスAPIキーをauthTokenクエリパラメーターとして渡すことができます。

API Endpoint

GET /devices/{deviceId}/command

URI Parameters
Field Description Required
deviceId
integer
デバイスID Yes
Headers
Header Description Required
Authorization
string
関連するデバイスのAPIキーを含んでいる必要があります。 Yes
Query Parameters
Field Description Required
authToken
string
デバイスに割り当てられたAPIキー。Authorizationヘッダーを設定できない場合のみ必須。 No
Response
Code Body Description
101   WebSocket接続が正常に確立されました。
401   認証に失敗しました。
403 Error データが無効か、権限が無いことが原因で、要求が失敗しました。
404 Error 要求したリソースが存在しないか、アクセスが不可です。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。
デバイスイベントの送信

デバイスイベントをクラウドに送信し、そこから他の関連リスナーにイベントを伝搬します。
この呼び出しを行うことができるデバイスは限られています。

API Endpoint

PUT /devices/{deviceId}/event

URI Parameters
Field Description Required
deviceId
integer
デバイスID Yes
Headers
Header Description Required
Authorization
string
関連するデバイスのAPIキーを含んでいる必要があります。 Yes
Request Body

Event (JSON)
Example:

{
  "eventType": "sprinkler-status",
  "eventData": {
    "zones": [0,0,0,0,0,0,0,1],
    "serial": 12,
    "timestamp": 1402313424,
    "appSerial": 14,
    "appTimestamp": 14243423423
  }
}
Response
Code Body Description
204   データは正常に送信されました。
401   認証に失敗しました。
403 Error データが無効か、権限が無いことが原因で、要求が失敗しました。
404 Error 要求したイベントが存在しないか、アクセスが不可です。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。

認証

APIクライアント認証を処理するためのリソースです。
これらのリソースは、RESTfulモデルに厳密には準拠していません。

認証状態の取得

API要求のHTTP Authorizationヘッダーで使用されている認証トークンをテストします。

API Endpoint

GET /auth

Headers
Header Description Required
Authorization
string
有効なAPIキーを含んでいる必要があります。 Yes
Response
Code Body Description
200 Authentication Info クライアントのIDに関する情報。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。
ユーザーの認証

プロジェクトのタイプに基づいて、このAPI呼び出しは次のいずれかを行います。

組み込みのアカウントシステムを利用するプロジェクト(電話番号ベース)

SMSでユーザーに送信されるAPIキーの認証コードを交換します。
リクエストボディには、phoneNumber、appId、およびcodeの各パラメーターが含まれている必要があります。

組み込みのアカウントシステムを利用するプロジェクト(メールアドレスベース)

パスワードによってユーザーを認証し、APIキーを返します。
リクエストボディには、email、appId、およびpasswordの各パラメーターが含まれている必要があります。

BYOU("Bring-Your-Own-Users")プロジェクト

ユーザーのAPIキーを取得します。
リクエストボディには、userIdパラメーターとprojectIdパラメーターが含まれている必要があります。
また、BYOUのプロジェクトAPI Keyを含むAuthorizationヘッダーが要求に組み込まれている必要があります。

API Endpoint

POST /auth/user

Headers
Header Description Required
Authorization
string
BYOUのプロジェクトAPI Keyを含んでいる必要があります。BYOUプロジェクトの場合のみ必須。 No
Request Body

Web Form:

Field Description Required
projectId
integer
ユーザーが属するプロジェクトのID。 Yes
appId
string
APIにアクセスするために使用されるアプリのID。BYOUプロジェクトの場合を除いて必須。 No
phoneNumber
string
認証されるユーザーの電話番号。
電話番号ベースのユーザーアカウントを使用するプロジェクトの場合のみ必須。
No
code
string
SMS経由でユーザーに送信される認証コード。
電話番号ベースのユーザーアカウントを使用するプロジェクトの場合のみ必須。
No
email
string
認証されるユーザーのメールアドレス。
メールアドレスベースのユーザーアカウントを使用するプロジェクトの場合のみ必須。
No
password
string
認証されるユーザーのパスワード。
メールアドレスベースのユーザーアカウントを使用するプロジェクトの場合のみ必須。
No
userId
integer
認証されるユーザーのID。BYOUプロジェクトの場合のみ必須。 No
Response
Code Body Description
200 Client Authentication ユーザー認証が成功しました。
401   認証に失敗しました。
403 Error データが無効か、権限が無いことが原因で、要求が失敗しました。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。
SMSによるユーザー認証の開始

ユーザーにSMSテキストを送信することによって認証プロセスを開始します。
テキストには、認証トークンと交換するユーザーの認証コードが含まれています。
このAPI呼び出しは、電話番号ベースのユーザーアカウントを使用するプロジェクトの場合にのみ可能です。

API Endpoint

POST /auth/user/sms

Request Body

Web Form:

Field Description Required
projectId
integer
ユーザーが属するプロジェクトのID。 Yes
phoneNumber
string
認証されるユーザーの電話番号。この電話番号はユーザー作成API呼び出しによってIoTデバイスハブにすでに登録されている必要があります。 Yes
Response
Code Body Description
200 SMS Message Receipt SMSメッセージが正常に送信されました。
401   認証に失敗しました。
403 Error データが無効か、権限が無いことが原因で、要求が失敗しました。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。
ユーザーのメールアドレスの確認

メール確認トークンによってユーザーアカウントを確認します。
このAPI呼び出しは、メールアドレスベースのユーザーアカウントを使用するプロジェクトの場合にのみ可能です。

API Endpoint

POST /auth/user/emailVerification

Request Body

Web Form:

Field Description Required
token
string
ユーザーにメールで送信される確認トークン。 Yes
Response
Code Body Description
200   ユーザーのIDが確認されました。
401   認証に失敗しました。
403 Error データが無効か、権限が無いことが原因で、要求が失敗しました。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。
ユーザーのメール確認の開始

確認メールを送信してアカウント確認プロセスを開始します。元のメッセージを紛失したユーザーが対象です。このAPI呼び出しは、メールアドレスベースのユーザーアカウントを使用するプロジェクトの場合にのみ可能です。

API Endpoint

POST /auth/user/emailVerification/start

Request Body

Web Form:

Field Description Required
projectId
integer
ユーザーが属するプロジェクトのID。 Yes
email
string
ユーザーのメールアドレス。 Yes
Response
Code Body Description
200   指定したメールアドレスにメールが送信されました。
401   認証に失敗しました。
403 Error データが無効か、権限が無いことが原因で、要求が失敗しました。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。
ユーザーパスワードのリセット

ユーザーのパスワードをリセットします。
このAPI呼び出しは、メールアドレスベースのユーザーアカウントを使用するプロジェクトの場合にのみ可能です。

API Endpoint

POST /auth/user/passwordReset

Request Body

Web Form:

Field Description Required
token
string
ユーザーにメールで送信されるパスワードリセットトークン。 Yes
newPassword
string
ユーザーのアカウントの新規パスワード。 Yes
Response
Code Body Description
200   ユーザーパスワードは正常に更新されました。
401   認証に失敗しました。
403 Error データが無効か、権限が無いことが原因で、要求が失敗しました。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。
ユーザーパスワードのリセットの開始

パスワードリセットトークンを含むメールを送信して、パスワードリセットプロセスを開始します。
パスワードを忘れたユーザーが対象です。
このAPI呼び出しは、メールアドレスベースのユーザーアカウントを使用するプロジェクトの場合にのみ可能です。

API Endpoint

POST /auth/user/passwordReset/start

Request Body

Web Form:

Field Description Required
projectId
integer
ユーザーが属するプロジェクトのID。 Yes
email
string
ユーザーのメールアドレス。 Yes
Response
Code Body Description
200   指定したメールアドレスにメールが送信されました。
401   認証に失敗しました。
403 Error データが無効か、権限が無いことが原因で、要求が失敗しました。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。

デバイス登録

ホームにデバイスを登録するプロセスを開始するためのもの。プロジェクトがオンデマンドデバイスプロビジョニングを許可するように構成されていない限り、この手順は必須です。

デバイス登録状態の更新

指定したデバイスの登録状態を変更します。この要求を行うことができるのは、そのデバイス自体に限られます。

API Endpoint

POST /deviceRegistration

Headers
Header Description Required
Authorization
string
対象デバイスのAPIキーを含んでいる必要があります。 Yes
Request Body

Web Form:

Field Description Required
deviceId
integer
変更するデバイスのID。 Yes
claimable
boolean
trueの場合、デバイスをクレーム可能に設定します。 Yes
duration
integer
クレーム可能状態にする期間(秒)。 No
Response
Code Body Description
200 Registration State Response 指定したデバイスは新しい状態に正常に設定されました。
401   認証に失敗しました。
403 Error データが無効か、権限が無いことが原因で、要求が失敗しました。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。

ユーザーセッション

このリソースは、ユーザーがAPIサービスによって正常に認証された後で使用可能になります。

ユーザーセッション情報の取得

現在のユーザーセッションに関する情報を取得します。

API Endpoint

GET /userSession

Headers
Header Description Required
Authorization
string
ユーザーのAPIキーを使用する必要があります。 Yes
Response
Code Body Description
200 User Session Info 要求したユーザーセッションが応答本文で返されます。
401   認証に失敗しました。
403 Error 権限が無いことが原因で、要求が失敗しました。
404 Error 要求したユーザーセッションが存在しないか、アクセス不能です。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。
ユーザーセッションの終了

ユーザーセッションを終了します。関連したAPIキーも無効になります。

API Endpoint

DELETE /userSession

Headers
Header Description Required
Authorization
string
ユーザーのAPIキーを使用する必要があります。 Yes
Response
Code Body Description
204   ユーザーセッションは終了しました。
401   認証に失敗しました。
403 Error データが無効か、権限が無いことが原因で、要求が失敗しました。
404 Error 要求したユーザーセッションが存在しないか、アクセス不能です。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。
イベントのリッスン

WebSocket接続を確立し、イベントをリッスンします。
WebSocket以外の要求はすべて拒否されます。
接続が確立されると、クライアントは、デバイスイベントJSONオブジェクト形式のメッセージの着信を待ち受けます。
WebSocketクライアントの実装によっては、Authorization HTTPヘッダーを設定できないことがあるので、その場合はユーザーAPIキーをauthTokenクエリーパラメーターとして渡すことができます。
このAPI呼び出しは、BYOUプロジェクトの場合は許可されません。

API Endpoint

GET /userSession/websocket

Headers
Header Description Required
Authorization
string
ユーザーのAPIキーを使用する必要があります。 Yes
Query Parameters
Field Description Required
authToken
string
ユーザーAPIキー。Authorizationヘッダーを設定できない場合のみ必須。 No
Response
Code Body Description
101   WebSocket接続が正常に確立されました。
401   認証に失敗しました。
403 Error データが無効か、権限が無いことが原因で、要求が失敗しました。
404 Error 要求したリソースが存在しないか、アクセス不能です。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。

キーバリューペアの取得

指定したホームに保存されたすべてのキーバリューペアを取得します。

API Endpoint

GET /homes/{homeId}/kv

URI Parameters
Field Description Required
homeId
integer
ホームID Yes
Headers
Header Description Required
Authorization
string
ユーザーまたはプロジェクトのAPIキーを含んでいる必要があります。 Yes
Query Parameters
Field Description Required
keyPrefix
string
指定した場合、そのプレフィックスを含むキーを持つアイテムだけを返します。 No
Response
Code Body Description
200 Array of Key-Value Pairs キーバリューペアオブジェクトの配列が返されます。
401   認証に失敗しました。
403 Error 権限が無いことが原因で、要求が失敗しました。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。

キーバリューペアの削除

指定したキーに対応するキーバリューペアを削除します。

API Endpoint

DELETE /homes/{homeId}/kv/{key}

URI Parameters
Field Description Required
homeId
integer
ホームID Yes
key
string
ホームに保存された1つのキーバリューペアに対応する一意なキー。 Yes
Headers
Header Description Required
Authorization
string
ユーザーまたはプロジェクトのAPIキーを含んでいる必要があります。 Yes
Response
Code Body Description
204 Key-Value Pairs キーバリューストアは正常に削除されました。
401   認証に失敗しました。
403 Error 権限が無いことが原因で、要求が失敗しました。
404 Error 要求したキーバリューストアは存在しないかアクセスできません。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。

キーバリューペアの作成・更新

指定したキーに値をセットします。キーバリューペアがまだ存在しない場合には、作成されます。

API Endpoint

PUT /homes/{homeId}/kv/{key}

URI Parameters
Field Description Required
homeId
integer
ホームID Yes
key
string
ホームに保存された1つのキーバリューペアに対応する一意なキー。 Yes
Headers
Header Description Required
Authorization
string
ユーザーまたはプロジェクトのAPIキーを含んでいる必要があります。 Yes
Request Body

Key-Value Pair(JSON)

Response
Code Body Description
204   キーバリューストアは正常に保存されました。
401   認証に失敗しました。
403 Error 権限が無いことが原因で、要求が失敗しました。
404 Error 要求したキーバリューストアは存在しないかアクセスできません。
500 Error 予期しないエラーが発生しました。
503 Error 一時的にサービスを利用できません。

推奨画面サイズ 1024×768 以上