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

概要

このセクションでは、RESTインターフェースを使用したマイクロサービスの開発における特定の側面を説明します。

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

RESTは、HTTP(S)およびTCPに基づいた非常にシンプルで安全なプロトコルです。現在、非常にシンプルなデバイスから大規模なITシステムまで、すべてのネットワークプログラミング環境でサポートされているインターネットの事実上の標準となっています。RESTを紹介する多くの書籍の中で、RESTful Web Servicesがあります。

この API の説明では、Things Cloud の REST インターフェースを使用して、Things Cloud プラットフォーム上でマイクロサービス アプリケーションを開発する方法を学びます。

この説明は、各インターフェースを詳細に説明した Things Cloud OpenAPI仕様 と密接に関連しています。Things Cloud OpenAPI仕様 の関連セクションは特に以下のとおりです。

Java を使用してアプリケーションを開発する場合は、Microservice SDK for Java をチェックして、Things Cloud の機能にさらに便利にアクセスしてください。

RESTを使用したデバイスの統合に関する詳しい情報は、RESTを参照してください。

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>を、テナント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"
},
...

出力をより読みやすい形式にするには、python -mjson.toolを試してみてください。

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

ここから、返された様々なオブジェクトへ移動できます。例えば、managedObjects エンドポイントにアクセスして、インベントリ内の項目を取得できます。

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

実際に返されるのは、インベントリ内のアイテムのサブセット、いわゆる「ページ」だけであることがわかります。ページ処理の詳細については、Things Cloud OpenAPI仕様 の REST の使用法 > クエリ結果のページング を参照してください。

Postmanの使用

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

例のRESTクライアント

Things Cloudは、数多くのオンラインAPI例を提供しています。それらを利用する場合は、Postmanをダウンロードしてインストールしてください。Postmanを起動後、アカウントを作成するか、Take me straight to the appをクリックします。

API例をダウンロードし、Postmanにコレクションとしてインポートします。

次に、Postmanの左上にあるCollectionsタブをクリックします。_Things Cloud API_というフォルダが表示されるはずです。そのフォルダとサブフォルダ_アラーム_を開き、次にGet collection of alarmsをクリックします。これにより、Things Cloudからアラームを取得する例が表示されます。

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

  • 右上の歯車をクリックし、Manage Environmentsを選択し、次にAddをクリックします。
  • 環境の名前を入力します（たとえば、テナントID）。次に、プレースホルダーの値を追加します。
  • _url_キーを、値を_https://<TENANT_NAME>.je1.thingscloud.ntt.com_で設定します。Submitをクリックします。
  • RESTリクエストのためのAuthorizationヘッダーの値として、_auth_キーを設定します。
  • Addをクリックし、ダイアログを閉じます。次に、最初は「環境なし」と表示されている右上のドロップダウンボックスから新しく作成した環境を選択します。
Postman環境設定

たとえば、テナントIDが「t07007007」で、ユーザー名が「winter」、パスワードが「jh0nS0nw」であるとします。authキーの正しい値を判断する簡単な方法は、次のように Base64 コマンドを使用することです。

$ echo -n t07007007/winter:jh0nS0nw | base64

結果のテキストは「dDA3MDA3MDA3L3dpbnRlcjpqaDBuUzBudw==」であり、authキーの値としてBasic dDA3MDA3MDA3L3dpbnRlcjpqaDBuUzBudw==を使用する必要があります。この結果は、オンラインのBase64エンコード/デコードツールを使用しても同じ結果が得られます。

さあ、API の探索を始めましょう!

マイクロサービスの開発

このセクションでは、マイクロサービスを開発するために必要な基本的なRESTエンドポイントを紹介します。また、Things Cloud REST APIがマイクロサービスアプリケーションを開発するためにどのように利用できるかについての基本的なユースケースも学びます。

アプリケーションの作成

マイクロサービスに取り組むには、事前にプラットフォーム上でアプリケーションのインスタンスを作成する必要があります。これを行うには、以下のエンドポイントを使用します。

