mixiアプリ » 技術仕様（RESTful API方式） » モバイル » リクエストAPIについて
リクエストAPIについて
リクエストAPIを利用することで、ユーザは友人に「花束を贈りますので受け取ってください」といった要求を送信することができます。
友人にリクエストを送信する
mixiアプリモバイルからリクエストAPIを利用するには、招待機能を利用する場合と同様に、invite:friendsユーザフローを利用します。
invite:friends?callback=[エスケープ済みURL]
リクエストAPIにおけるinvite:friendsユーザフローの利用は、formタグを使ったPOSTメソッドによるHTTPリクエストとなります。具体的なリクエストの内容は、type属性がhiddenであるinputタグを使って記述します。指定可能なパラメータは、以下となります。
| callback | リクエスト送信完了画面(*)へ遷移するエスケープ済みのURLを指定します。 *SAPサーバに用意していただく必要があります。 |
|---|---|
| recipients | カンマ区切りで1つ以上のユーザIDが指定された場合は、そのユーザが初期選択状態＆優先的に表示されます。 |
| message | メッセージの本文。 |
| image | メッセージに含める画像のURL。末尾にMIME typeをカンマ区切りで指定する必要があります。但し4KB以上の画像を受信すると相手にはNo Imageの画像が表示されます。 |
| filter_type | リクエストの対象となるユーザの種別。joined, not_joined, bothのいずれかを指定。 |
| url | リクエストをユーザがクリックした際の飛び先のURL（for PC, Touch）。 |
| mobile_url | リクエストをユーザがクリックした際の飛び先のURL（for Mobile）。 |
| target_users | ユーザに表示したい友人のリスト。友人全員を表示するのではなく、特定の友人に限定したい場合に、カンマ区切りで表示したい友人のユーザIDを列挙します。 |
| description | 友人の選択を促す説明文をmixiアプリ側で変更したい場合に使用します。 |
| exclude_users | ユーザの表示から除外する友人のリスト。カンマ区切りで除外する友人のユーザIDを列挙します。 |
また、ユーザがアクセスしている端末のキャリアがドコモの場合には、”guid=ON”パラメータも付加してください。
なお、パラメータで指定した値が長い場合、キャリアによっては送信できる上限に達する場合がありますので、ご注意ください。
リクエスト例
<form action="invite:friends?callback=[エスケープ済みURL]&guid=ON" method="POST"> <input type="hidden" name="recipients" value="xxxx,yyyy" /> <input type="hidden" name="message" value="花束を贈りますので受け取ってください" /> <input type="hidden" name="filter_type" value="joined" /> <input type="hidden" name="image" value="http://server.name/image.gif,image/gif" /> <input type="hidden" name="url" value="http://mixi.jp/run_appli.pl?id=[アプリID]&appParams=..." /> <input type="hidden" name="mobile_url" value="http://ma.mixi.net/[アプリID]/?..." /> <input type="submit" value="送信！" /> </form>
appParamsはJSON形式で表しURIエスケープします。
appParams以外のパラメータ名を指定した場合でもアプリの起動URLとしてパラメータは付与されますが、
TouchにおいてはappParamsで指定したパラメータのみバックエンドサーバへ送信されます。
（例：「{"uid":"1569"}」をURIエスケープして「%7B%22uid%22%3A%221569%22%7D」）
appParams=%7B%22uid%22%3A%221569%22%7D
もし友人全員ではなく、限定した友人のみを表示したい場合は、以下のようにtarget_usersを指定します。この場合、xxxx, yyyy以外の友人は表示されず、その中でyyyyのユーザにチェックが入った状態となります。
<form action="invite:friends?callback=[エスケープ済みURL]&guid=ON" method="POST"> .... <input type="hidden" name="recipients" value="yyyy" /> <input type="hidden" name="target_users" value="xxxx,yyyy" /> <input type="submit" value="送信！" /> </form>
また、特定の友人を除外して表示したい場合は、以下のようにexclude_usersを指定します。この場合、xxxx,yyyy以外の友人が表示されます。
<form action="invite:friends?callback=[エスケープ済みURL]&guid=ON" method="POST"> .... <input type="hidden" name="exclude_users" value="xxxx,yyyy" /> <input type="submit" value="送信！" /> </form>
また、もし各mixiアプリが説明文を変更したい場合は、以下のようにしてdescriptionを指定します。
<form action="invite:friends?callback=[エスケープ済みURL]&guid=ON" method="POST"> .... <input type="hidden" name="description" value="ｷﾞﾌﾄを贈りたい人を15人までで選択してください！" /> <input type="submit" value="送信！" /> </form>
送信したユーザおよびリクエストIDの取得について
ユーザが確認画面で”はい”を押すと、指定したコールバックURLにリダイレクトされます。実際にユーザが誰に送信したかは、コールバックURLに対してQuery String形式でデータが送信されます。”request_member”パラメータにユーザIDがカンマ区切り形式で渡されます。また、同時に作成されたリクエストのIDに関しても、”request_id”パラメータとして渡されます。リクエストIDはSAP側で保持し、後に対象のリクエストを削除したいときに利用可能です。
http://example.com/foo?request_member=xxxx,yyyy,zzzz&request_id=abc
エラーコード
もし何らかのエラーが発生した場合は、コールバックURLが呼び出される際に、resultパラメータにfalseが、errorパラメータに具体的なエラーコードが指定されます。エラーコードの詳細は以下となります。
| エラーコード | 概要 |
|---|---|
| 400 (BAD_REQUEST) | パラメータ指定エラー(不正なrecipients指定、不正なmessage指定、不正なcallback指定、不正なimage指定、不正なfilter_type指定、不正なurl指定、不正なmobile_url指定、不正なtarget_users指定、不正なexclude_users指定) |
| 403 (FORBIDDEN) | ユーザーがキャンセルした(アプリに戻るリンクを押下した) |
| 500 (INTERNAL_SERVER_ERROR) | mixi側の内部エラー |
リクエストの削除について
送信されたリクエストをSAP側から削除する際には、RESTful APIを使用します。詳しくは以下のページを参照ください。