WebSocket API仕様(情報配信者向け)

WebSocket APIについて

  • 情報配信クライアントからのリクエストに応じて、通知対象のクライアントに対してメッセージの転送を行います。

API仕様

  • リクエストメッセージ内の一部の情報を通知対象クライアントに対して転送します。
    • 通知対象クライアントは、datatype名に対して受信権限を持つクライアントを指します。
    • リクエストクライアントへの情報の転送は行いません。
  • リクエストメッセージに対して、レスポンスメッセージの送信は行いません。
    • 後述する認証要求メッセージに限り、レスポンスメッセージを送信します。
  • 一定期間内は過去リクエスト済みメッセージ(msgid)は、クライアントへの転送処理を行いません。

リクエスト(送信)メッセージ共通パラメータ

  • クライアントからWebSocket APIサーバに通知するリクエストメッセージの共通パラメータを以下に示します。

    セクション パラメータ 必須 タイプ 設定値 意味 備考
    version   必須 Hash 以下の2パラメータを設定されます。 メッセージのバージョン情報設定セクション  
      common_version 必須 String "1" commonセクションのパラメータバージョン 現在は"1"のみが利用されます。
      details_version 必須 String "1" detailsセクションのパラメータバージョン 現在は"1"のみが利用されます。
    common   必須 Hash 以下の4パラメータが設定されます。 メッセージの共通情報設定セクション 以下のパラメータはバージョン"1"
      datatype 必須 String 任意 メッセージのデータタイプ 利用申請時に利用者が定義します。
      msgid 必須 String 任意 メッセージ毎の一意な番号  
      sendid 必須 String 任意 メッセージの一意な番号  
      senddatetime 必須 String YYYY-MM-DD HH:mm:SS+HH:mm形式 メッセージの送信時刻  
    sender   必須 Hash 以下の3パラメータを設定する。 メッセージの送信者情報設定セクション  
      version 必須 String "1" senderセクションのパラメータバージョン 現在は1のみ対応
      userid 必須 String 任意 メッセージの送信者ユーザID  
      termid 必須 String 任意 メッセージの送信者端末ID  
    receiver   必須 Hash 以下の3パラメータを設定する。 メッセージの受信者情報設定セクション  
      version 必須 String "1" receiverセクションのパラメータバージョン 現在は1のみ対応
      userid 必須 String
    "*" （全useridへ配信）
    または
    任意（メッセージの受信先機器が利用しているuseridを設定）
    		 メッセージの受信者ユーザID 指定がない場合は、"*"として処理する。
      termid 必須 String
    "*" （全termidへ配信）
    または
    任意（メッセージの受信先機器が利用しているtermidを設定）
    		 メッセージの受信者端末ID 指定がない場合は、"*"として処理する。
    details   必須 Array データタイプ毎に定義されたパラメータが設定されます。 メッセージの詳細情報設定セクション パラメータは利用者が任意で定義します。
    option   任意 Hash 以下のパラメータを設定できます。 メッセージのオプション情報設定セクション  
      force 任意 String 0:無効、1:有効 メッセージの強制転送オプション  

レスポンス(受信)メッセージ共通パラメータ仕様

  • WebSocket APIからクライアントに通知されるレスポンスメッセージの共通パラメータを以下に示します。

    セクション パラメータ タイプ 設定値 意味 備考
    version   Hash 以下の2パラメータを設定されます。 メッセージのバージョン情報設定セクション  
      common_version String 任意 commonセクションのパラメータバージョン 現在は"1"のみが利用されます。
      details_version String 任意 detailsセクションのパラメータバージョン  
    common   Hash 以下の4パラメータが設定されます。 メッセージの共通情報設定セクション 以下のパラメータはバージョン"1"
      datatype String 任意 メッセージのデータタイプ 利用申請時に利用者が定義します。
      msgid String 任意 メッセージ毎の一意な番号  
      sendid String 任意 メッセージの配信元情報  
      senddatetime String YYYY-MM-DD HH:mm:SS+HH:mm形式 メッセージの送信時刻  
    details   任意 データタイプ毎に定義されたパラメータが設定されます。 メッセージの詳細情報設定セクション パラメータは利用者が任意で定義します。

  • リクエストメッセージの「version,common,details」セクションを抜き出した情報が通知されます。

  • リクエストメッセージの送信者にはレスポンスメッセージは通知されません。


