PD Exchange / QuickStart Guide

Overview

このクイックスタートガイドでは、Docker Engineがセットアップ済のサーバに対してPD Exchangeのインストールから初期設定、デバイスからのメッセージ送信とアプリケーションでのメッセージ取得と、PD Exchangeの基本動作を確認することができます

PD Exchangeの操作はすべてコマンドラインおよびREST APIによって行います

本ガイドにおけるREST APIの操作はcurlを利用しますので、予め準備してください

学習には1〜2時間程度を必要とします

NOTE: PD Exchangeのレスポンス形式であるJSONを整形するためにjqを利用したため、実際のレスポンスとフォーマットが異なっている場合がありますがご了承ください

  1. 当社のDocker Trusted RegistryからPD ExchangeのDocker Containerをダウンロード
  2. PD Exchangeの開始
  3. PD Exchangeの初期設定
  4. ユーザアカウントの作成
  5. デバイスグループの作成
  6. アプリケーションの登録
  7. チャネルの開設
  8. デバイスからのメッセージ送信
  1. アプリケーションでのメッセージ取得
  1. アプリケーションからのコマンド送信
  1. デバイスでのコマンド受信
  1. PD Exchangeの終了

本ガイドでは、下記については説明しません。該当するドキュメントを参照するようにしてください

  • OSおよびDocker Engineやネットワークのセットアップ
  • curlコマンドのオプション等の使用方法
  • PD Exchangeライセンスの取得
  • PD Exchangeの継続的な運用
  • デバイス/アプリケーションの開発

本ガイドで使われる表記

以下は本ガイドで使われる文字の一覧です

固定幅 (constant width)

コード例、ファイルの内容、コマンド、コマンドからの出力を示すために使われます

固定幅太文字 (constant width bold)

例や表の中で使われ、そのとおりに入力しなければならないコマンドやその他のテキストを示します

固定幅斜体 (constant width italic)

例や表の中で使われ、ユーザが入力してその部分のテキストを置き換えなければならないことを示します

Basic flow

PD ExchangeのDocker Containerをダウンロード

docker login にて当社Docker Trusted Registryサーバへログインし、 docker pull にて実際のダウンロードを行います

YOUR_PDEX_DTR_URL, YOUR_PDEX_ID, YOUR_PDEX_PASSWD および YOUR_PDEX_EMAIL は、PD Exchangeライセンス証に記載されています。予め用意してください

$ docker login YOUR_PDEX_DTR_URL
Username:
YOUR_PDEX_ID
Password:
YOUR_PDEX_PASSWD (入力は表示されません)
Email:
YOUR_PDEX_EMAIL
WARNING: login credentials saved in /home/user/.docker/

$ docker pull YOUR_PDEX_DTR_URL/pd-dist/pdex-allinone
latest: Pulling from dtr0.plathome.com/pd-dist/pdex-allinone
d3a1f33e8a5a: Already exists
c22013c84729: Already exists
...snip...
21db6763943e: Already exists
7676dee1410d: Already exists
Digest: sha256:d71518379002e20c23a825f152e96df7280a1040673591889d076a63ffe619dc
Status: Image is up to date
for dtr0.plathome.com/pd-dist/pdex-allinone:latest

※例 YOUR_PDEX_DTR_URL が dtr0.plathome.com である場合は、下記の通りになります

$ docker login dtr0.plathome.com

$ docker pull dtr0.plathome.com

PD Exchange Docker Containerを開始

docker run にてPD Exchangeを開始します

NOTE: 本ガイドではPD Exchange終了後に設定やデータ等がすべて消去されるため、継続的な運用には向いていません

$ docker run --rm --name pdex YOUR_PDEX_DTR_URL/pd-dist/pdex-allinone
WARN: Not found /wproc on this system
May be max concurrency is 100, due to
somaxconn=128
please re-run
"docker run -v /proc:/wproc"
2015-10-04 03:10:16,254 CRIT Supervisor running as root (no user in config file)
2015-10-04 03:10:16,255 WARN Included extra file
"/etc/supervisord/conf.d/app.conf" during parsing
2015-10-04 03:10:16,276 INFO RPC interface
'supervisor' initialized
2015-10-04 03:10:16,276 CRIT Server
'inet_http_server' running without any HTTP authentication checking
2015-10-04 03:10:16,276 INFO supervisord started with pid 1
2015-10-04 03:10:17,279 INFO spawned:
'pgsql' with pid 8
2015-10-04 03:10:17,283 INFO spawned:
'api' with pid 9
2015-10-04 03:10:17,286 INFO spawned:
'gc' with pid 10
2015-10-04 03:10:17,289 INFO spawned:
'nginx' with pid 11
2015-10-04 03:10:18,417 INFO success: pgsql entered RUNNING state, process has stayed up
for > than 1 seconds (startsecs)
2015-10-04 03:10:18,417 INFO success: api entered RUNNING state, process has stayed up
for > than 1 seconds (startsecs)
...snip..
2015-10-04 03:10:31,681 INFO spawned:
'gc' with pid 121
2015-10-04 03:10:32,730 INFO success: gc entered RUNNING state, process has stayed up
for > than 1 seconds (startsecs)
2015-10-04 03:10:32,849 INFO exited: gc (
exit status 1; not expected)
2015-10-04 03:10:33,851 INFO spawned:
'gc' with pid 129
2015-10-04 03:10:34,929 INFO success: gc entered RUNNING state, process has stayed up
for > than 1 seconds (startsecs)

