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.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 改修 の対応に関する記述を追加

PREVIOUS

Activity

NEXT

AppData