User Chat Channel
概要
ユーザーが参加しているチャンネルとチャンネルとユーザー間で関連する情報を管理する為の API です。
ゲームチャットの使い方に関しては、こちらのチュートリアルをご確認下さい。
- 1 ユーザにつき、1 チャットルームを作成し、特定ユーザーのみにメッセージ(ゲームからのお知らせ)を送る行為は禁止されています。
- 1アプリケーションにつき生成できるチャンネルの最大エントリ数は 1,000,000 件 になります。
UserChatChannel オブジェクトフィールド
ユーザーが参加しているチャンネルを表すオブジェクトです。
| 値 | 説明 | 型 | 補足 |
|---|---|---|---|
| id | チャンネル ID | xs:string | チャンネルを一意に示す識別子 |
| unreadMessages | 未読件数 | xs:int | – |
| joined | 参加日時 | xs:date | 参加日時 (ISO8601, GMT表記) |
| updated | 更新日時 | xs:date | 更新日時 (ISO8601, GMT表記) |
API リクエスト
HTTP メソッド
Authorization Code Grant
- GET ユーザーが参加しているチャンネル一覧の取得,ユーザーが参加しているチャンネルの取得
Client Credentials Grant
- GET サポートしていません。
エンドポイント URL
-
Sandbox 環境
https://sb-app.mobage.jp/social/api/restful/v2/people/{userId}/{groupId}/channels/{-prefix|/|channelId} -
本番環境
https://app.mobage.jp/social/api/restful/v2/people/{userId}/{groupId}/channels/{-prefix|/|channelId}URI Template パラメータ
userId
userId パラメータは下記のいずれかの値を指定します。
値 説明 備考 @me viewer のユーザーIDと同義 必須 groupId
groupId パラメータは下記のいずれかの値を指定します。
値 説明 備考 @self userId パラメータで指定したユーザー自身のプロフィール情報に対するエントリリソース 必須 channelId
channelId パラメータは下記のいずれかの値を指定します。
値 説明 備考 {channelId} チャンネル ID 任意 クエリパラメータ
下記のクエリパラメータを指定する事が出来ます。
format
レスポンス形式を指定する事が出来ます。
| 値 | 説明 | 備考 |
|---|---|---|
| json | "application/json; charset=utf8" | 任意、デフォルト値 |
fields
取得したいチャンネル情報を指定する事が出来ます。指定可能なフィールド名については UserChatChannel オブジェクトフィールドを参照して下さい。
複数指定する場合はスペース無しのカンマ (,) 区切りで指定します。
fields パラメータを省略した場合、下記の属性情報全てを取得します。
パフォーマンス向上の為に、必要な属性のみを取得するようにして下さい。
count
コレクションリソースとしてレスポンスを取得する際に、最大何件のエントリリソースを取得するかを指定出来ます。
デフォルト値は 50 件で、最大 1000 件まで指定出来ます。
パフォーマンス向上の為に、必要な件数のみを取得するようにして下さい。
startIndex
コレクションリソースの開始値を指定します。省略時は 1 が指定されます。
sortBy
sortBy は UserChatChannel コレクションの取得時にのみ使う事が出来ます。
sortBy と sortOrder を指定すると、レスポンスとして返って来る UserChatChannel オブジェクトのコレクションに対してソート条件を加える事が出来ます。sortBy 値はソートのキーとなるフィールドを指定する事が出来ます。
現在指定可能な sortBy 値は以下の表になります。
| sortBy | 説明 |
|---|---|
| updated | UserChatChannel の更新日時 |
sortBy を指定する場合、sortOrder も指定されている必要があります。
sortOrder
sortOrder は UserChatChannel コレクションの取得時にのみ使う事が出来ます。
sortBy と sortOrder を指定すると、レスポンスとして返って来る UserChatChannel オブジェクトのコレクションに対してソート条件を加える事が出来ます。sortOrder 値はソート時の昇順、降順を指定する事が出来ます。
現在指定可能な sortOrder 値は以下の表になります。
| sortOrder | 説明 |
|---|---|
| ascending | 昇順 |
| descending | 降順 |
sortOrder を指定する場合、sortBy も指定されている必要があります。
APIレスポンス
レスポンスコード
API のレスポンスコードは以下のいずれかになります。
| リクエスト HTTP メソッド | レスポンスコード | レスポンスメッセージ | 説明 |
|---|---|---|---|
| GET | 200 | OK | 参加者の取得に成功した場合 |
| GET | 400 | Bad Request | データ形式が不正な場合 |
| GET | 401 | Unauthorized | 不正な Authorization ヘッダの場合 |
| GET | 403 | Forbidden | 実行しようと操作の権限がない場合 |
| GET | 404 | Not Found | 存在しない userId, channelIdが指定された場合 |
| GET | 500 | Internal Server Error | サーバー側の処理でエラーが発生した場合 |
| GET | 503 | Service Unavailable | サーバー側が一時的にサービス停止している場合 |
サンプル
ユーザーが参加しているチャンネル一覧を取得
リクエスト形式
GET /social/api/restful/v2/people/@me/@self/channels?count=50&fields=id%2Cupdated&sortBy=updated&sortOrder=descending&startIndex=1
レスポンス形式
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"entry" : [
{
"id" : "123",
"updated" : "2013-04-11T13:20:52"
},
{
"id" : "163",
"updated" : "2013-04-11T10:34:12"
}
],
"itemsPerPage" : 50,
"startIndex" : 1,
"totalResults" : 2
}
ユーザーが参加しているチャンネルを取得
リクエスト形式
GET /social/api/restful/v2/people/@me/@self/channels/100?fields=id%2CunreadMessages%2Cupdated
レスポンス形式
200 OK HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"id" : "100",
"unreadMessages" : 12,
"updated" : "2013-04-11T10:31:10"
}