POST /application/applications
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: application/vnd.com.nsn.cumulocity.application+json
{
  "key": "<APPLICATION_NAME>-key",
  "name": "<APPLICATION_NAME>",
  "type": "MICROSERVICE",
  "requiredRoles": [ "ROLE_INVENTORY_READ" ],
  "roles": [ "ROLE_CUSTOM_MICROSERVICE" ]
}

成功レスポンスは、201ステータスと<HOST>/application/applications/<APPLICATION_ID>に似たロケーションヘッダで構成されます。

上記のリクエストボディのプロパティkey、name、およびtypeは明白であり、ロールについては次の通りです。

  • requiredRoles - マイクロサービスユーザーがThings Cloudからデータを取得するために必要なThings Cloudの権限のリストです。例えば、マイクロサービスが管理オブジェクトを作成する場合、必要なロールの一つはROLE_INVENTORY_ADMINである必要があります。
  • roles - マイクロサービスの権限のリストです。マイクロサービスが独自のREST APIを公開する場合、独自の権限のセットで保護することができ、例えばSMSマイクロサービスはSMSメッセージを送信するためにSMS_ADMIN権限を要求します。これらの権限は、マイクロサービスのサブスクリプション後にテナントで利用可能になります。その後、管理者ユーザーはSMSメッセージをThings Cloudプラットフォーム経由で送信したい別のユーザーにそのような権限を付与することができます。

既存のアプリケーションのアプリケーションIDは、アプリケーションの名前を使ってGETリクエストを行うことによって取得できます。

GET /application/applicationsByName/<APPLICATION_NAME>
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.application+json

成功レスポンスは次のようになります。

{
    "applications": [
        {
            "activeVersionId": "329",
            "availability": "MARKET",
            "id": "174",
            "key": "<APPLICATION_NAME>-microservice-key",
            "manifest": {
                "imports": [],
                "noAppSwitcher": true
            },
            "name": "<APPLICATION_NAME>",
            "owner": {
                "self": "<HOST>/tenant/tenants/<TENANT>",
                "tenant": {
                    "id": "<TENANT>"
                }
            },
            "requiredRoles": [],
            "roles": [],
            "self": "<HOST>/application/applications/174",
            "type": "MICROSERVICE"
        }
    ],
    "next": "<HOST>/application/applications?pageSize=5&currentPage=2",
    "statistics": {
        "currentPage": 1,
        "pageSize": 5
    },
    "self": "<HOST>/application/applications?pageSize=5&currentPage=1"
}

アプリケーションは、その後PUTリクエストを使用して更新できます。

PUT /application/applications/<APPLICATION_ID>
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: application/vnd.com.nsn.cumulocity.application+json
{
    "key": "<APPLICATION_NAME>-key",
    "name": "<APPLICATION_NAME>",
    "type": "MICROSERVICE",
    "requiredRoles": [ "ROLE_INVENTORY_READ" ],
    "roles": [ "ROLE_CUSTOM_MICSROSERVICE" ]
}

アプリケーションの展開

マイクロサービスアプリケーションは、バイナリZIPファイルをアップロードすることによって、Things Cloudプラットフォームのユーザーに利用可能になります。

POST /application/applications/<APPLICATION_ID>/binaries
Host: ...
Authorization: Basic ...
Content-Type: multipart/form-data

ZIPファイルには以下が含まれていなければなりません。

  • cumulocity.json - デプロイメントを説明するアプリケーションマニフェストファイル
  • image.tar - 実行可能なDockerイメージ

マイクロサービス認証情報の取得

次のセクションは、Things Cloudにおけるマイクロサービスのユーザー管理に関する一般的な側面のまとめです。

マイクロサービス関連のエンドポイントは、サービスプロバイダが使用できるマイクロサービスブートストラップユーザーを必要とします。

GET /application/applications/<APPLICATION_ID>/bootstrapUser
Host: ...
Authorization: Basic ...

レスポンス：

HTTP/1.1 200 Ok
Content-Type: application/vnd.com.nsn.cumulocity.user+json
{
    "tenant": "...",
    "name": "...",
    "password": "..."
}

これらの認証情報は以下のエンドポイントへのアクセスを許可します。

