Chat Member

This page is not available in English.

Please select another language.

概要

チャットの参加者を管理する為の API です。

1 ユーザにつき、1 チャットルームを作成し、特定ユーザーのみにメッセージを送る行為は禁止されています。
1アプリケーションにつき生成できるチャンネルの最大エントリ数は 1,000,000 件になります。

ゲームチャットの使い方に関しては、こちらのチュートリアルをご確認下さい。

ChatMember オブジェクトフィールド

参加者を表すオブジェクトです。

値	説明	型	名前空間	補足
id	グローバルオブジェクト ID	xs:string	http://ns.dena.jp/mbga/gameapi/v1	id = objectType + ':' + localId というフォーマット
objectType	ChatMember オブジェクトの型	xs:string	http://ns.dena.jp/mbga/gameapi/v1	"person" のみ指定可能
localId	ローカル ID	xs:string	http://ns.dena.jp/mbga/gameapi/v1	objectType ごとにユニークに割り当てられた識別子（People の userId の localId と同義）
joined	参加日時	xs:date	http://ns.dena.jp/mbga/gameapi/v1	参加日時 (ISO8601, GMT表記)

API リクエスト

HTTP メソッド

Trusted モデル

GET
- 参加者一覧の取得
- 参加者の取得
POST
- 参加者の追加
DELETE
- 参加者の削除

エンドポイント URL

Sandbox 環境

http://sb.sp.app.mbga.jp/social/api/restful/v2/chat/{appId}/channels/{channelId}/members/{-prefix|/|id}

本番環境

http://sp.app.mbga.jp/social/api/restful/v2/chat/{appId}/channels/{channelId}/members/{-prefix|/|id}

URI Template パラメータ

appId

appId パラメータは下記のいずれかの値を指定します。

値	説明	備考
@app	現在実行中のアプリケーション ID	必須

channelId

channelId パラメータは下記のいずれかの値を指定します。

値	説明	備考
{channelId}	チャンネル ID	必須

id

id パラメータは下記のいずれかの値を指定します。

値	説明	備考
{id}	ChatMember オブジェクトの ID	任意

クエリパラメータ

下記のクエリパラメータを指定する事が出来ます。

format

レスポンス形式を指定する事が出来ます。

値	説明	備考
json	"application/json; charset=utf8"	任意、デフォルト値

fields

取得したいチャンネル情報を指定する事が出来ます。指定可能なフィールド名については ChatMember オブジェクトフィールドを参照して下さい。
複数指定する場合はスペース無しのカンマ (,) 区切りで指定します。
fields パラメータを省略した場合、下記の属性情報全てを取得します。

パフォーマンス向上の為に、必要な属性のみを取得するようにして下さい。

count

コレクションリソースとしてレスポンスを取得する際に、最大何件のエントリリソースを取得するかを指定出来ます。

デフォルト値は 50 件で、最大 1000 件まで指定出来ます。

パフォーマンス向上の為に、必要な件数のみを取得するようにして下さい。

startIndex

コレクションリソースの開始値を指定します。省略時は 1 が指定されます。

sortBy

sortBy は ChatMember コレクションの取得時にのみ使う事が出来ます。

sortBy と sortOrder を指定すると、レスポンスとして返って来る ChatMember オブジェクトのコレクションに対してソート条件を加える事が出来ます。sortBy 値はソートのキーとなるフィールドを指定する事が出来ます。

現在指定可能な sortBy 値は以下の表になります。

sortBy	説明
joined	ChatMember の参加日時

sortBy を指定する場合、sortOrder も指定されている必要があります。

sortOrder

sortOrder は Channel コレクションの取得時にのみ使う事が出来ます。

sortBy と sortOrder を指定すると、レスポンスとして返って来る ChatMember オブジェクトのコレクションに対してソート条件を加える事が出来ます。sortOrder 値はソート時の昇順、降順を指定する事が出来ます。

現在指定可能な sortOrder 値は以下の表になります。

sortOrder	説明
ascending	昇順
descending	降順

sortOrder を指定する場合、sortBy も指定されている必要があります。

API レスポンス

レスポンスコード

API のレスポンスコードは以下のいずれかになります。

