Message
message.send
アプリケーションからユーザーへ通知する為の API です。
API の定義
| REST Base URI | http://app.mbga-platform.jp/social/api/restful/v2 ( Service ) http://app.sb.mbga-platform.jp/social/api/restful/v2 ( Sandbox ) |
| REST HTTP Method | POST |
| REST URI Fragment | /messages/{userId}/@self/@outbox |
| REST Query Parameters | Send-Message-Request-Parameters |
| Return Object | なし |
認可
| type | permission | description |
|---|---|---|
| ANONYMOUS | false | 未認証でのアクセス |
| SECURITY_TOKEN | false | セキュリティトークンを用いた認証 |
| OAUTH_MOBILE | false | モバイル用で発行された OAuth Token を用いた認証 |
| OAUTH_CONSUMER | true | Consumer 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 | その操作が許可されていない場合です |
| 429 | Too Many Requests | 429 | APIリクエスト数の制限を超えた場合です |
500 | Internal Server Error | -32603 | API サーバー側のエラーです |
503 | Service Unavailable | – | 一時的に API が利用不可となっている場合です |
JSON-RPC エラーコード
エラー時の Error オブジェクトの code フィールドに含まれる値です。
| RPC Code | Meaning |
|---|---|
| -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 として指定します。
| Name | Type | Description |
|---|---|---|
| userId | UserId | Required '@me' のみ指定可能。アプリケーション自身を意味します。 |
ベースとなるデータ型
- Starndard-Request-Parameters
Message
| Name | Type | Description |
|---|---|---|
| title | String | メッセージのタイトルです。 |
| recipients | String | 受信者のユーザーIDです。 |
| urls | Array | リンク先のURLです。 |
| type | MessageType | NOTIFICATION のみ設定可能です。 |
recipients フィールド
recipients は ユーザーID の配列として指定して下さい。但し現時点で recipients に指定出来る ユーザーID は 1 リクエストにつき 1 つです。
urls フィールド
Url オブジェクトの配列として指定して下さい。この際に Url オブジェクトフィールドとして指定出来るのは下記になります。
| Name | Type | Description |
|---|---|---|
| value | String | Message オブジェクトの title フィールドを表示する際のリンク先になります |
| type | String | "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 に修正