GET /tenant/currentTenant
GET /user/currentUser
GET /application/currentApplication
GET /application/currentApplication/subscription
PUT /application/currentApplication

例えば、現在のアプリケーションを取得するには次のようにします。

GET /application/currentApplication
Authorization: Basic ...
Content-Type: application/json

レスポンス：

{
    "activeVersionId": "329",
    "availability": "MARKET",
    "id": "...",
    "key": "...",
    "manifest": {
        "imports": [],
        "noAppSwitcher": true
    },
    "name": "hello-world",
    "owner": {
        "self": "...",
        "tenant": {
            "id": "..."
        }
    },
    "requiredRoles": [],
    "roles": [],
    "self": "...",
    "type": "MICROSERVICE"
}

サブスクリプション

この範囲でのサブスクリプションは、テナントがマイクロサービスアプリケーションにサブスクライブすることを意味します。サブスクリプションはデプロイメント後の重要なステップです。 マイクロサービスアプリケーションがデプロイされると、他のテナントがサブスクリプションできるようになります。マイクロサービスへのサブスクリプションは他のアプリケーションへのサブスクリプションと同様で、管理アプリケーションで行うことができます。また、テナントはPOSTリクエストを使用してサブスクライブすることもできます。

POST /tenant/tenants/<TENANT>/applications
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: application/vnd.com.nsn.cumulocity.applicationreference+json
Accept: application/vnd.com.nsn.cumulocity.tenant+json
{
    "application": {
        "id": "<APPLICATION_ID>"
    }
}

成功レスポンスは次のようになります。

HTTP/1.1 201 Created
Content-Type: application/vnd.com.nsn.cumulocity.tenant+json
Content-Length: ...
{
    "application": {
        "id": "<APPLICATION_ID>",
        "key": "...",
        "name": "...",
        "owner": {
            "self": ".../tenant/tenants/<TENANT>",
            "tenant": {
                "id": "<TENANT>"
            }
        },
        "self": "...",
        "type": "MICROSERVICE"
    },
    "self": "..."
}

サブスクリプションは、認可されたマイクロサービスブートストラップユーザーを介してマイクロサービスユーザーに提供されます。

GET /application/currentApplication/subscriptions
Host: ...
Authorization: Basic ...

レスポンス：

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.applicationusercollection+json
{
    "users": [{
        "tenant": "...",
        "name": "...",
        "password": "..."
    }],
    "self": ".../applications/application/285/users"
}

このレスポンスには、各テナント専用のサービスユーザー認証情報が含まれています。サービスユーザーは、マイクロサービスが登録時に要求した権限（「ロール」）を持つテナント内のユーザーアカウントです。

設定

マイクロサービスの設定は、認可されたブートストラップまたはサービスユーザーを介してマイクロサービスユーザーに提供されます。 ブートストラップユーザーを使用する場合、すべての設定は常にマイクロサービスのオーナーのためにロードされます。 設定は、Things Cloud内でテナントオプションとして保存されます。カテゴリはデフォルトでcontextPath（または、コンテキストパスが定義されていない場合はapplicationName）です。

リクエスト：

GET /application/currentApplication/settings
Host: ...
Authorization: Basic ...

レスポンス：

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.option+json;charset=UTF-8;ver=0.9
{
   "email.protocol": "smtps",
   "password.enforce.strength": "true",
   "another.key.1": "$value15"
}

基本ユースケース

アセットの登録

アセットは、ビジネスおよびアプリケーションが焦点を当てるオブジェクトです。例えば、ビル管理やホームオートメーションに関するビジネスの場合、アセットは建物や部屋である可能性があります。また、機械サービスに関するビジネスの場合は、ルートや機械である可能性もあります。

アセットはデバイスと共にインベントリに保存されますが、デバイスとは独立した独自の構造を持つことが多いです。アセットは、管理オブジェクトのコレクションにPOSTすることによって作成します。例えば、インベントリに新しい部屋を作成するには、次のようにします。

POST /inventory/managedObjects
Content-Type: application/vnd.com.nsn.cumulocity.managedobject+json
Accept: application/vnd.com.nsn.cumulocity.managedobject+json
Authorization: Basic ...
{
    "name": "Building 043",
    "type": "c8y_Building"
}

