User Chat Channel

概要

ユーザーが参加しているチャンネルとチャンネルとユーザー間で関連する情報を管理する為の API です。

  • 1 ユーザにつき、1 チャットルームを作成し、特定ユーザーのみにメッセージ(ゲームからのお知らせ)を送る行為は禁止されています。
  • 1アプリケーションにつき生成できるチャンネルの最大エントリ数は 1,000,000 件 になります。
ゲームチャットの使い方に関しては、こちらのチュートリアルをご確認下さい。

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

ユーザーが参加しているチャンネルを表すオブジェクトです。

説明

名前空間

補足

id

チャンネル ID

xs:string

http://ns.dena.jp/mbga/gameapi/v1

チャンネルを一意に示す識別子

unreadMessages

未読件数

xs:int

http://ns.dena.jp/mbga/gameapi/v1

joined

参加日時

xs:date

http://ns.dena.jp/mbga/gameapi/v1

参加日時 (ISO8601, GMT表記)

updated

更新日時

xs:date

http://ns.dena.jp/mbga/gameapi/v1

更新日時 (ISO8601, GMT表記)

API リクエスト

HTTP メソッド

Proxy モデル

  • GET
    • ユーザーが参加しているチャンネル一覧の取得
    • ユーザーが参加しているチャンネルの取得

エンドポイント URL

  • Sandbox 環境
    http://sb.app.mbga.jp/social/api/restful/v2/people/{userId}/{groupId}/channels/{-prefix|/|channelId}
  • 本番環境
    http://app.mbga.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"
}

参考資料

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/03/14
    • userIdパラメータに関する誤った記述を修正しました。
  • 2013/10/01
    • OAuth Signed Request (xoauth_requestor_id) に関する記述を削除しました。
  • 2013/06/20
    • サンプルの誤植の修正
  • 2013/04/25
    • 新規作成

PREVIOUS

Chat Widget

NEXT

Learderboard