mixi Developer Center (ミクシィ デベロッパーセンター)

mixi Connect

mixi Connect » mixi Graph API » 技術仕様 » mixiアプリ用API » 新リクエストAPI

新リクエストAPI

新リクエストAPIとは、mixiアプリ上でユーザからユーザへのリクエストを送る事ができる機能です。

また、それらリクエストを、 Push通知 や メール 等で、ユーザーへお知らせすることができます。

ここでは、新リクエストAPIについてその使用方法を説明します。

事前に必要なもの

新リクエストAPIを利用するためには以下の情報を既に入手している必要があります。
新リクエストAPIの使用する機能によって必要なスコープとアクセストークンの取得方法が異なります。

使用する機能

アクセストークン

ユーザからユーザへのリクエストの投稿

"mixi_apps2"スコープについてユーザ認可によって得られたアクセストークン

mixiアプリ運営者からユーザへのお知らせの投稿

クライアント認証によって得られたアクセストークン

上記以外のスコープで認可されたアクセストークンを使用して、新リクエストAPIにアクセスすることはできません
現状では、mixi_apps2スコープはmixiアプリやmixi API SDK for Android™、mixi API SDK for iOSからのみ利用することが可能です。

 

クライアント認証の手順

クライアント認証されたアクセストークンを取得するためのURIは以下の仕様となります。

POST https://secure.mixi-platform.com/2/token

以下のパラメータをリクエストボディにapplication/x-www-form-urlencoded形式で指定します。

 

パラメータ名

指定する値

grant_type

"client_credentials"

client_id

client_id

client_secret

Consumer Secret

各パラメータが正しければ、レスポンスで以下のようなJSON形式の認可情報を返します。

{
"refresh_token":"391e1188f707bc5d599d53c3f7b13664ba2fc3d3",
"expires_in":900,
"access_token":"5d73a24c593234f17f389d3221225aa635a6a796",
"token_type":"Bearer"
}

フィールド名

説明

refresh_token

アクセストークンを更新する際に利用するリフレッシュトークン文字列

expires_in

アクセストークンが失効するまでの時間(秒)

access_token

アクセストークン文字列

token_type

アクセストークンの種類。"Bearer"という値が返されます。

ユーザからユーザへのリクエストの投稿

新リクエストAPI機能により、mixiアプリで遊んでいるユーザから別のユーザに対してリクエストを送ることができます。

リクエストの受け取りユーザとして指定できるユーザについては「 recipientIdsで指定できるユーザについて 」をご覧下さい。

リクエストの投稿仕様

新リクエストAPIを利用するための URI は以下となります。

ユーザからユーザへのリクエストを投稿する際には ユーザ認可によって得られたアクセストークン を利用してくだい。

POST https://api.mixi-platform.com/2/apps/requests/[User-ID]

 

 

パラメータ名

指定する値

User-ID

認可を得た投稿者であるユーザーのユーザーID、もしくは @me が指定可能です

リクエストのリクエスト・ボディには、投稿内容をJSON形式で指定します。

Content-Type ヘッダには、 application/json と charset を指定します。

例えば本文に指定する文字列の文字コードがUTF-8 の場合は、 application/json; charset=utf-8 となります。

リクエスト・ボディに指定できるパラメータは以下の通りです。

パラメータ名

指定する値

必須か否か

body

全角・半角共に50文字以内

必須

recipientIds

リクエストを受け取るユーザのID (複数指定可能、15人まで)

必須

url

mixiアプリ for PC 、mixiアプリ for Touchで用いられるアプリを起動するURL
省略された場合は、対象 アプリを起動するURL

例:http://mixi.jp/run_appli.pl?id=[アプリID]&appParams=...

省略可

mobileUrl

mixiアプリ for Mobile で用いられるアプリを起動するURL
省略された場合は、対象 アプリを起動するURL

例:http://ma.mixi.net/[アプリID]/?url=...

省略可

mediaItem

下記のパラメータを持ったオブジェクト

省略可

mediaItem.mimeType

指定する画像のMIME Type

mediaItemを利用する場合必須、指定しない場合は省略

mediaItem.url

指定したい画像のURL

mediaItemを利用する場合必須、指定しない場合は省略

urlには、クエリパラメータとしてappParamsを設定することができます。

appParamsはJSON形式で表しURIエスケープします。

