Cassia RESTful APIの概要 – サポートページTOP

Cassia Bluetoothゲートウェイは、エンタープライズ利用向けに設計された世界初の長距離Bluetoothゲートウェイであり、あらゆるサイズと規模のシームレスなカバレッジを可能にします。 Bluetoothの範囲を最大300m（オープンスペース、視線）まで拡張し、Bluetoothデバイスに変更を加えることなく複数のBluetooth Low Energy（BLE）デバイスのリモートコントロールを可能にします。

Cassia RESTful APIは、サードパーティの開発者とデバイスメーカーが、お客様のクラウドサービスを使用してゲートウェイごとに複数のBLEデバイスを同時に接続および制御しながら、CassiaゲートウェイのBluetoothルーティングと拡張範囲機能を利用できるようにするために開発されました。さらに、Cassia RESTful APIは、プログラミング言語の柔軟性（C＃、Node.js、Java、およびその他の任意の言語）を提供するHTTP / HTTPSベースの通信プロトコルを使用して、アプリケーションとサーバーに直接統合するように設計されています。詳細については以下参考URLを参照ください。

参考URL：Cassia SDK Implementation Guide

https://github.com/CassiaNetworks/CassiaSDKGuide/wiki

Cassia RESTful APIは、次の機能を提供します。

BLEデバイスを接続して制御
スキャン、接続、ブロードキャストの3つのモードをサポート
BLEデバイスとの間でデータの書き込み/読み取り
BLEデバイスから通知/表示イベントとしてデータを読み取り

2種類のRESTfulAPI

Cassiaは、BLEデバイスとCassiaゲートウェイの相互作用を可能にする2種類のRESTfulAPIを提供します。

１．ローカルゲートウェイ上のAPI

ゲートウェイと同一ネットワーク上に存在するアプリケーション（アーキテクチャ図　図1）や、ゲートウェイ内Container上のアプリケーション（アーキテクチャ図　図2）からAPIを利用したい場合に使用します。

２．Cassia IoT アクセスコントローラー（Cassia AC）を介したAPI

APIはCassia ACを介して使用することができます。（アーキテクチャ図　図3）

以下APIはAC経由のみ利用できます。これらのAPIを除いて、2種類のRESTful APIは同じであり、同じ結果が得られます。

注意事項：

Cassia ACを介したRESTfulAPIには、{your AC domain}の後に"/ api"が含まれています。ローカルゲートウェイのRESTfulAPIには必要ありません。
Cassia ACを介したRESTfulAPIには、使用されているゲートウェイを識別するための"mac="が含まれています。ローカルゲートウェイのRESTfulAPIには必要ありません。
ファームウェア1.3以降では、ゲートウェイモードが”Standalone Gateway”として構成されている場合、ローカルのRESTfulAPIが自動的にオンになります。（既定は”AC Managed Gateway"）ゲートウェイ”AC Managed Mode”として設定されている場合、ローカルRESTful APIはデフォルトでオフになります（お客様はACコンソールからローカルRESTful APIを有効にできます）。設定方法は以下手順をご覧ください。

手順：

１．ローカルWebコンソールから設定する場合

ローカルWebコンソールにログインしBasicメニュー→Gateway Modeを”Standalone Gateway”に設定

２．Cassia アクセスコントローラ（AC）を使用して設定する場合

アクセスコントローラログインいただき以下操作ください。

1）Gatewayメニュー選択

2）操作したいCassia Gatewayのラインをクリック

３）Configメニュー選択しLocal RESTful APIを“ON”に設定

４）“Save”ボタンをクリック

Cassia IoT Access Controller（AC）は、強力なIoTネットワーク管理ソリューションです。これは、企業がデータ収集、配置、およびセキュリティポリシー管理を行うためのRESTful APIを提供し、インターネットを介したCassiaBluetoothゲートウェイのリモート制御を可能にします。

BLEデバイスは、CassiaゲートウェイおよびCassiaACを介して一連のRESTfulAPIを使用して操作できます。それぞれのCassia RESTful APIの動作図については、以下の図を参照してください。

図1．同一ネットワーク上に存在するアプリケーションとの通信

図2．Container内のアプリケーションとの通信

図3．アクセスコントローラを介したアプリケーションとの通信

Cassia ACを介してRESTful API通信を利用する場合、まずビジネスアプリケーションは、Cassia ACに対して（開発者の資格情報を使用して生成された）OAuth認証要求を開始します。認証が成功すると、RESTfulに基づいてCassiaACにHTTPクエリを送信します。次に、Cassia ACは、暗号化されたCAPWAPを介して対応するBluetoothゲートウェイにクエリを送信します。次に、ゲートウェイはBLEデバイスに対してクエリを実行し、その結果をCassia ACに返し、次にビジネスアプリケーションに返します。

Server Sent Events (SSE)
SSEは、ブラウザーがHTTP接続を介してサーバーから自動更新を受信するテクノロジーです。 SSE APIは、W3CによってHTML5の一部として標準化されています。 SSEは、メッセージの更新または継続的なデータストリームをブラウザクライアントに送信するために使用されます。手動で終了する必要があります。そうしないと、エラーが発生するまで実行を続けます。

SSE仕様：https：//html.spec.whatwg.org/multipage/server-sent-events.html#the-eventsource-interface

APIは、ユーザーが接続がアクティブかどうかを確認するために、SSE接続で30秒ごとに"keep-alive"を送信します。

キープアライブロスト、ソケットエラー、ネットワークの問題など、接続が異常に終了した場合、ユーザーはCassia RESTfulAPIを呼び出してSSEを再接続する必要があります。

Nodejsライブラリの"eventsource"はSSEの再接続を自動的に処理します。他の言語の場合、再接続はユーザーアプリケーションによって処理される必要がある場合があります。

6つのRESTfulAPIがSSEを使用しています。

各SSE応答は、”data”始まります。デバッグ時に、SSEのURLをWebブラウザーに入力すると、WebブラウザーからのSSE出力が表示されます。

プログラムでは、通常のHTTPリクエストのようにインターフェースを呼び出すと、SSEリクエストはデータを返しません。これは、通常のHTTPリクエストは終了したときにのみ出力を返すためです。さらに、SSEを呼び出すときは、このスレッドを監視する必要があります。エラーまたは予期しないインシデントによって中断された場合は、再起動できます。

注：HTTPリクエストにCURLなどのツールを使用する場合、ツールはHTTPリクエストが終了したときにデータを返します。ただし、SSE APIは終了せず、ストリームでデータを送信するため、ページがハングします。次のスニペットを追加する必要があります（例としてスキャンを使用）。

PHP

if ($stream = fopen($url_for_scan, 'r')) {
  while(($line=fgets($stream))!== false){
    echo $line;
  }
}

[Update]

更新日：202109

2種類のRESTfulAPI

１．ローカルWebコンソールから設定する場合

２．Cassia アクセスコントローラ（AC）を使用して設定する場合

関連記事