跳到主要内容

Message

アプリケーションからユーザーへ通知を行う際に利用する API です。通知されたメッセージはユーザーのマイページ「ゲームからのお知らせ」で確認する事が出来ます。
Message の生成は非同期で実行されるので、マイページに表示されるまでに若干の遅延が発生する場合があります。

信息

SmartphoneWebではマイゲームにて表示をご確認ください。


Message オブジェクトフィールド​

Message オブジェクトのフィールド一覧です。

値説明型名前空間補足
titleタイトルxs:stringhttp://ns.opensocial.org/2008/opensocial–
recipients受信者の guidxs:string (unbounded)http://ns.opensocial.org/2008/opensocial–
urlstitle のリンク先の指定に使いますtns:Url (unbounded)http://ns.opensocial.org/2008/opensocial–
typeメッセージタイプtns:MessageTypehttp://ns.opensocial.org/2008/opensocial"NOTIFICATION" (ダブルクオートは除く) のみ設定可能です

recipients フィールド​

recipients は guid の配列として指定して下さい。但し現時点で recipients に指定出来る guid は 1 リクエストにつき 1 つです。

urls フィールド​

Url オブジェクトの配列として指定して下さい。この際に Url オブジェクトフィールドとして指定出来るのは下記になります。

値説明型名前空間補足
valueURLxs:stringhttp://ns.opensocial.org/2008/opensocialMessage オブジェクトの title フィールドを表示する際のリンク先になります
type利用タイプxs:stringhttp://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 のみ指定する事ができます。

値説明備考
@meviewer の guid、または application の id を指す必須

Proxy モデルでは @me は viewer を指します。一方で Trusted モデルの場合 @me は現在のアプリケーションを指します。

selector​

selector パラメータは @outbox のみ指定する事ができます。

値説明備考
@outboxguid パラメータで指定したユーザーまたはアプリケーションの送信コレクションリソース必須

クエリパラメータ​

特にありません。


API レスポンス​

レスポンスコード​

API のレスポンスコードは以下のいずれかになります。

リクエスト HTTP メソッドレスポンスコードレスポンスメッセージ説明
POST202AcceptedMessage の生成リクエストを正常に受け付けた状態です
POST400Bad Requestリクエストデータが不正です
POST401UnauthorizedOAuth による認可が失敗しています
POST403Forbidden認証エラー以外の理由でアクセス出来ない場合です
POST429Too Many RequestsAPIリクエスト数の制限を超えた場合です
POST500Internal Server ErrorAPI 側の問題による失敗です
POST503Service 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/06/28
    • ニュース掲載 API 改修 の対応に関する記述を追加
  • Message オブジェクトフィールド
    • recipients フィールド
    • urls フィールド
  • API リクエスト
    • HTTP メソッド
    • エンドポイント URL
    • クエリパラメータ
  • API レスポンス
    • レスポンスコード
  • 注意事項
  • サンプル
    • viewer からユーザーへの通知
  • 参考資料
  • 更新履歴