Chat Webhooks

Photon CloudでWebhookを用いることで、チャットアプリケーションをより制御することができるようになります。チャンネル履歴を継続したり、メッセージをフィルタリングしたり、チャンネル作成をキャンセルしたり、特定のプレイヤーにチャットルームの登録を禁止したりすることができるようになります。

Photon Chat webhookは、イベントにより制御されるPhoton Cloudから特定のURLに送信されるHTTP POSTリクエストです。それぞれのPhoton Chat webhookは、それ自身のトリガーやデータ、目的地経路によって定義されます。

設定

基礎設定

ベースURL （必須）
フックをホストしているサービスのURLです。フォワードスラッシュ（バックスラッシュでないスラッシュ）で終わっていないものです。コールバックは、設定されたフックの関連するパスURLで受信されます。設定する値にクエリ文字列が含まれる場合は、こちらをお読みください。
カスタムHttpヘッダー
設定されたウェブサービスに対して行われたいかなるリクエストにおいても、公開鍵と秘密鍵または値のペアが含まれるJSONオブジェクトはHTTPヘッダーとして設定できません。詳細はこちら。

パス

それぞれのパスが、それぞれが自分のホストで識別できるURIにおいてイベントを受信できるように設定してください。空で残されたパスはヒットしません。影響を受けるwebhook上ではあらゆるコールバックを受けることはありません。設定する値にクエリ文字列が含まれる場合は、こちらをお読みください。

パスチャンネル作成
新たなチャンネルが作成されたとき、またはその状態が外部サービスからロードされる必要がある際に呼び出されます。
パスチャンネル崩壊
チャンネルがPhotonサーバーのメモリから取り除かれる際に呼び出されます。 IsPersistent がtrueに設定されている場合、チャンネルの状態が送信されます。
パスチャンネル登録
プレイヤーが既に作成されたチャンネルに登録している場合に呼び出されます。
パスチャンネル登録解除
プレイヤーがチャンネルから登録解除した場合に呼び出されます。
パス発行メッセージ
クライアントがチャンネル内でメッセージを発行した場合に呼び出されます。クライアントは、メッセージをWebhookとしてHTTP転送することを明示的に選択する必要があります。

オプション

これらのオプションにより、チャットのwebhook設定の挙動を微調整できます。設定されていない場合、またはその値が空のままになっている場合、オプションは設定されている状態であるとはされません。

FailIfUnavailable
trueに設定されている場合、チャンネル作成、登録、発行メッセージのオペレーションは、対応するフックの設定されたエンドポイントが利用可能でないときに失敗することとなります。そのHTTPリクエストのプロセス中にエラーが発生した場合、またはHTTPレスポンスが成功していない場合には、エンドポイントが利用可能ではないとされます。デフォルトではfalseとなっています。
IsPersistent
trueに設定されている場合、Photon Cloudは破棄の前にチャンネル情報を送信します。このオプションが有効なのは、PathChannelCreate と PathChannelDestroy の両方が適切に設定されており、かつ MaxChannelHistory が0を上回っている場合のみです。詳細については、ChannelCreateおよびChannelDestroyのwebhookを読んでください。デフォルトはfalseです。
MaxChannelHistory チャンネルごとに継続される最大メッセージ数です。 1から100の間が推奨されます。デフォルトは100です。
HasErrorInfo trueに設定されている場合、hookのエンドポイントが利用できないのに FailIfUnavailable がfalseに設定されているとき、チャットクライアントはエラーメッセージで通知されます。デフォルトはfalseです。
SkipPostCreationFailure trueに設定されている場合、PathUnsubscribe および PathChannelDestroy のwebhookは、チャンネル作成が失敗した後に送信されません。デフォルトはfalseです。

クエリ文字列の処理

クエリ文字列パラメータはベースURLまたはパスに含まれています。これを使用する場合は、以下の事柄について理解しておいてください。

クエリ文字列パラメータはUTF8エンコードで解析されます。
同じクエリ文字列パラメータの複数同時発生が、同一の設定内で見られる場合は、カンマで各値を区切りながら単一のパラメータが使用されます。カンマは%2cを使用してエスケープされます。
ベースURLと設定済みのパスで同じパラメータキーが使用されている場合、パス設定の値が使用されます。
値のないパラメータは認められています。
キーのないパラメータは認められています。キーは空の文字列とみなされます。ベースURLと設定済パスの両方でキーが足りないパラメータが見つかった場合、設定済パスのもののみが使用されます。
クエリ文字列パラメータはURLエンコードとなります。
クエリ文字列パラメータ内でURLタグを使用できます。

例:

設定:
- ベースURL:
```
        https://myawesomegame.com/chat/webhooks?clientver={AppVersion}&key=&keyA=valueA&keyA=valueB&keyB=valueB&=value
```
- PathChannelCreate: create?key=X&keyA=valueC
- PathChannelDestroy: destroy?keyB=valueC&keyC=valueC&=valueD&=valueE