appParams以外のパラメータ名を指定した場合でもアプリの起動URLとしてパラメータは付与されますが、

mixiアプリ for TouchにおいてはappParamsで指定したパラメータのみバックエンドサーバへ送信されます。

(例:「{"uid":"1569"}」をURIエスケープして「%7B%22uid%22%3A%221569%22%7D」)

appParams=%7B%22uid%22%3A%221569%22%7D

 

 

例えば、リクエストボディとして、送信内容を以下のように application/json 形式にて指定します。

{
    "body" : "ボスが強い!助けて!",
    "recipientIds" : ["rdqz7s6ew176q", "kgon1ryo7omkn"],
    "url" : "http://mixi.jp/run_appli.pl?id=1234567890&appParams=%7B%22foo%22%3A%22bar%22%7D",
    "mobileUrl" : "http://ma.mixi.net/1234567890/?foo=bar",
    "mediaItem" : {
      "mimeType" : "image/jpeg",
      "url" : "http://hogefuga.com/piyo.jpeg"
    }
}

 

 

recipientIdsで指定できるユーザについて

recipientIdsに指定するユーザはどちらかの条件を満たしている必要があります。

  • リクエストを投稿しようとしているmixiアプリユーザ(User-IDで指定されている)の友人である

もしくは

  • リクエストを投稿しようとしているmixiアプリをインストールしている

前者の場合、mixiアプリをインストールしているかどうかによらずリクエストを投稿することが出来ます。

後者の場合は、友人であるかどうかによりません。

レスポンス仕様

正常に処理が行われた結果、新リクエストAPI は以下のレスポンスを application/json 形式で返却します。

HTTPステータスコードは、200が返却されます。

項目名

説明

recipientIds

リクエストを受け取るユーザのID

requestId

投稿したリクエストのID

例えば、以下の様なレスポンスが application/json 形式で返却されます。

{
    "recipientIds" : ["rdqz7s6ew176q", "kgon1ryo7omkn"],
    "requestId" : "115f89503138416a242f40fb7d7f338e"
}

 

 

エラー仕様

正常に処理が行われなかった際には、以下のエラーが返却されます。

状況

ステータスコード

error値

error_desription値

リクエストの Content-Type に application/json 以外が指定された

400

bad_request

Invalid Content Type

不正な User-ID

400

bad_request

Invalid User ID

mixi_apps2 スコープの認可を得ていない

401

unauthorized

Unauthorized

リクエストの受け取りユーザのユーザーのIDが不正

400

parameter_invalid

Invalid Recipient IDs

上記以外の何らかのリクエストパラメータが不正

400

parameter_invalid

Parameter Invalid

上記以外の何らかの理由でアクセス出来なかった

403

forbidden

Forbidden

API側で何らかの理由で失敗した

500

internal_server_error

Internal Server Error

制限を超えた頻度でリクエストが送られた(60秒間に1回)

503

service_unavailable

Service Unavailable

例えば、不正な User-ID が指定された場合は、以下の様なエラーレスポンスが application/json 形式で返却されます。

{
    "error" : "bad_request",
    "error_description" : "Invalid User ID"
}

 

 

利用制限

  • 60秒間に1回まで登録ができます。mixiアプリ・ユーザごとの制限になります。

mixiアプリ運営者からユーザへのお知らせの投稿

新リクエストAPIの機能により、「mixiアプリ運営者」から 「mixiアプリをインストールしている任意のユーザ」へリクエストを投稿できるようになります。

お知らせの投稿仕様

新リクエストAPIを利用するための URI は以下となります。APIを呼び出すときはクライアント認証によって得られたアクセストークンを利用してくだい。

POST http://api.mixi-platform.com/2/apps/requests/[User-ID]

※ユーザからユーザへの投稿とURIの形式は同じですが、アクセストークンを取得する方法によって機能が変わります。

パラメータ名

指定する値

User-ID

@me だけが指定可能です

※mixiアプリ運営者からユーザへのお知らせの投稿の場合、 @me は投稿者であるmixiアプリを表しています。

HTTPリクエストのリクエスト・ボディには、投稿内容をJSON形式で指定します。
Content-Type ヘッダには、 application/json と charset を指定します。
例えばUTF-8 の場合は、 application/json; charset=utf-8 となります。

パラメータ名

指定する値

必須か否か

body

全角・半角共に50文字以内

