RESTについて

概要

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

RESTはHTTP(S) とTCPをベースにした非常にシンプルでセキュアなプロトコルです。現在、非常にシンプルなデバイスから大規模なITに至るまで、すべてのネットワーク型プログラミング環境でサポートされている事実上のインターネット標準となっています。RESTを紹介している多くの本の中の一つにRESTful Web Servicesがあります。

ここでの説明は、各インターフェースの詳細が記載されたリファレンスガイドと密接に関連しています。 リファレンスガイド内の関連する章は、次のとおりです。

JavaまたはC#を使用してアプリケーションを開発する場合は、Things Cloudの機能にさらに簡単にアクセスできるよう、このガイドの関連するセクションもご覧ください。

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

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

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

$ curl -u <username>:<password> https://<yourTenant>.je1.thingscloud.ntt.com/platform

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

このコマンドは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"
},
...

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

$ curl -u <username>:<password> https://<yourTenant>.je1.thingscloud.ntt.com/platform | python -m json.tool

この時点より、返されるさまざまなオブジェクトへ移動することができます。たとえば、managedObjectsエンドポイントに従って、インベントリ内の項目を取得できます。

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

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

Postmanの使用

RESTインターフェースやThings Cloudデータベースのコンテンツを探索する場合、PostmanのようなグラフィカルRESTクライアントが便利です。

Example REST client

Cumulocity 社から多くの API コマンドのサンプルが提供されています。利用する場合、Postman をダウンロードしてインストール してください。Postman を開始した後、create an account または、Take me straight to the app を選べます。下のボタンをクリックし、インストールした Postman のタイプを選びます。ブラウザ( Windows の"Electron”)から、Postman を本当に実行してよいかセキュリティープロンプトが出る場合もあります。

Run in Postman

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

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

Postman environment setup

キー auth の正しい値を簡単に得るには、Web上から手に入るBase64エンコード/デコード・ツールを使用すると良いでしょう。たとえば、テナントIDが"tenant”、ユーザー名が"me”、パスワードが"secret"とします。まず、ostermiller.org/calc/encode.htmlへ行き、tenant/me:secretをテキストボックスに入力し、“Base 64"列のEncodeをクリックします。変換後、テキストは"dGVuYW50L21lOnNlY3JldA=="になり、キー auth の値には"Basic dGVuYW50L21lOnNlY3JldA=="を設定してください。

次のようにBase64コマンドを使用しても、同じ結果が得られます。

$ echo -n tenant/me:secret | base64

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