はじめに
この記事では、ThingWorx へ REST API を用いてアクセスし、Thing の持つプロパティの値を読み書きしたり、サービスを呼び出したりする方法を説明します。
対象読者
この記事は、ThingWorx を用いた開発の基礎知識を有していることを前提として書かれています。また、REST API の基本的な知識も必要です。
対象バージョン
この記事は、ThingWorx 8.x および 9.x を対象に書かれています。
REST API 基礎
対応しているメソッド
Thing の持つプロパティの値を読み出すには、GET メソッドを使います。プロパティに値をセットするには、PUT を使用します。ただし、リモート・バインドやローカル・バインドされているプロパティに値を書き込むことはできません。
必要なリクエスト・ヘッダ
RET API 発行時、下記のヘッダを積んでおく必要があります。
Content-type
Content-type ヘッダには application/json をセットします。
Accept
Accept ヘッダには受け取りたいデータのメディアタイプを指定します。8.x 以降、下記が使用可能です。
- text/xml
- application/json
また、9.x 以降は下記も可能です。
- text/html
- text/csv
認証
ThingWorx へ REST でアクセスする際には、Application Key と呼ばれるセキュリティ・トークンを使うと便利です。通常の BASIC 認証も対応していますし、SSO が構成されている場合にはその他の認証方法も選択可能ですが、パスワードをプログラムでどのように扱うかなどの問題を避けるために Application key を使うことをお勧めします。
Application Key を使うには、リクエストヘッダに appKey を追加します。appKey の値は、ThingWorx コンポーザーで作成した Application Key の値です。
全体として、下記のようなリクエストヘッダになっていれば十分です。
認証関連ヘッダ
その他ヘッダ
REST API エンドポイント
ThingWorx の REST API については、完全なガイドがヘルプセンターにあります。
ThingWorx 9 のヘルプセンターはこちらからアクセスできます。
Things
よく使うのは、やはり Thing の持つプロパティの値へのアクセスでしょう。
Thingworx/Things
すべての Thing の一覧が得られます。注意すべきことは、指定した Application Key が紐付けられているユーザーの権限において、閲覧可能な Thing に限られる、ということです。Application Key の権限では見えない Thing は応答に含まれません。
Thingworx/Things/{Thing名}/Properties/{プロパティ名}
個別の Thing の、個別のプロパティの値を読み書きします。読み出す場合は GET メソッドを、書き込む場合は PUT メソッドを使用します。PUT メソッドでは、プロパティ名とその値を JSON 形式で、リクエストボディに記載します。
下記はブラウザから ThingWorx/Things/{Thing名}/Properties へアクセスして、Thing の持つプロパティを一覧させたところです。
つづいて、プロパティ PumpBPower の値を読み取るべく、ThingWorx/Things/{Thing名}/Properties/PumpBPower を GET してみます。ブラウザに次のように表示されます。
Postman での実行では、次のようにレスポンスを確認できます。
Thingworx/Things/{Thing名}/Services/{サービス名}
Thing名に指定した Thing のサービスを起動します。サービスに入力パラメータがある場合には、POST のボディに JSON 形式で記述します。
下記は、SayHello という名前のカスタムサービスを Postman で呼び出しているところです。SayHello サービスは "Hello, things!" という文字列を返すだけの単純なサービスです。
その他
上記に簡単に説明した Thing のプロパティ値の読み書きやサービス起動の他にも、ログを読み出したりユーザーやグループの情報をリストしたりなど、REST API を使うと ThingWorx を外部から便利に使えます。詳細の情報は上記に紹介した ThingWorx のヘルプセンターを参照してください。