必須

recipientIds

リクエストを受け取るユーザのID
mixiアプリ運営者からユーザへのお知らせの投稿の場合は、1人のみ指定可能です。

必須

url

mixiアプリ for PC 、mixiアプリ for Touchで用いられるアプリを起動するURL
省略された場合は、対象アプリを起動するURL

例:http://mixi.jp/run_appli.pl?id=[アプリID]&appParams=...

省略可

mobileUrl

mixiアプリ for Mobile で用いられるアプリを起動するURL
省略された場合は、対象アプリを起動するURL

例:http://ma.mixi.net/[アプリID]/?url=...

省略可

mediaItem

下記のパラメータを持ったオブジェクト

省略可

mediaItem.mimeType

指定する画像のMIME Type

mediaItemを利用する場合必須、指定しない場合は省略

mediaItem.url

指定したい画像のURL

mediaItemを利用する場合必須、指定しない場合は省略

urlには、クエリパラメータとしてappParamsを設定することができます。
appParamsはJSON形式で表しURIエスケープします。
appParams以外のパラメータ名を指定した場合でもアプリの起動URLとしてパラメータは付与されますが、
mixiアプリ for TouchにおいてはappParamsで指定したパラメータのみバックエンドサーバへ送信されます。
(例:「{"uid":"1569"}」をURIエスケープして「%7B%22uid%22%3A%221569%22%7D」)

appParams=%7B%22uid%22%3A%221569%22%7D

例えば、リクエストボディとして、送信内容を以下のように application/json 形式にて指定します。

{
    "body" : "ボス討伐イベント期間が始まりました",
    "recipientIds" : ["rdqz7s6ew176q"],
    "url" : "http://mixi.jp/run_appli.pl?id=1234567890&appParams=%7B%22foo%22%3A%22bar%22%7D",
    "mobileUrl" : "http://ma.mixi.net/1234567890/?foo=bar",
    "mediaItem" : {
      "mimeType" : "image/jpeg",
      "url" : "http://hogefuga.com/piyo.jpeg"
    }
}

 

recipientIdsで指定できるユーザについて

recipientIdsに指定するユーザは以下の条件を満たしている必要があります。

  • リクエストを投稿しようとしているmixiアプリをインストールしている

レスポンス仕様

正常に処理が行われた結果、新リクエストAPIは以下のレスポンスを application/json 形式で返却します。HTTPステータスコードは、200が返却されます。

 

項目名

説明

recipientIds

リクエストを受け取るユーザのID

requestId

投稿したリクエストのID

例えば、以下の様なレスポンスが application/json 形式で返却されます。

 

{
    "recipientIds" : ["rdqz7s6ew176q", "kgon1ryo7omkn"],
    "requestId" : "115f89503138416a242f40fb7d7f338e"
}

 

エラー仕様

正常に処理が行われなかった際には、以下のエラーが返却されます。

状況

ステータスコード

eroor値

error_desription値

リクエストの Content-Type に application/json 以外が指定された

400

bad_request

Invalid Content Type

不正な User-ID

400

bad_request

Invalid User ID

リクエストの受け取りユーザのIDが不正

400

parameter_invalid

Invalid Recipient IDs

上記以外の何らかのリクエストパラメータが不正

400

parameter_invalid

Parameter Invalid

上記以外の何らかの理由でアクセス出来なかった

403

forbidden

Forbidden

API側で何らかの理由で失敗した

500

internal_server_error

Internal Server Error

制限を超えた頻度でリクエストが送られた

503

service_unavailable

Service Unavailable


例えば、不正な User-ID が指定された場合は、以下の様なエラーレスポンスが application/json 形式で返却されます。

{
    "error" : "bad_request",
    "error_description" : "Invalid User ID"
}

 

利用制限

  • 4時間に1回まで投稿ができます。mixiアプリ・ユーザごとの制限になります。
  • ユーザはmixiアプリ運営者からユーザへ投稿されたお知らせとして最後に投稿されたもののみ受け取ることが可能であり、最新の1件以外は削除されます。

注意事項

  • クライアント認証の場合、Consumer Secret が漏れると、ユーザの認可なく第三者からリクエストを送られる可能性がありますので、この API を使う際に Consumer Secret はサーバーサイドに置き、より厳重な Secret の管理を必ずお願いします。

 

このページの上部へ