生じるURL:

PathChannelCreate:

        https://myawesomegame.com/chat/webhooks/create?clientver=1.0&key=X&keyA=valueC&keyB=valueB&=value

PathChannelDestroy:

        https://myawesomegame.com/chat/webhooks/destroy?clientver=1.1&key=&keyA=valueA%2cvalueB&keyB=valueC&keyC=valueC&=valueD%2cvalueE

HTTP Headers Considerations

カスタムHTTPヘッダーの使用にあたり、いくつかの留意事項があります:

CustomHttpHeaders設定キーの値は、文字列に変更された、文字列以外を含まないプロパティのJSONオブジェクトである必要があります。JSONオブジェクトのプロパティ名は、HTTPリクエストヘッダフィールド名として使用され、プロパティの値はリクエストヘッダーのそれぞれの値として使用されます。例:
- CustomHttpHeaders 値:
```
        {'X-Secret': 'YWxhZGRpbjpvcGVuc2VzYW1l', 'X-Origin': 'Photon'}
```
- Webhooks HTTP リクエストヘッダー:
```
        X-Secret: YWxhZGRpbjpvcGVuc2VzYW1l
  X-Origin: Photon
```
カスタムHTTPヘッダーフィールド名は大文字と小文字を区別します。
次のHTTPヘッダーは制限されており、"CustomHttpHeaders"設定値から設定された場合、無視されます。
- Connection
- Content-Length
- Host
- Range
- Proxy-Connection
- Accept
- Content-Type
- Date
- Expect
- If-Modified-Since
- Referer
- Transfer-Encoding
- User-Agent

URLタグ

ダッシュボードからwebhookまたはWebRpcのベースURLを設定する場合、必要に応じて、クエリ文字列の一部として1つ以上の動的変数を設定することができます。これらの変数は、リクエストを送信する前に、バックエンドでそれぞれの値に置き換えられます。

それぞれのアプリケーションのユーザー・セグメントを個別に処理したい場合は、URLのタグを使用します。 Photonは、次のURLのタグに対応しています：

{AppVersion} クライアントによって設定されたアプリケーションのバージョンを渡します。
{AppId} アプリケーションのIDを渡します。
{Region} トリガークライアントが接続されているクラウドリージョンのトークンを渡します。例："eu"
{Cloud} は、トリガークライアントが接続されているクラウドの名前を渡します。例：「public」または「enigmaticenterprise」

URLタグの例

https://{Region}.mydomain.com/{AppId}?version={AppVersion}&cloud={Cloud}　例：パラメータとして渡される異なるホスト、バージョン、およびクラウドに各リージョンをルート。
https://mydomain.com/{Cloud}/{Region}/{AppId}/{AppVersion} 構造化されたURIとしてすべてのタグを渡します。

全てのwebhookへの共通引数

アプリケーションID: ゲームクライアントから設定されている、ダッシュボードで見られるアプリケーションのアプリケーションID

アプリケーションのバージョン: ゲームクライアント側で設定されているアプリケーションのバージョン

リージョン: ゲームクライアントが接続される、および件のルームが属する領域を持っている

ChannelType: チャンネルタイプ：パブリックチャンネルの場合はPublic、プライベートチャネルの場合はPrivate。

UserId: フックをトリガーするプレイヤーのユーザーID（ChannelDestoryを除く）。

HistoryCount: チャンネル履歴内のメッセージの現在の数（ChannelDestoryを除く）。

チャンネル名: フックがトリガー動作しているチャンネルの名前

UsersPair: プライベートチャンネルの両端のUserIDを含む2つの文字列の配列。（プライベートチャンネルのみ）。

Request Arguments List

この表から、それぞれのwebhookについて何の引数を用いることができるかが分かります:

引数	ChannelCreate / ChannelSubscribe	ChannelDestroy	PublishMessage	ChannelUnsubcribe
AppId
AppVersion
Region
ChannelType ("Public")
ChannelName
HistoryLen
HistoryCount
UserId
ChannelState
Message

プライベートチャンネルの場合、次の引数を持つ単一のwebhook PublishMessageがあります：

AppId
AppVersion
Region
ChannelType (Privateに設定)
UsersPair
HistoryCount
UserId

詳細なパス

チャンネル作成

このwebhookは、チャンネルがPhotonサーバー上で作成されようとしているときに送信されます。前回保存されたチャンネル状態がある場合、履歴をロードするためのwebhookレスポンスにおいてそれを戻さなければなりません。例としては、"戻り値を確認してください。

特定の引数

HistoryLen: 登録オペレーションの中でクライアントにより設定されているものと同じ名前を持つパラメータを転送します。これには、クライアントから要請を受けた履歴からのメッセージ数も含まれます。

