RESTについて

概要

Things Cloudでは、すべての外部通信向けにRESTを採用しています。IoTデバイス、Webアプリケーション、バックオフィスITシステムのどれから通信が生じるかに問わず、通信プロトコルは常にRESTです。

RESTはHTTP(S)およびTCPを基本とする、非常に簡易でありながらセキュアなプロトコルです。現在、ごく単純なデバイスから大規模ITに至るまで、あらゆるネットワーク型プログラミング環境が対応する、事実上のインターネット標準です。

このセクションではThings CloudにおけるRESTインターフェースについて、以下の内容で説明します。

  • Things Cloudに加わるアプリケーションの開発

この説明は各インターフェースを詳細に記されたリファレンスガイドと関連しています。 リファレンスガイドでとくに関連する章は以下の通りです。

一般的なRESTインターフェースおよびRESTとデバイスの統合の詳細については、Device のRESTのセクションを参照してください。

JavaまたはC#を使用して開発を行う場合、Things Cloudの機能性へのアクセスが一層便利になるよう、該当する開発者向けガイドをチェックしてください。

RESTインターフェースの使用法

現在、ほとんどのプログラミング環境において、RESTベース通信への対応が際立っています。Things CloudのRESTインターフェースを理解し、使用するにあたり、利用できる膨大なコマンドラインツールやブラウザ拡張機能が役立ちます。

例えば、多数のオペレーティングシステムに「curl」コマンドが予めインストールされています。Things Cloud APIのブラウジングを開始したい場合、以下のコマンドラインが基本となります。

$ curl -u <username>:<password> https://<yourURL>/platform

「username」と「password」を、自分がThings Cloudに登録する際に使用するユーザー名とパスワードに書き換えます。同様に、「yourURL」を、登録時に使用するURLに書き換えます。

コマンドはThings Cloudのあらゆる基本的インターフェースにリンクを返します。

...
"inventory": {
    "managedObjects": {
        "references": [],
        "self": "https://<yourURL>/inventory/managedObjects"
    },
    "managedObjectsForFragmentType": "https://<yourURL>/inventory/managedObjects?fragmentType={fragmentType}",
    "managedObjectsForListOfIds": "https://<yourURL>/inventory/managedObjects?ids={ids}",
    "managedObjectsForType": "https://<yourURL>/inventory/managedObjects?type={type}",
    "self": "https://<yourURL>/inventory"
},
...

Mac上で出力形式をもっと整えたい場合、「curl ... | python -mjson.tool」を試してみてください。

この時点から、ナビゲーションをさらに進めることができます。例えば、「managedObjects」リンクを辿ると、インベントリ内の項目が表示されます。

$ curl -u <username>:<password> https://<yourURL>.je1.thingscloud.ntt.com/inventory/managedObjects

インベントリ内の項目のサブセットが実際に返されることが分かります。これが所謂「ページ」です。ページの扱い方について詳しくはクエリ結果のページングをご覧ください。

ここでは簡略化のため認証情報を <username>:<password> で指定する方法をとっていますが、ホスト名と yourURL が異なるケースもあり得ます。デバイスエージェントのようにユースケースが特定されない場合は、RESTの実装 に述べられるように、<tenant ID>/<username>:<password> の形式で生成すべきです。

Postmanの使用

RESTインターフェースやThings Cloudデータベースのコンテンツを探索する場合、PostmanのようなグラフィカルRESTクライアントが便利です。 Cumulocity 社から多くの API コマンドのサンプルが提供されています。利用する場合、Postman をダウンロードしてインストール してください。Postman を開始した後、create an account または、Take me straight to the app を選べます。下のボタンをクリックし、インストールした Postman のタイプを選びます。ブラウザから、Postman を本当に実行してよいかセキュリティープロンプトが出るかも知れません。

Example REST client

Postmanおよび重要なREST APIコマンドのサンプルをセットアップするには、下記のボタンをクリックします。

Run in Postman

では、最上段のタブにある "Collections" をクリックしてください。"Cumulocity API" フォルダ を例としてみましょう。フォルダ、"Alarms" サブフォルダを開き、"Get collection of alarms" をクリックしてください。これで Things Cloud からどのようにアラームを取得するかの例が示されます。

例にはプレースホルダが含まれていることに注意してください。この例では、"{{url}}/alarm/alarms" にある "url" がプレースホルダです。Postman にこのようなプレースホルダの埋め方を指定し、どの Things Cloud アカウントに接続するかを指定する必要があります。このため、"environment"を作成し、プレースホルダを設定してください。

  • 右上の歯車をクリックし、"Manage Environments" を選び、"Add" をクリックしてください。
  • environment の名前(例えばテナント名)を入力して、プレースホルダの値を追加してください。
  • キー "url" の値を "https://<yourURL>.je1.thingscloud.ntt.com" に設定し、"Submit" をクリックしてください。
  • キー "auth" の値を REST要求の "Authorization" ヘッダーの値に設定してください。
  • "Add" をクリックし、ダイアログをクローズしてください。これで新しくつくられた environment が右上のドロップダウン(最初 "No environment" になっています)から選べるようになります。

Postman environment setup

Web 上には Base64 を行うツールがあります。このようなツールを利用すれば、キー "auth" の正しい値を簡単に得られます。例:あなたのテナント名を "tenant"、ユーザー名を "me" とし、パスワードを "secret" とします。ツールで ""tenant/me:secret" を Base64 に変換してください。変換後、テキストは "dGVuYW50L21lOnNlY3JldA==" になります。"auth" の値に "Basic dGVuYW50L21lOnNlY3JldA==" を利用してください。

色々なAPI を使ってみましょう。