PD Exchange Docker ContainerのIPアドレスを確認する

PD Exchange APIにアクセスするためにPD ExchangeのIPアドレスが必要となります

docker run を行ったターミナルとは別のターミナルから docker inspect にて確認します

$ docker inspect --format '{{ .NetworkSettings.IPAddress }}' pdex
172.17.0.3

※以降、本ガイドではPD ExchangeのIPアドレスを $PDEX とします

PD Exchangeの初期設定

PD Exchange 管理者アカウント(以下、adminアカウント)を発行します

$ curl -w "\n" -X POST http://$PDEX/api/v1/setup

{"admin":{"username":"pdexadm","access_token":"e9e3412efea4"}}

※以降、本ガイドではadminアカウントのaccess_tokenを $ADMIN_ACCESS_TOKEN とします

/api/v1/setup は1回呼び出されると “セットアップ済” として記録され、初期化しない限り二度と呼び出しができません

そのため、ここで表示されたadminアカウントのaccess_tokenは紛失しないように保管してください

NOTE: 本ガイドではPD Exchange終了後に設定やデータ等がすべて消去されるため、再度PD Exchangeを開始しても常に初期された状態となります

ユーザアカウントの作成

一般ユーザアカウントをPD Exchange内に作成します。普段はこのアカウントにて操作を行います

例として、User IDを pd_user1 、パスワードを AnyPassword とします

$ curl -w "\n" -H "AUTHORIZATION: Bearer $ADMIN_ACCESS_TOKEN" \

-d "username=pd_user1" -d "password=AnyPassword" \

-X POST http://$PDEX/api/v1/users

{"username":"pd_user1","access_token":"ef9d778b3143"}

※以降、本ガイドでは一般ユーザアカウントのaccess_tokenを $USER_ACCESS_TOKEN とします

いま作成したユーザの自分自身の情報が確認できます

$ curl -w "\n" -H "AUTHORIZATION: Bearer $USER_ACCESS_TOKEN" \

-X GET http://$PDEX/api/v1/me

{

  "devicegroups": [],

  "apps": [],

  "access_token": "ef9d778b3143",

  "username": "pd_user1"

}

アプリケーションの登録とapp_tokenの確認

pd_user1 が保有するアプリケーションをPD Exchange内に登録します

例として、アプリケーション名を pd_app1 とします

$ curl -w "\n" -H "AUTHORIZATION: Bearer $USER_ACCESS_TOKEN" \

-d "app_name_suffix=pd_app1" -X POST http://$PDEX/api/v1/apps

{"app_id":"1b28a60b98094bfdb34e8344cf50aa8c"}

※以降、本ガイドでは上記app_idを  $APP1_ID とします

GET /api/v1/apps/:app_id で、当該アプリケーションのapp_tokenを含めた詳細を確認できます

$ curl -w "\n" -H "AUTHORIZATION: Bearer $USER_ACCESS_TOKEN" \

-X GET http://$PDEX/api/v1/apps/$APP1_ID

{

  "has_channel_count": 0,

  "registered_at": "2015-09-21 07:30:41 +0000",

  "app_name": "pd_user1:pd_app1",

  "app_token": "13ed1acbaffc",

  "app_id": "1b28a60b98094bfdb34e8344cf50aa8c"

}

※以降、本ガイドでは上記app_tokenを  $APP1_TOKEN とします

NOTE: GET /api/v1/me でアプリケーション(一覧)が確認できます

$ curl -w "\n" -H "AUTHORIZATION: Bearer $USER_ACCESS_TOKEN" -X GET http://$PDEX/api/v1/me