リクエスト HTTP メソッド	レスポンスコード	レスポンスメッセージ	説明
GET	200	OK	参加者の取得に成功した場合
POST	201	Created	参加者の追加が成功した場合
DELETE	204	No Content	参加者の追加/削除が成功した場合
POST/DELETE	207	Multi-Status	複数参加者の追加/削除が成功した場合
GET/POST/DELETE	400	Bad Request	データ形式が不正な場合
GET/POST/DELETE	401	Unauthorized	不正な Authorization ヘッダの場合
GET/POST/DELETE	403	Forbidden	実行しようと操作の権限がない場合
GET/POST/DELETE	404	Not Found	存在しない appId, channelId, id が指定された場合
POST	409	Conflict	既に存在するメンバーを追加しようとした場合
POST	422	Unprocessable Entity	101人目以上のメンバーを追加しようとした場合
GET/POST/DELETE	500	Internal Server Error	サーバー側の処理でエラーが発生した場合
GET/POST/DELETE	503	Service Unavailable	サーバー側が一時的にサービス停止している場合

サンプル

参加者一覧の取得

リクエスト形式

GET /social/api/restful/v2/chat/@app/channels/100/members?count=50&fields=id%2CobjectType%2ClocalId%2Cjoined&sortBy=joined&sortOrder=descending&startIndex=1

レスポンス形式

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
   "entry" : [
      {
         "id" : "person:11030",
         "objectType" : "person",
         "localId" : "11030",
         "joined" : "2013-03-30T21:21:26"
      },
      {
         "id" : "person:11031",
         "objectType" : "person",
         "localId" : "11031",
         "joined" : "2013-03-30T18:34:46"
      }
   ],
   "itemsPerPage" : 50,
   "startIndex" : 1,
   "totalResults" : 2
}

参加者の取得

リクエスト形式

GET /social/api/restful/v2/chat/@app/channels/100/members/person%3A11031?fields=id%2CobjectType%2ClocalId%2Cjoined

レスポンス形式

200 OK HTTP/1.1
Content-Type: application/json; charset=utf-8
 
{
   "id" : "person:11031",
   "objectType" : "person",
   "localId" : "11031",
   "joined" : "2013-03-30T18:38:16"
}

参加者の追加

リクエスト形式

POST /social/api/restful/v2/chat/@app/channels/110/members
Content-Type: application/json; charset=utf8

{
   "objectType" : "person",
   "localId" : "34127"
}

レスポンス形式

201 Created
Content-Type: application/json; charset=utf-8

{
   "id" : "person:34127",
   "objectType" : "person",
   "localId" : "34127",
   "joined" : "2013-03-30T15:15:21"
}

複数参加者の追加

リクエスト形式

POST /social/api/restful/v2/chat/@app/channels/110/members
Content-Type: application/json; charset=utf8

[
   {
      "objectType" : "person",
      "localId" : "34127"
   },
   {
      "objectType" : "person",
      "localId" : "67349"
   }
]

レスポンス形式

207 Multi-Status
Content-Type: application/json; charset=utf-8
 
[
   {
      "id" : "person:34127",
      "status" : 201,
      "entity" : {
         "id" : "person:34127",
         "objectType" : "person",
         "localId" : "34127",
         "joined" : "2013-04-08T13:13:44"
      }
   },
   {
      "id" : "person:67349",
      "status" : 409
   }
]

参加者の削除

リクエスト形式

DELETE /social/api/restful/v2/chat/12000129/channels/768/members/person%3A11231

レスポンス形式

204 No Content

複数参加者の削除

リクエスト形式

DELETE /social/api/restful/v2/chat/12000129/channels/273/members/person%3A11231,person%3A11461,person%3A53411

レスポンス形式

207 Multi-Status
Content-Type: application/json; charset=utf8
 
[
   {
      "id" : "person:11231",
      "status" : 204
   },
   {
      "id" : "person:11461",
      "status" : 404
   },
   {
      "id" : "person:53411",
      "status" : 204
   }
]

参考資料

The OAuth 1.0 Protocol (RFC 5849)
URI Template (RFC6570)
5.6. Internet Date/Time Format - Date and Time on the Internet: Timestamps (RFC 3339)
7.3.1. date-time - JSON Schema: interactive and non interactive validation draft-fge-json-schema-validation-00

更新履歴

2014/02/06
- DELETEサンプルの誤植の修正
2013/10/01
- OAuth Signed Request (xoauth_requestor_id) に関する記述を削除しました。
2013/06/20
- サンプルの誤植の修正
2013/04/25
- 新規作成