認証

  • APIを利用するには、認証のためにユーザＩＤとパスワードを利用します。

  • ユーザＩＤとパスワードは利用申請時に発行されます。

  • 認証は以下の手順で行います。

    1. エンドポイントURLとwebsocket接続を確立します。
    2. 認証のリクエストメッセージを生成します。
    3. リクエストメッセージ(認証要求)を送信します。
    4. レスポンスメッセージ(認証応答)を受信します。
    • 認証エラーとなった場合、websocket接続が切断されます。
    • 一定時間以内に認証メッセージがサーバに通知されない場合、websocket接続が切断されます。

  • 具体的な認証手順は、 サンプルプログラム をご参照ください。

  • 認証要求メッセージパラメータ

    セクション パラメータ 必須 タイプ 設定値 意味 備考
    version   必須 Hash 以下の2パラメータを設定 メッセージのバージョン情報設定セクション  
      common_version 必須 String 1 commonセクションのパラメータバージョン 現在は1のみ対応
      details_version 必須 String 1 detailsセクションのパラメータバージョン 現在は1のみ対応
    common   必須 Hash 以下の4パラメータを設定 メッセージの共通情報設定セクション  
      datatype 必須 String authentication メッセージのタイプ  
      msgid 必須 String * メッセージ毎の一意な番号 認証では利用しない。
      sendid 必須 String * メッセージの配信元情報 認証では利用しない。
      senddatetime 必須 String * メッセージの送信時刻 認証では利用しない。
    sender   必須 Hash 以下の3パラメータを設定 メッセージの送信者情報設定セクション  
      version 必須 String 1 senderセクションのパラメータバージョン  
      userid 必須 String 任意 メッセージの送信者ユーザID 利用申請時に発行のユーザID
      termid 必須 String 任意 メッセージの送信者端末ID 利用者が定義する接続端末毎に一意な番号
    receiver   必須 Hash 以下の3パラメータを設定 メッセージの受信者情報設定セクション  
      version 必須 String 1 receiverセクションのパラメータバージョン  
      userid 必須 String * メッセージの受信者ユーザID 認証では利用しない。
      termid 必須 String * メッセージの受信者端末ID 認証では利用しない。
    details   必須 Hash 以下のパラメータを設定 メッセージの詳細情報設定セクション  
      password 必須 String 任意 認証ユーザのパスワード 利用申請時に発行のパスワード

  • 認証応答メッセージパラメータ

    セクション パラメータ タイプ 設定値 意味 備考
    version   Hash 以下の2パラメータを設定されます。 メッセージのバージョン情報設定セクション  
      common_version String "1" commonセクションのパラメータバージョン  
      details_version String "1" detailsセクションのパラメータバージョン  
    common   Hash 以下の4パラメータが設定されます。 メッセージの共通情報設定セクション 以下のパラメータはバージョン"1"
      datatype String authentication メッセージのデータタイプ  
      msgid String "" メッセージ毎の一意な番号 認証では利用しない。
      sendid String "" メッセージの配信元情報 認証では利用しない。
      senddatetime String "" メッセージの送信時刻 認証では利用しない。
    details   Hash 認証応答メッセージパラメータが設定されます。 認証応答メッセージの詳細情報設定セクション  
      resultcode String 200:認証成功、401:認証エラー 認証応答コード  
      message String   認証応答メッセージ  

API利用方法

  • 情報配信を行うまでの手順を以下に記載します。
    1. エンドポイントURLとwebsocket接続を確立します。
    2. 認証リクエストメッセージを送信します。
    3. 通知メッセージを生成します。
    4. 通知メッセージを送信します。
  • 利用に際しての、推奨事項を以下に記載します。
    • 常時websocketセッションを確立する場合、クライアント側から一定間隔でPingフレームを通知すること。(websocketセッション状態確認のため)
      • 一定時間内にPongフレーム応答がない場合、websocket接続断と判断し、websocket接続処理を再度行うこと。
    • websocket接続断検出時に、websocket接続処理を再度行うこと。

サンプルプログラム

  • ruby

    • push配信サーバへのwebsocket接続/認証および通知メッセージの送信処理

        1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
      #!/usr/bin/ruby
# -*- coding: utf-8 -*-
require "rubygems"
require "eventmachine"
require "faye/websocket"    # gem install faye-websocket
require "date"
require "json"

# 接続情報
WSS_SERVER = "wss://localhost:443"
USERID = "trialuser"
PASSWD = "trialpass"
TERMID = "0000000001"

# 認証メッセージ
AUTH_MESSAGE = {
  "version" => {
    "common_version"  =>  "1",
    "details_version" =>  "1"
  },
  "common" => {
    "datatype"     => "authentication",
    "msgid"        => "*",
    "sendid"       => "*",
    "senddatetime" => ""
  },
  "details" => {
    "password"     => PASSWD
  },
  "sender" => {
    "version"      => "1",
    "userid"       => USERID,
    "termid"       => TERMID
  },
  "receiver" => {
    "version"      => "1",
    "userid"       => "*",
    "termid"       => "*"
  }
}

# 通知メッセージ
SEND_MESSAGE = {
  "version" => {
    "common_version"  =>  "1",
    "details_version" =>  "1"
  },
  "common" => {
    "datatype"     => "trialdata",
    "msgid"        => "trialdata" + DateTime.now.strftime("%Y-%m-%d %H:%M:%S"),
    "sendid"       => "trialserver",
    "senddatetime" => DateTime.now.strftime("%Y-%m-%d %H:%M:%S%Z")
  },
  "sender" => {
    "version"      => "1",
    "userid"       => USERID,
    "termid"       => TERMID
  },
  "receiver" => {
    "version"      => "1",
    "userid"       => "*",
    "termid"       => "*"
  },
  "details" => {
    "trialdata1"   => "trial",
    "trialdata2"   => 10
  },
}

$conn = nil

EM.run do
  # websocket生成
  $conn = Faye::WebSocket::Client.new(WSS_SERVER)

  # websocket接続確立
  $conn.on :open do |e|
    puts "connection success."
    puts "send auth message."
    $conn.send(JSON::dump(AUTH_MESSAGE))
  end

  # websocket接続エラー
  $conn.on :error do |e|
    puts "error occured."
  end

  # websocket切断
  $conn.on :close do |e|
    puts "connection close."
  end

  # メッセージ受信
  $conn.on :message do |msg|
    now = Time.now.strftime("%Y-%m-%d %H:%M:%S")
    puts "#{now} message receive."
    result = JSON::parse(msg.data.to_s)
    puts result

    # 認証成功時メッセージ送信
    if result["common"]["datatype"] == "authentication" and result["details"]["resultcode"] == "200"
      puts "authorized success."
      puts "message send!!"
      $conn.send(JSON::dump(SEND_MESSAGE))
      exit
    else
      puts "authorized error."
      exit
    end
  end
end