{

  "devicegroups": [],

  "apps": [

    {

      "app_name": "pd_user1:pd_app1",

      "app_id": "1b28a60b98094bfdb34e8344cf50aa8c"

    }

  ],

  "access_token": "ef9d778b3143",

  "username": "pd_user1"

}

デバイスグループの作成とsecret_keyの確認

pd_user1 が管理するデバイスグループをPD Exchange内に作成します

$ curl -w "\n" -H "AUTHORIZATION: Bearer $USER_ACCESS_TOKEN" \

-X POST http://$PDEX/api/v1/devicegroups

{"deid_prefix":"01.312949"}

※以降、本ガイドでは上記devicegroup_idを  $DG1_PREFIX とします

GET /api/v1/devicegroups/:deid_prefix で、当該デバイスグループのsecret_keyを含めた詳細を確認できます

$ curl -w "\n" -H "AUTHORIZATION: Bearer $USER_ACCESS_TOKEN" \

-X GET http://$PDEX/api/v1/devicegroups/$DG1_PREFIX

{

  "secret_key": "98e53f40aec1",

  "deid_prefix": "01.312949"

}

※以降、本ガイドでは上記secret_keyを  $DG1_SECRET_KEY とします

チャネルの開設

デバイスとアプリケーション間のメッセージとコマンドの交換を行うためのチャネルをPD Exchange内に開設します

チャネルの開設には “DeIDの決定” “secret_tokenの生成” “チャネルの開設” という3つの操作が必要となります

DeIDの決定

DeIDはドットを含めた9オクテットの “DeID Prefix” と 8オクテットの “DeID Node” をドット文字で結合した文字列です

例) 01.312949.a012b012

DeID Nodeは下記のような条件があります

  • 使用可能文字: 0~9a~f
  • 文字数: 8
  • デバイス側で割り当てる必要がある
    (PD Exchangeでは DeID Nodeの生成・発行や管理をする仕組みはありません)

今回は $DG1_PREFIX.00000001 を DeID として 以降 $DEID1 とします

secret_tokenの生成

DeIDとsecret_keyからsecret_tokenを生成します。APIを操作する際に必要となる文字列です

$ curl -w "\n" -d "key=$DG1_SECRET_KEY" -d "message=$DEID1" \

-X POST http://$PDEX/api/v1/utils/hmac

{"digest":"JJQuAPOCUtLpz4wvStlCGDfdMqmHLskxkafbRA=="}

※以降、本ガイドでは上記 digest と表示された値を  $DEID1_SECRET_TOKEN とします

NOTE: secret_tokenは、APIを使わずに一般的なプログラム言語でも生成可能です。詳細はFAQをご覧ください

チャネルの開設

secret_token、 DeID、 application_id の3つの値を使い、チャネルを開設します

今回の例は  pd_app1 と 01.312949.0000001 の間にチャネルを開く事になります

$ curl -w "\n" -H "Authorization: Bearer $DEID1_SECRET_TOKEN" \

-d "deid=$DEID1" -d "app_id=$APP1_ID" \

-X POST http://$PDEX/api/v1/channels

{

  "channel_id": "81a4459bb4b24c18b3fccb89760ace9d"

}

※以降、本ガイドでは上記 channel_id と表示された値を  $DEID1_APP1_CHANNEL1_ID とします

デバイスからアプリケーションへのメッセージ送信

$DEID1 からのメッセージ” として送信します。必要なのは DeID と secret_token です

送信されたメッセージは、その時点で開設済みのチャネルすべてに配信されます

例として “This is test message” という文字列を送信します

$ curl -w "\n" -H "Authorization: Bearer $DEID1_SECRET_TOKEN" \

-H "Content-Type: text/plain" -d "This is test message" \

-X POST http://$PDEX/api/v1/devices/$DEID1/message

{"transaction_id":"A650594771592552449"}

アプリケーションでのメッセージ取得

アプリケーションでメッセージを取得するためには、channel_idとapp_token、そしてmsgidが必要になります

チャネル内のメッセージ一覧の取得

msgidを得るために、まずチャネル内のメッセージ一覧を取得します

$ curl -w "\n" -X GET -H "Authorization: Bearer $APP1_TOKEN" \

http://$PDEX/api/v1/channels/$DEID1_APP1_CHANNEL1_ID/messages

{

  "count": 1,

  "messages": [

    {

      "msgid": "650594771600941058"

    }

  ]

}

※以降、本ガイドでは上記 msgid を $MSGID1 とします

NOTE: メッセージ送信時のレスポンス内の transaction_id は、あくまでも送信操作に対する受付番号のようなものであり、ここで表示される msgid とは関連性はありません

メッセージの取得