サンプル呼び出し

{
   "AppId":"00000000-0000-0000-0000-000000000000",
   "AppVersion":"1.0",
   "Region":"EU",
   "ChannelType":"Public",
   "ChannelName":"PersistentChannel",
   "HistoryLen":10,
   "UserId":"testClient1"
}

ChannelDestroy

本webhookは、チャンネルがPhotonサーバー上で破棄されようとしているときに送信されます。これは、空のチャンネルがタイムアウトした際に発生します。チャンネルが空とされるのは、登録者が離れたために一人もいない場合です。デフォルトの空チャンネルタイムアウト値は5秒となっています。 IsPersistent がtrueに設定されており、PathChannelDestroy が適切に設定されている場合、 ChannelStateがwebhookボディ内で送信されます。 ChannelState内ではHistoryオブジェクトは単にデバッグ用です。これは破棄することができます。 PhotonサーバーはBinaryHistoryを用いてデータタイプを追跡します。チャンネル履歴を後にロードする場合、as is で保存してください。

特定の引数

ChannelState: 直列化可能なチャンネル状態。

サンプル呼び出し

{
   "AppId":"00000000-0000-0000-0000-000000000000",
   "AppVersion":"1.0",
   "Region":"EU",
   "ChannelType":"Public",
   "ChannelName":"PersistentChannel",
   "HistoryCount":2,
   "ChannelState":{
      "ChannelHistoryCapacity":100,
      "BinaryHistory": "RGl6AAEAAAAAAAN6AANp..",
      "History":{
         "MessageIdBase":2,
         "Entries":[
            {
               "Message":"msg1",
               "Sender":"testClient1",
               "MsgId":1
            },
            {
               "Message":"msg2",
               "Sender":"testClient2",
               "MsgId":2
            }
         ]
      }
   }
}

ChannelSubscribe

本webhookのトリガーは、既に作成されたチャンネルへのクライアントの登録です。クライアントには以下のケースがあります：:

最初の登録者ではない。最もよくあるケースです。
チャンネルが空でタイムアウトしていなかった場合、最初の登録者となります。時間が短いため、あまりあることではありません。

特定の引数

サンプル呼び出し

{
   "AppId":"00000000-0000-0000-0000-000000000000",
   "AppVersion":"1.0",
   "Region":"EU",
   "ChannelType":"Public",
   "ChannelName":"PersistentChannel",
   "HistoryLen":-1,
   "HistoryCount": 1,
   "UserId":"testClient2"
}

ChannelUnsubscribe

本webhookのトリガーは、クライアントがチャンネルとの接続を切ったときです。これは、以下の理由で起こりえます。

登録解除オペレーションを意識的に呼び出したとき。
意識的に接続を切ったとき。
タイムアウトによる接続切れ。
チャンネル作成が失敗し、SkipPostCreationFailure がfalseに設定されているとき。
登録が失敗したとき。

特定の引数

ChannelUnsubscribeには追加の引数はありません。

サンプル呼び出し

{
   "AppId":"00000000-0000-0000-0000-000000000000",
   "AppVersion":"1.0",
   "Region":"EU",
   "ChannelType":"Public",
   "ChannelName":"PersistentChannel",
   "HistoryCount":2,
   "UserId":"testClient2"
}

PublishMessage

このwebhookは、クライアントがチャンネルにメッセージを公開するか、ユーザーにプライベートメッセージを送信するとトリガーされます。クライアントは、適切なWebFlagを使用して、メッセージをwebhookとしてHTTP転送することを明示的に選択する必要があります。公開するメッセージを置き換えたい場合は、 Dataパラメーターで新しいメッセージを返すことができます。返されたwebhookレスポンスの Dataプロパティの値は、クライアントによって送信された元のメッセージコンテンツではなく、チャンネル内で公開されます。例は"Return Values" でご確認ください。

Photonの直列化で対応されている任意のタイプのデータを使用できます。使用例の1つは、Webサーバーからのデータポーリングです。 DataリターンパラメータはPhoton RealtimeのWebRPCのように使用することもできます。

特定の引数

Message: チャンネルの全ての登録者に対して発行されるメッセージです。クライアントから送信されると転送されます。

サンプル呼び出し

{
   "AppId":"00000000-0000-0000-0000-000000000000",
   "AppVersion":"1.0",
   "Region":"EU",
   "ChannelType":"Public",
   "ChannelName":"PersistentChannel",
   "HistoryCount":1,
   "UserId":"testClient2",
   "Message":"msg2"
}

プライベートチャンネル: サンプル呼び出し