レスポンス：

HTTP/1.1 201 Created
Content-Type: application/vnd.com.nsn.cumulocity.managedobject+json;charset=UTF-8;ver=0.9
...
{
    "owner": "admin",
    "id": "2549800",
    "self": "https://.../inventory/managedObjects/2549800",
    "type": "c8y_Building",
    "lastUpdated": "2018-09-05T16:38:31.250+02:00",
    "name": "Building 043",
    "assetParents": {
        "references": [],
        "self": "https://.../inventory/managedObjects/2549800/assetParents"
    },
    "childAssets": {
        "references": [],
        "self": "https://.../inventory/managedObjects/2549800/childAssets"
    },
    "childDevices": {
        "references": [],
        "self": "https://.../inventory/managedObjects/2549800/childDevices"
    },
    "deviceParents": {
        "references": [],
        "self": "https://.../inventory/managedObjects/2549800/deviceParents"
    }
}

デバイスが正常に作成された場合、ステータスコード201が返されます。元のリクエストが上記の例と同様に「Accept」ヘッダを含んでいる場合、作成されたオブジェクトの完全な情報がIDとオブジェクトを参照するためのURLと共に返されます。返されるオブジェクトには、子デバイスと子アセットのコレクションへの参照も含まれ、デバイスに子を追加するために使用できます。

例えば、部屋を作成したと仮定し、その部屋の「self」プロパティが「https://…/inventory/managedObjects/2549700」であるとします。部屋を建物にリンクするには、建物の子アセットコレクションにPOSTします（上記の「childAssets」の「self」プロパティを参照）。

POST /inventory/managedObjects/2549800/childAssets HTTP/1.1
Content-Type: application/vnd.com.nsn.cumulocity.managedobjectreference+json
{
    "managedObject" : {
        "self" : "https://.../inventory/managedObjects/2549700"
    }
}

再度建物をクエリすると、部屋が建物の子として登録されていることが確認できます。

GET /inventory/managedObjects/2549800

レスポンス：

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.managedobject+json; charset=UTF-8; ver=0.9
...
{
    "owner": "admin",
    "id": "2549800",
    "self": "https://.../inventory/managedObjects/2549800",
    ...
    "childAssets": {
        "references": [
            {
                "managedObject": {
                    "id": "2549700",
                    "name": "Room 042",
                    "self": "https://.../inventory/managedObjects/2549700"
                },
                "self": "https://.../inventory/managedObjects/2549800/childAssets/2549700"
            }
        ],
        "self": "https://.../inventory/managedObjects/2549800/childAssets"
    }
}

デバイスとアセットのリンク

アセットを他の子アセットにリンクするのと同様に、アセットをそのアセットを監視して制御するデバイスにリンクすることもできます。例えば、部屋に設置された光センサーがあり、その光センサーのURLが「https://…/inventory/managedObjects/2480500」であると仮定します。次のように部屋のchildDevicesにPOSTします。

POST /inventory/managedObjects/2549700/childDevices
Content-Type: application/vnd.com.nsn.cumulocity.managedobjectreference+json
{
    "managedObject" : {
        "self" : "https://.../inventory/managedObjects/2480500"
    }
}
備考
複数の子アセットまたは複数の子デバイスを同じ親に対して1回のリクエストでリンクできます。詳細については、Things Cloud OpenAPI仕様内のインベントリAPIのインベントリ子操作を参照してください。

アセットと外部システムとの同期

しばしば、Things Cloudは企業のアセットを扱う唯一のITシステムではありません。外部ITシステムに保存されたアセットを同期するための技術的手順は、デバイスの登録に使用される手順と全く同じです。

  • Identity APIを使用して、外部ITシステムのアセットIDをThings CloudのアセットIDにリンクさせます。
  • Inventory APIを使用して、外部システムのデータに基づいてThings Cloud のインベントリにアセットを作成または更新します。

特定の機能のクエリ

