本文へジャンプします。

ニフクラ ユーザーガイド

リファレンス

概要

ニフクラIoTデバイスハブのAPIはHTTPベースのAPIとなり、ハードウエアデバイス、モバイルアプリ、およびスマートモジュールはこのAPIを使用してクラウドと簡単に通信ができます。

すべてのAPIリクエストは、HTTPS経由でセキュアに行う必要がありますが、HTTPS接続を確立できないデバイスを使用したプロトタイピングのために、暗号化されていないHTTP経由でAPIを使用することもできます。
実動システムでは、非セキュアなアクセスは使用しないことを強くお勧めします。

エンドポイント

ニフクラIoTデバイスハブAPIのエンドポイントは以下の通りです。

iot-device.jp-east-1.api.cloud.nifty.com

リクエストヘッダー

Content Type と Content Length

APIリクエストにリクエストボディが含まれている場合は、Content-TypeヘッダーとContent-Lengthヘッダーも含まれている必要があります。APIリソース/エンドポイントによっては、リクエストボディは、JSON(application/json)またはWebフォーム(application/x-www-form-urlencoded)のどちらかの形式であることが期待されています。

Authorization

一部のリソース/エンドポイントには、特定の許可されたクライアントのみがアクセスできるメソッドがあります。これらの制限付きメソッドにアクセスするには、クライアントはAuthorizationリクエストヘッダーを利用する必要があります。このヘッダーは、次の形式で指定します。

Authorization: ModeCloud <AUTH_CODE>

<AUTH_CODE>は認証トークンです。
認証トークンを取得する方法は、次に説明するように、APIクライアントの性質によって異なります。

クライアント認証

APIに対するリクエストは、通常はユーザー(モバイルあるいはwebアプリを使用)、デバイス、または認可された外部のプログラム/サービスのいずれかのエンティティーによって行われます。
APIクライアントは、認証トークンを含むAuthorizationリクエストヘッダーを使用して自身を識別できます。このトークンを取得する方法を以下に示します。

ユーザーの場合

認証のエンドポイントに対するリクエストによってトークンを取得します。
プロジェクトの設定によっては、ユーザー認証の一環として、SMS、パスワードの直接入力、または特殊なサーバー間APIを利用した確認が行われる場合があります。

デバイスの場合

トークンは、プロビジョニング時にデバイスインスタンスに割り当てられたAPIキーです。
デバイスが事前プロビジョニング済みの場合は、コントロールパネルからこのキーを取得できます。オンデマンドデバイスプロビジョニングを使用する場合は、デバイスをホームに追加するAPI呼び出しの中でこのキーが返されます。

その他のクライアントの場合

外部プログラムやサービスをニフクラIoTデバイスハブと連携するためには、プロジェクトのAPIキーが必要です。
外部サービスとは例えば、定期的にデバイスにコマンドを送信するスケジューラサービスのことです。また、独自のユーザ管理システムでデバイスハブのユーザ管理を行いたい場合には、ユーザーの登録およびログイン時にその外部システムからIoTデバイスハブのAPIを呼ぶ必要があります。 コントロールパネルのプロジェクトの設定画面で、これらAPIクライアント用のAPIキーを用意できます。また、キーごとにパーミッション設定があり、キーが利用できる機能を制御できます。

WebSocketエンドポイント

APIエンドポイントのいくつかは、クライアントがWebSocket接続を確立するためのものです。これらは通常のRESTful APIリソースとは異なる動作をします。例えば、次のようなものがあります。

  • ユーザーがホームで発生するイベントをリッスンするためのWebSocketエンドポイント。
  • デバイスがコマンドをリッスンするためのWebSocketエンドポイント。

リソース

クライアントが使用できるAPIリソース/エンドポイントを以下に示します。

ユーザー プロジェクトの登録済みエンドユーザー。
ホーム 「ホーム」はデバイスのコンテナーを表し、1人以上のユーザーによって所有/管理されます。
デバイス ホームに登録されたクラウド対応のデバイス。デバイスによってクラウドに直接接続するものと、ゲートウェイなどの制御下に置かれるものがあります。
認証 APIクライアント認証を処理するためのリソース。これらのリソースは、RESTfulモデルに厳密には準拠していません。
デバイス登録 ホームにデバイスを登録するプロセスを開始するためのリソース。プロジェクトがオンデマンドデバイスプロビジョニングを許可するように構成されていない限り必須です。
ユーザーセッション このリソースは、ユーザーがAPIサービスによって正常に認証された後で使用可能になります。

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