メインコンテンツまでスキップ

Message

message.send​

アプリケーションからユーザーへ通知する為の API です。

API の定義​

REST Base URIhttp://app.mbga-platform.jp/social/api/restful/v2 ( Service ) http://app.sb.mbga-platform.jp/social/api/restful/v2 ( Sandbox )
REST HTTP MethodPOST
REST URI Fragment/messages/{userId}/@self/@outbox
REST Query ParametersSend-Message-Request-Parameters
Return Objectなし

認可​

typepermissiondescription
ANONYMOUSfalse未認証でのアクセス
SECURITY_TOKENfalseセキュリティトークンを用いた認証
OAUTH_MOBILEfalseモバイル用で発行された OAuth Token を用いた認証
OAUTH_CONSUMERtrueConsumer Request を用いた認証

RESTful API レスポンスコード​

HTTP Status Code

HTTP Status Message

JSON-RPC Error Codes

Meaning

202

Accepted

–

データの送信が成功した場合

400

Bad Request

-32700, -32600, -32601, -32602, 400

クライアント側のリクエストデータが不正です

401

Unauthorized

401

認証エラーです

403

Forbidden

403

リソースは存在するが認証エラー以外の理由でアクセス出来ない場合です

404

Not Found

404

存在しないリソースです

405

Method Not Allowed

405

その操作が許可されていない場合です

429Too Many Requests429APIリクエスト数の制限を超えた場合です

500

Internal Server Error

-32603

API サーバー側のエラーです

503

Service Unavailable

–

一時的に API が利用不可となっている場合です

JSON-RPC エラーコード​

エラー時の Error オブジェクトの code フィールドに含まれる値です。

RPC CodeMeaning
-32700 (Parse error)不正な JSON format です
-32600 (Invalid Request)不正な JSON-RPC リクエストです
-32601 (Method not found)存在しないメソッドまたは利用不能なメソッドです
-32602 (Invalid params)不正な API リクエストパラメータです
-32603 (Internal server error)API サーバー側のエラーです
400 (Bad Request)他のエラーに該当しないクライアント側の不正なリクエストです
401 (Unauthorized)認証エラーです
403 (Forbidden)リソースは存在するが認証エラー以外の理由でアクセス出来ない場合です
404 (Not Found)存在しないリソースです
405 (Method Not Allowed)その操作が許可されていない場合です

データ型​

Send-Message-Request-Parameters​

userId は URI Template Parameters として指定し、それ以外のパラメータは Query String として指定します。

NameTypeDescription
userIdUserIdRequired '@me' のみ指定可能。アプリケーション自身を意味します。

ベースとなるデータ型

  • Starndard-Request-Parameters

Message​

NameTypeDescription
titleStringメッセージのタイトルです。
recipientsString受信者のユーザーIDです。
urlsArrayリンク先のURLです。
typeMessageTypeNOTIFICATION のみ設定可能です。
recipients フィールド​

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

urls フィールド​

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

NameTypeDescription
valueStringMessage オブジェクトの title フィールドを表示する際のリンク先になります
typeString"mobile" (モバイル向けのリンク url の場合) または "canvas" (PC 向けリンク url の場合) を指定して下さい。

注意事項​

  • Message オブジェクトの type フィールドに指定できる値 (tnx:MessageType) は "NOTIFICATION" (ダブルクオートは除く) のみです。
  • Message の送信先 (recipients) に指定出来る guid はそのアプリケーションをインストールしているユーザーのみです。
  • Message の送信先 (recipients) に指定出来る guid は 1 リクエストにつき 1 つのみです。
  • Message の title は*半角38文字、全角19文字*以内に収まるようにして下さい。
    • 実際にユーザーに見えるメッセージには、各メッセージの先頭に時刻とアプリケーションの短縮名がつきます。
  • title にユーザーからの自由入力文を設定しないようにして下さい。
  • title に絵文字は使用できません。
  • 特定のユーザーに対する Message の記録は4時間に1回までにして下さい。制限を超えたリクエストを送った場合は 503 Service Unavailable が返って来ます。
  • type フィールドの値として canvas を指定した際の value 値に使える url 文字列は、アプリケーションのトップ (http://yahoo-mbga.jp/game/\{appId}) または起動画面 (http://yahoo-mbga.jp/game/\{appId}/play) のみです。sandbox の場合は sb.yahoo-mbga.jp になります。またいずれも appParams を用いてガジェット実行時の view-params として渡す事が可能です。
  • Trusted モードの場合、リクエスト数を秒間250reqまでに制限して下さい。制限を超えてリクエストを送った場合は 429 Too Many Requests が返ります。

サンプルデータ​

RESTful API​

POST /social/api/restful/v2/messages/@me/@self/@outbox
Content-Type: application/json; charset=utf8

{
"type" : "NOTIFICATION",
"title" : "仲間申請が届いています",
"urls" : [
{
"value" : "http://example.com/foo/bar",
"type" : "mobile"
},
{
"value" : "http://sb.yahoo-mbga.jp/game/9999999/play?appParams=requestFriends",
"type" : "canvas"
}
],
"recipients" : [
999998
]
}

参考資料​

OpenSocial Core API Server Specification 1.0
OpenSocial Core Data Specification 1.0
OpenSocial Social API Server Specification 1.0
OpenSocial Social Data Specification 1.0

更新履歴​

  • 2014/11/27

    • アクセス制限を超えた場合のエラーについて追記しました。
  • 2010/10/05

    • REST HTTP Method を GET から POST に修正
    • REST Query Parameters を PostMessage-Request-Parameters から Send-Message-Request-Parameters に修正
    • RESTful API レスポンスコード を 200 OK から 202 Accepted に修正