{
   "AppId":"00000000-0000-0000-0000-000000000000",
   "AppVersion":"1.0",
   "Region":"EU",
   "ChannelType":"Private",
   "UsersPair":["testClient1", "testClient2"],
   "HistoryCount":1,
   "UserId":"testClient2",
   "Message":"msg2"
}

戻り値

全てのwebhookには、ResultCodeが含まれるJSONオブジェクトが期待されます。ResultCodeには以下のようなものがあります:

成功の場合は0

サンプル成功レスポンス

{
   "ResultCode":0,
   "Message":"OK"
}

その他全ての整数は失敗

サンプル失敗レスポンス

{
   "ResultCode":1,
   "Message":"A nice self explained error message"
}

"PublishMessage"webhookは、Webサーバーからの Dataの追加プロパティに対応しています。

サンプル "完全な" PublishMessage Response

{
   "ResultCode":0,
   "DebugMessage":"Message Will Be Overridden By Server",
   "Data": "Anything you want and supported by Photon Serialization"
}

"ChannelCreate" webhookは、 ChannelStateであるWebサーバーからの追加のプロパティに対応しています。

サンプル "完全な" ChannelCreateResponse

{
   "ResultCode":0,
   "DebugMessage":"ChannelState Loaded Successfully",
   "ChannelState":{
      "ChannelHistoryCapacity":100,
      "BinaryHistory": "RGl6AAEAAAAAAAN6AANp..",
      "History":{
         "MessageIdBase":2,
         "Entries":[
            {
               "Message":"msg1",
               "Sender":"testClient1",
               "MsgId":1
            },
            {
               "Message":"msg2",
               "Sender":"testClient2",
               "MsgId":2
            }
         ]
      }
   }
}

"History"は、デバッグに有用であるものの情報のロードには必要ないため、情報を保存するときあるいはロードするときに破棄することができます。

サンプル "Stripped" ChannelCreateResponse

{
   "ResultCode":0,
   "DebugMessage":"ChannelState Loaded Successfully",
   "ChannelState":{
      "ChannelHistoryCapacity":100,
      "BinaryHistory": "RGl6AAEAAAAAAAN6AANp.."
   }
}

ベストプラクティスと考えられるのは以下です:

カスタムユーザーエラータイプごとに確保されたResultCode値のリストを作る
デバッグに有用な可能性のあるMessage文字列を戻す

Response Arguments List

以下の表には、どのチャットオペレーションがwebhookを利用中にキャンセルまたは中断可能であるかが示されています。

Argument	ChannelCreate	PublishMessage	others
ResultCode
DebugMessage	(optional)	(optional)	(optional)
Data		(optional)
ChannelState	(optional)

Cancelable Operations

以下の表は、webhookを使用してキャンセルまたは中止できるチャット操作を示しています。そのためには、0以外の ResultCodeと、オプションで OperationResponseの DebugMessageにある DebugMessageを返す必要があります。

Webhook	Can Be Canceled
ChannelCreate
ChannelDestory
ChannelSubscribe
ChannelUnsubscribe
PublishMessage

データ型の変換

このセクションでは、Photonクラウドとウェブサービスの間で交換されるデータ型のみが説明されています。クライアントとPhotonサーバ間のデータ型の詳細はPhotonページのシリアル化を参照してください。

Photon Cloud -> ウェブサービス

C# / .NET (Photonが対応するタイプ)	JavaScript / JSON
`byte`	number
`short`
`int`
`long`
`double`
`bool`	bool
`string`	string
`byte[]` (byte array length < `short.MaxValue`)	string (Base64 encoded)
`T[]` (array of supported type T, length < `short.MaxValue`)	array
`Hashtable` (対応されているタイプの, カウント < `short.MaxValue`, Photon実装が望ましい)	object
`Dictionary` (対応されているタイプのキーや値, カウント < `short.MaxValue`)	object
`null`	`null`

サンプルリクエストデータ（タイプは連結されます）

Photonクラウドから送信：

ウェブサーバによって読み込み：

ウェブサービス - >Photon Cloud

各JavaScript/JSONタイプをC#/.Netの同等のものに照らし合わせる表：

JavaScript / JSON	C# / .Net
object	`Dictionary`
array	`object[]` (array of objects)
number (integral)	`long`
number (floating)	`double`
string	`string`
boolean	`bool`
`null` (タイプではない)	`null`
`undefined`（送信時）	`null`

サンプルのレスポンスデータ（タイプは連結されています）

Webサーバーから送信：

Photon Cloudから読み込み：

Webhookを保護する

HTTPSと最新のTLSバージョンの使用だけでなく、カスタムHTTPリクエストヘッダやクエリ文字列パラメータを使用してwebhookセキュリティを強化できます。受信するHTTPリクエストがPhoton Serverで生成されいることがわかるように、Photonのダッシュボードで１つもしくは複数の「秘密」（「トークン」、「キー」など）を設定します。