アプリケーションを特定のデバイスタイプの詳細から切り離すために、アプリケーションはフラグメントを使用してインベントリをクエリできます（詳細はThings Cloudのドメインモデルのフラグメントのセクションを参照）。例えば、位置情報を持つすべての管理オブジェクトを見つけるには、次のようにします。

GET /inventory/managedObjects?fragmentType=c8y_Position&withTotalPages=true

レスポンス：

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.managedobjectcollection+json; charset=UTF-8; ver=0.9
...
{
    "managedObjects": [{
        "id": "2480700",
        "lastUpdated": "2013-08-30T10:15:44.218+02:00",
        "name": "RaspPi BCM2708 0000000017b769d5 Gps eM9",
        "owner": "admin",
        "self": "https://.../inventory/managedObjects/2480700",
        "type": "c8y_TinkerForge_Gps",
        "c8y_Position": {
            "alt": 102.36,
            "lng": 6.769717,
            "lat": 51.267259
        },
        ...
    },
    ...
    ]
    "next": "https://.../inventory/managedObjects?withTotalPages=true&fragmentType=c8y_Position&pageSize=5&currentPage=2",
    "statistics": {
        "currentPage": 1,
        "pageSize": 5,
        "totalPages": 4
    },
    "self": "https://.../inventory/managedObjects?withTotalPages=true&fragmentType=c8y_Position&pageSize=5&currentPage=1"
}

このようにして、例えばc8y_Positionプロパティを使用して、オブジェクトを地図上で位置付けることができます。標準フラグメントはフラグメントライブラリで定義されています。

/platformリソースをクエリすると、データをクエリするさらなる可能性が示されます（詳細はRESTも参照してください）。

なお、クエリが必ずしもすべてのクエリ結果を一度に返すわけではなく、結果のページのみを返すことに注意してください。ページングの詳細については、Things Cloud OpenAPI仕様内のREST実装 > REST使用 > クエリ結果のページングを参照してください。オプショナルパラメータwithTotalPagesを指定すると、クエリは若干パフォーマンスが低下しますが、全ページ統計を含むことができます。

センサーデータのクエリ

インベントリと同様に、特定のセンサーの読み取りをクエリすることもできます。例えば、過去1か月の光の測定値を（このテキストの作成時点から）次のようにクエリできます。

GET /measurement/measurements?dateFrom=2019-04-01&dateTo=2019-05-31&fragmentType=c8y_LightMeasurement

レスポンス：

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.measurementcollection+json; charset=UTF-8; ver=0.9
...
{
    "measurements": [{
        "id": "2480900",
        "self": "https://.../measurement/measurements/2480900",
        "source": {
            "id": "2480500",
            "self": "https://.../inventory/managedObjects/2480500"
        },
        "time": "2013-08-29T21:19:52.321+02:00",
        "type": "c8y_LightMeasurement",
        "c8y_LightMeasurement": {
            "e": {
                "unit": "lux",
                "value": 169.2
            }
        }
    },
    ...
    ]
    ...
}

オペレーションをデバイスへ送信

デバイスで操作をトリガーするには、操作をデバイス制御APIにPOSTします。次の例は、ID「2480300」のデバイス（「デバイス統合」内のRaspberry Pi）を再起動します。

POST /devicecontrol/operations
Content-Type: application/vnd.com.nsn.cumulocity.operation+json;
Accept: application/vnd.com.nsn.cumulocity.operation+json;
{
    "deviceId": "2480300",
    "c8y_Restart":{}
}

レスポンス：

HTTP/1.1 201 Created
Content-Type: application/vnd.com.nsn.cumulocity.operation+json; charset=UTF-8; ver=0.9
...
{
    ...
    "deviceId": "2480300",
    "id": "2550200",
    "self": "https://.../devicecontrol/operations/2550200",
    "status": "PENDING",
    "c8y_Restart": {}
}

POSTコマンドは、該当のデバイスに対するオペレーションを作成した後、その作成結果を即座に返します。オペレーションの作成と実行は非同期です。リクエスト例でオプションの「Accept」ヘッダーを追加したので、レスポンスにおいてはselfプロパティにおけるURLを含む、すべての発行済オペレーションを取得することになります。そのURLに対してGETを使用すると、以下の通り、現在のオペレーション実行状態をチェックすることができます。

