Message
アプリケーションからユーザーへ通知を行う際に利用する API です。通知されたメッセージはユーザーのマイページ「ゲームからのお知らせ」で確認する事が出来ます。
Message の生成は非同期で実行されるので、マイページに表示されるまでに若干の遅延が発生する場合があります。
Message オブジェクトフィールド
Message オブジェクトのフィールド一覧です。
| 値 | 説明 | 型 | 名前空間 | 補足 |
|---|---|---|---|---|
| title | タイトル | xs:string | http://ns.opensocial.org/2008/opensocial | – |
| recipients | 受信者の guid | xs:string (unbounded) | http://ns.opensocial.org/2008/opensocial | – |
| urls | title のリンク先の指定に使います | tns:Url (unbounded) | http://ns.opensocial.org/2008/opensocial | – |
| type | メッセージタイプ | tns:MessageType | http://ns.opensocial.org/2008/opensocial | "NOTIFICATION" (ダブルクオートは除く) のみ設定可能です |
recipients フィールド
recipients は guid の配列として指定して下さい。但し現時点で recipients に指定出来る guid は 1 リクエストにつき 1 つです。
urls フィールド
Url オブジェクトの配列として指定して下さい。この際に Url オブジェクトフィールドとして指定出来るのは下記になります。
| 値 | 説明 | 型 | 名前空間 | 補足 |
|---|---|---|---|---|
| value | URL | xs:string | http://ns.opensocial.org/2008/opensocial | Message オブジェクトの title フィールドを表示する際のリンク先になります |
| type | 利用タイプ | xs:string | http://ns.opensocial.org/2008/opensocial | "mobile" (モバイル向けのリンク url の場合) または "canvas" (PC 向けリンク url の場合) を指定して下さい。互換性の為に "title" も暫くの間は利用可能です |
API リクエスト
HTTP メソッド
Proxy モデル
- POST - アプリケーション内でのユーザー間での Message の作成
Trusted モデル
-
POST - アプリケーションからユーザーへの Message の作成
エンドポイント URL
-
Sandbox 環境
http://sb.sp.app.mbga.jp/api/restful/v1/messages/{guid}/{selector} -
本番環境
http://sp.app.mbga.jp/api/restful/v1/messages/{guid}/{selector}
URI Template パラメータ
guid
guid パラメータは @me のみ指定する事ができます。
| 値 | 説明 | 備考 |
|---|---|---|
| @me | viewer の guid、または application の id を指す | 必須 |
Proxy モデルでは @me は viewer を指します。一方で Trusted モデルの場合 @me は現在のアプリケーションを指します。
selector
selector パラメータは @outbox のみ指定する事ができます。
| 値 | 説明 | 備考 |
|---|---|---|
| @outbox | guid パラメータで指定したユーザーまたはアプリケーションの送信コレクションリソース | 必須 |
クエリパラメータ
特にありません。
API レスポンス
レスポンスコード
API のレスポンスコードは以下のいずれかになります。
| リクエスト HTTP メソッド | レスポンスコード | レスポンスメッセージ | 説明 |
|---|---|---|---|
| POST | 202 | Accepted | Message の生成リクエストを正常に受け付けた状態です |
| POST | 400 | Bad Request | リクエストデータが不正です |
| POST | 401 | Unauthorized | OAuth による認可が失敗しています |
| POST | 403 | Forbidden | 認証エラー以外の理由でアクセス出来ない場合です |
| POST | 429 | Too Many Requests | APIリクエスト数の制限を超えた場合です |
| POST | 500 | Internal Server Error | API 側の問題による失敗です |
| POST | 503 | Service Unavailable | 制限を超えて、同一ユーザーに対する Message を POST した場合 |
注意事項
- Message オブジェクトの type フィールドに指定できる値 (tnx:MessageType) は "NOTIFICATION" (ダブルクオートは除く) のみです。
- Message の送信先 (recipients) に指定出来る guid はそのアプリケーションをインストールしているユーザーのみです。
- Message の送信先 (recipients) に指定出来る guid は 1 リクエストにつき 1 つのみです。
- Message の title は 半角38文字、全角19文字 以内に収まるようにして下さい。
- 実際にユーザーに見えるメッセージには、各メッセージの先頭に時刻とアプリケーションの短縮名がつきます。
- title にユーザーからの自由入力文を設定しないようにして下さい。
- title に絵文字は使用できません。
- Proxy モードの場合、閲覧ユーザーが特定のユーザーに対して送信する Message の記録は1分間に1回までにして下さい。制限を超えたリクエストを送った場合は 503 Service Unavailable が返って来ます。
- A さんが B さんに送信した場合、A さんは B さんに1分間 Message の送信を行う事が出来ません。
- この場合 A さんは B さんに送信は出来なくなりますが、C さんに対して送信を行う事は可能です。
- Trusted モードの場合、特定のユーザーに対する Message の記録は4時間に1回までにして下さい。制限を超えたリクエストを送った場合は 503 Service Unavailable が返って来ます。
- Message のリンク先の指定は互換性の為に urls の type フィールドの値として title も暫く利用可能です。title で指定した url は mobile で指定した url と同等の扱いになります。
-
type フィールドの値として canvas を指定した際の value 値に使える url 文字列は、PC のアプリケーションのトップまたは起動画面のみです。またいずれも appParams を用いてガジェット実行時の view-params として渡す事が可能です。
PC トップ:http://yahoo-mbga.jp/game/{appId}PC 起動画面:http://yahoo-mbga.jp/game/{appId}/play
-
- ユーザーがそのアプリケーションをインストールしていない場合に レスポンスコードは 403 が返されます。
- ユーザーがアプリ設定変更にある「ゲームからの招待・お知らせを受け取らない」と設定している場合に レスポンスコードは 403 が返されます。
- Trusted モードの場合、リクエスト数を秒間250reqまでに制限して下さい。制限を超えてリクエストを送った場合は 429 Too Many Requests が返ります。
サンプル
viewer からユーザーへの通知
viewer から指定された guid へ Message を通知する場合です。
リクエスト形式
POST /api/restful/v1/messages/@me/@outbox
Content-Type: application/json; charset=utf8
{
"type" : "NOTIFICATION",
"title" : "仲間申請が届いています",
"urls" : [
{
"value" : "http://example.com/foo/bar",
"type" : "mobile"
},
{
"value": "http://sb.sp.mbga.jp/game/12000129/play?appParams=requestFriends",
"type": "canvas"
}
],
"recipients" : [
10001
]
}
レスポンス形式
202 Accepted
参考資料
OpenSocial RESTful Protocol Specification v0.9 - 10. Messaging (Optional)
XML Schema Part 2: Datatypes Second Edition
URI Template draft-gregorio-uritemplate-03
OAuth Request Body Hash 1.0 Draft 4
OAuth Consumer Request 1.0 Draft 1
更新履歴
- 2014/11/27
- アクセス制限を超えた場合のエラーについて追記しました。
- 2014/09/04
- アプリ設定変更「ゲームからの招待・お知らせを受け取らない」に関する注意事項を追記しました。
- 2013/10/01
- OAuth Signed Request (xoauth_requestor_id) に関する記述を削除しました。
- 2012/12/11
- 新規作成