Message

This page is not available in English.

Please select another language.

アプリケーションからユーザーへ通知を行う際に利用する 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.app.mbga.jp/api/restful/v1/messages/{guid}/{selector}

本番環境

http://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.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/06/28
- ニュース掲載 API 改修の対応に関する記述を追加