GET /devicecontrol/operations/2550200 HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.operation+json; charset=UTF-8; ver=0.9
{
    "status": "PENDING",
    ...
}

ここでの「PENDING」ステータスとは、デバイスがまだオペレーションを受け取っていないことを意味します。「EXECUTING」は、デバイスがオペレーションを実行中であることを意味します。最後に、「SUCCESSFUL」または「FAILED」は、オペレーションが完了したことを示します。

イベントの応答を受信する

Things Cloudデータストアをクエリするだけでなく、リアルタイムでイベントを処理して受信することもできます。例えば、リアルタイムの位置情報更新を地図上に表示したいと仮定します。

位置情報更新を送信するデバイスがある場合、ユーザーインターフェースにそれらがすぐに表示されるはずです。それらを独自のRESTクライアントで受信するために、通知APIを使用してサブスクライブできます。このAPIは、HTTPSロングポーリングを使用したBayeuxプロトコルに基づいています。適用される制限については、Things Cloud OpenAPI仕様内のリアルタイム通知で説明されています。まず、ハンドシェイクが必要です。ハンドシェイクは、クライアントが通知のためにサポートするプロトコルをThings Cloudに伝え、クライアントIDをクライアントに割り当てます。

POST /notification/realtime
Content-Type: application/json
...
[ {
    "id": "1",
    "supportedConnectionTypes": ["long-polling"],
    "channel": "/meta/handshake",
    "version": "1.0"
} ]

HTTP/1.1 200 OK
...
[ {
    "id": "1",
    "supportedConnectionTypes": ["long-polling"],
    "channel": "/meta/handshake",
    "version": "1.0",
    "clientId": "71fjkmy0495rxrkfcmp0mhcev1",
    "minimumVersion": "1.0",
    "successful": true
}]

ハンドシェイクの後、クライアントは特定のデバイスチャンネルまたはすべてのデバイスチャンネル（*）にサブスクライブする必要があります。これは、チャンネル名を使用してPOSTリクエストで行います。
例えば、内部ID「24800」のデバイスからのイベントに関する通知を受信したい場合、サブスクリプションチャンネルは「/events/24800」です。

POST /notification/realtime
Content-Type: application/json
...
[ {
    "id": "2",
    "channel": "/meta/subscribe",
    "subscription": "/events/24800",
    "clientId": "71fjkmy0495rxrkfcmp0mhcev1"
}]

HTTP/1.1 200 OK
...
[ {
    "id":"2",
    "channel": "/meta/subscribe",
    "subscription": "/events/24800",
    "successful": true,
} ]

最後に、クライアントは接続状態のまま、イベントが送られてくるのを待ちます。

POST /notification/realtime HTTP/1.1
Content-Type: application/json
...
[ {
    "id": "3",
    "connectionType": "long-polling",
    "channel": "/meta/connect",
    "clientId": "71fjkmy0495rxrkfcmp0mhcev1"
} ]

このリクエストは、操作が実行されるまでハングします。以下は、位置情報の更新が1回だけ行われたレスポンスの例です。

HTTP/1.1 200 OK
...
[
    {
        "id": "3",
        "data": {
            "creationTime": "...",
            "id": "2481400",
            "self": "https://.../event/events/2481400",
            "source": {
                "id": "24800",
                "name": "RaspPi BCM2708 0000000017b769d5 Gps eM9",
                "self": "https://.../inventory/managedObjects/24800"
            },
            "text": "Location updated",
            "time": "...",
            "type": "c8y_LocationUpdate",
            "c8y_Position": {
                "alt": 58.34,
                "lng": 6.769717,
                "lat": 51.267259
            },
            "channel": "/events/24800"
        },
        "successful": true,
        "channel": "/meta/connect"
    }
]
備考
すべてのデバイスのチャネル (*) は非推奨であるため、使用しないでください。 このチャネルのサブスクリプションはクライアント側とサーバー側の両方でパフォーマンスの問題を引き起こす可能性があり、このオプションはThings Cloudの将来のバージョンで削除される可能性があります。