$ curl -w "\n" -X GET -H "Authorization: Bearer $APP1_TOKEN" \

http://$PDEX/api/v1/channels/$DEID1_APP1_CHANNEL1_ID/messages/$MSGID1

This is test message

アプリケーションからデバイスへのコマンド送信

アプリケーションからコマンドを送信するためには、 channel_id と app_token が必要になります

送信すると、チャネルに紐づいたデバイスへコマンドが送信されることになります

例として “To Device COMMAND” という文字列を送信します

$ curl -w "\n" -H "Authorization: Bearer $APP1_TOKEN" \

-H "Content-Type: text/plain" -d "To Device COMMAND" \

-X POST \

http://$PDEX/api/v1/channels/$DEID1_APP1_CHANNEL1_ID/command

{"transaction_id":"A650594771500533761"}

デバイスでのコマンド取得

デバイスでコマンドを取得するためには  DeID と secret_token が必要になります

チャネル内のコマンド一覧の取得

cmdidを得るために、まずチャネル内のコマンド一覧を取得します

$ curl -w "\n" -H "Authorization: Bearer $DEID1_SECRET_TOKEN" \

-X GET http://$PDEX/api/v1/channels/$DEID1/commands

{

  "count": 1,

  "commands": [

    {

      "cmdid": "650594771600654123"

    }

  ]

}

※以降、本ガイドでは上記 cmdid を  $CMDID1 とします

NOTE: メッセージ送信時のレスポンス内の transaction_id は、あくまでも送信操作に対する受付番号のようなものであり、ここで表示される cmdid とは関連性はありません

コマンドの取得

$ curl -w "\n" -H "Authorization: Bearer $DEID1_SECRET_TOKEN" \

-X GET http://$PDEX/api/v1/channels/$DEID1/commands/$CMDID1

To Device COMMAND

PD Exchangeの終了

docker run したターミナルで Ctrl+C、もしくは他のターミナルから docker stop pdex で終了します

本ガイドのNOTEで説明したとおり、設定やデータ保存は一切おこないません

Next Steps

PD Exchangeを本格的に運用するには Administrator Guideをご覧ください。また、Amazon Web Services上での運用においては、Administrator Guide in AWS(準備中)をご覧ください

PD Exchangeに対応したデバイス・アプリケーション開発を行うためには Developer Guide for device(準備中)、 Developer Guide for Application(準備中) をそれぞれご覧ください

APIリファレンスはPD Exchange API Referenceをご覧ください

用語集

Docker Engine

Docker Containerを動作するために必要な基盤ミドルウェア

Docker Container

アプリケーション本体の他、そのアプリケーションを動かすために必要なOSやライブラリ等まですべてをまとめたイメージファイル

Docker Trusted Registry

Docker Containerをネットワーク越しに配信するためのサーバ

DeID

PD Exchange特有の概念で、PD Exchange上において “デバイス” として識別する単位

デバイスグループに割り当てられるDeID Prefixと任意の番号の組み合わせで作られ、PD Exchange内でユニークである必要がある

通常は物理デバイスに対して1つ割り当てるが、割り当て方法に制限は無い

語源はDeviceID

デバイスグループ

PD Exchange特有の概念で、DeIDをひとまとめに管理する単位

デバイスグループ1つに対しPD Exchange内でユニークなDeID Prefixが自動的に1つ割り当てられる

一つのユーザアカウントで複数のデバイスグループを保有することができる

SecretToken

PD Exchange特有の概念で、DeIDを利用してメッセージの送受信を行うソフトウェアからPD Exchange APIにアクセスする際に必要なトークン文字列

デバイスグループ 1つに対し1つのSecretKeyが自動的に割り当てられる

アプリケーション

PD ExchangeのAPIを利用するソフトウェア。PD Appsと呼称する場合もある

アプリケーション1つに対しPD Exchange内でユニークなApplication IDが自動的に1つ割り当てられる

AppToken

PD Exchange特有の概念で、アプリケーションからPD Exchange APIにアクセスする際に必要なトークン文字列

アプリケーション1つに対し複数のAppTokenを割り当てる事ができ、個別に有効/無効化が可能

チャネル

PD Exchange特有の概念で、デバイスとアプリケーション間においてメッセージ交換を行う、専用の仮想回線

DeIDとApplication IDの組み合わせによってPD Exchange内でユニークなChannel IDが自動的に1つ割り当てられる

AccessKey

PD Exchange特有の概念で、PD Exchangeの管理系APIにアクセスする際に必要な文字列

ユーザアカウント1つに対し複数のAccessKeyを割り当てる事ができ、個別に有効/無効化が可能