mixiアプリ » 技術仕様(RESTful API方式) » ライフサイクルイベントについて
ライフサイクルイベントについて
ライフサイクルイベントは、OpenSocial 0.8.1 にて規定されている「コンテナ上で起こったアプリケーションに関する事象を、アプリケーションプロバイダに送信するための仕様」です。mixi ではライフサイクルイベントのうち、現在
- event.addapp
- event.removeapp
の2つをご提供しています。アプリケーションプロバイダは対象mixiアプリ設定画面の、「ライフサイクルイベントに関する設定」で、ライフサイクルイベントを受け取るための設定を行うことで、そのmixiアプリに関して、
- どのユーザが使用を開始したのか
- どのユーザが使用を終了したのか
といった情報を外部サーバにて受けとることが可能になります。開発、公開したmixiアプリの利用状況の把握や、使用を終了したユーザに関する情報の削除処理などを行うためのきっかけとして、ライフサイクルイベントを利用すると良いでしょう。
ライフサイクルイベントの使用宣言
開発したmixiアプリに関するライフサイクルイベントを利用するためには、対象mixiアプリ設定画面の、「ライフサイクルイベントに関する設定」で、以下のように設定を行います。
各設定は、それぞれ、以下のライフサイクルイベントに対応しています。
メニュー名 | ライフサイクルイベント |
---|---|
アプリ追加情報 | event.addapp |
アプリ削除情報 | event.removeapp |
上記のコード例では、以下のような定義となります。
- ユーザがこのmixiアプリの使用を開始したことを、http://example.com/add にGETでリクエストを送信する
- ユーザがこのmixiアプリの使用を終了したことを、http://example.com/remove にPOSTでリクエストを送信する
設定を変更した後、「設定を変更する」ボタンを押下します。これによりライフサイクルイベントの登録が行われます。
ライフサイクルイベントを解除する場合は、エンドポイントの記述を削除した後、「設定を変更する」ボタンを押下してください。
送信されるパラメータ
実際にライフサイクルイベントに関する通知が行われる際には、関係する情報がパラメータ値として同時に送信されます。以下に送信されるパラメータをイベントごとに示します。
event.addapp
アプリ追加情報を設定した場合、以下のパラメータが渡されます。
- eventtype – “event.addapp”
- opensocial_app_id – mixiアプリのID
- id – mixiアプリの使用を開始したユーザのID
- mixi_invite_from – 招待を受けてmixiアプリの使用を開始した場合の、招待したユーザのID
event.removeapp
アプリ削除情報を設定した場合、以下のパラメータが渡されます。
- eventtype – “event.removeapp”
- opensocial_app_id – mixiアプリのID
- id – mixiアプリの使用を終了したユーザのID
ライフサイクルイベントの通知頻度
エンドポイントへのライフサイクルイベントの通知は、これにかかる負荷などのコストを考慮し、ユーザのアクションに対してリアルタイムに行われるのではなく、定期的に通知が行われます。そのため、ユーザのアクションと実際の通知に関して、遅延が発生いたしますので、それを前提とした設計を行ってください。
準備するエンドポイントに関しては、必ずリクエストの受信成功とステータスコードとして200を返却するようにしてください。受信に失敗した場合であっても再送はされません。200以外のステータスコードが返却されると、一定時間ライフサイクルイベントの通知を中断します。その間の通知は送信されません。
各イベントのマージ
ライフサイクルイベントの通知は定期的に行われます。その際に、一定期間内で発生した各イベントごとにリクエストが行われるのではなく、同一イベントであれば一つのリクエストにまとめられます。具体的には、同じイベント種別であり、ユーザのIDのみが異なる複数のイベントについて、リクエストがマージされます。
例えば、mixiアプリXについて、ユーザID=A,B,Cそれぞれのユーザがそのアプリの使用を開始したことを”http://example.com/add”にGETで送信する場合、
- GET /add?opensocial_app_id=X&id=A
- GET /add?opensocial_app_id=X&id=B
- GET /add?opensocial_app_id=X&id=C
というリクエストが個別に送信されるのではなく、
- GET /add?opensocial_app_id=X&id=A&id=B&id=C
といったようにリクエストが一つにまとめられます。エンドポイント側で、複数のidパラメータが指定されている場合についても、正しく受け取れるように処理を行うようにしてください。
また、あるユーザに招待されたことを受けてアプリの利用を開始したユーザに関するリクエストの場合、mixi_invite_fromパラメータは各リクエストで0個もしくは1個となります。例えば、
- ユーザAの招待を受けて、ユーザBとユーザCが利用開始した。
- ユーザBの招待を受けて、ユーザDが利用開始した。
- 招待に関係なく、ユーザAが利用開始した。
という場合は、
- id=B&id=C&mixi_invite_from=A
- id=D&mixi_invite_from=B
- id=A
という3つのリクエストが送信されます。
署名の検証
ライフサイクルイベントによって送信されるリクエストには、Authorizationリクエストヘッダに署名が付与されています。これを検証することによって、妥当なリクエストかどうかをエンドポイント側で判断することが可能です。
具体的な検証方法は、以下のドキュメントをご参照ください。
[署名付きリクエストの検証]
http://developer.mixi.co.jp/appli/spec/pc/validating_signed_requests/
POSTメソッドを利用する場合はmixiモバイル同様PostBodyを署名のベース文字列に含めないようご注意ください。
また、
ライフサイクルイベントでのリクエストでは、opensocial_owner_idパラメータおよびopensocial_viewer_idパラメータが送信されることはありません。上記の署名検証に加えて、これらのパラメータがリクエストに含まれないことも同時に確認を行うようにしてください。
公開鍵
-----BEGIN CERTIFICATE----- MIIEKDCCApACCQDTo5idqFSRvTANBgkqhkiG9w0BAQsFADBWMQswCQYDVQQGEwJK UDEOMAwGA1UECAwFVG9reW8xEDAOBgNVBAcMB1NoaWJ1eWExEzARBgNVBAoMCk1J WEksIEluYy4xEDAOBgNVBAMMB21peGkuanAwHhcNMjMwNjAyMDYyMDE4WhcNMzMx MTAxMDYyMDE4WjBWMQswCQYDVQQGEwJKUDEOMAwGA1UECAwFVG9reW8xEDAOBgNV BAcMB1NoaWJ1eWExEzARBgNVBAoMCk1JWEksIEluYy4xEDAOBgNVBAMMB21peGku anAwggGiMA0GCSqGSIb3DQEBAQUAA4IBjwAwggGKAoIBgQDqAUBSR414H9uMS4ib uI5zOWzOwQ3yNSHUuoJ09/Vz63uCM9kZoyVGs+6m+rnQMWBHp6fcJz++VKA2AeBn z59Upf8yxrBicGT9qA6cOiscp4dbWPGzK9KD3UJCQV6DL7Q8DG+busVtFuAJY1kb NkPemYHcy9CdbwqOriVnp0cloyB8ItqWTRrfuiTuB4OfvesGUOL4/tJetpLgydlX mUYcJlYph7uG55rkyovqXmpt81v/cF08wkH8MOCuCg1D2hslEXeXYG1dEVstOLYi kEc4tlpo+LdfOPY2gnrmw4K52dTLsWrXhjYSDkezbiQN9CIj9/yXvkVETXXd8ILZ +qDnZIOi1VBx2Pi4p1OCoTXfr95z1G8XSvNwfiAWK3Hy589z5PCTA3G4tMOZ1Amy faLA0f2fARCU3vNiz3vsXjGvvHeibUbtVFKd5O5+Hh//yh3jOjX9irgflzPUBJUz GM8f8Eq6jsCOdqhG//cM26NfPj62Ce5qyAD32VVHH9iuGrMCAwEAATANBgkqhkiG 9w0BAQsFAAOCAYEAW1ezTxL2RQGvUJHnWXC72mr/7fDJ5fdDclBNn1X2b0V5uHI7 bAXO1MTkWcN++w20GfJ5oDvGLHOXBRoAU2ieHBeQZ9szrKs50iPL40Hz9YksI3hV 0aHMsgEowv5TNLaYFUjccAsXB1+EG+Iqg66yryRycFFm6BEM/7akl0jcULnINQf2 0scboWzfGYoQCe5foPKPUdek1U2Xt57xkazpRZZnh3pQ62hq1Gw55LT3kl+Lt/37 Zz1RjE1T9/nkkNgrFqRbOuGDyt/1Y6wxNxumfIGZiCaAxL+fDD0DWpSN4ty9D3tZ +tmuVMnr+qwEaJiR6s8DNLnUtEcDkNBqItxWhQZcagA1X0hnuBMlGBtrP7MIbRLS xmQQppFtHpt7QQzo2MjVpIq29j2CBbKGBxMIXTNIhfHXNraVC42SLp2C/2jFNCq1 ul42Q1wK8z4q3sh2vFzegjQxDq9luJf2Ke6GcFjvsPB+ophCGFkjA6vs6AWgOL2e JKLy8bBQIuQ7KBgt -----END CERTIFICATE-----
サンプルコード
ライフサイクルイベントに付加されている署名を検証するためのサンプルコード(PHP)を以下に掲載します。
<?php require_once("OAuth.php"); class MixiSignatureMethod extends OAuthSignatureMethod_RSA_SHA1 { protected function fetch_public_cert(&$request) { return <<< EOD -----BEGIN CERTIFICATE----- MIIEKDCCApACCQDTo5idqFSRvTANBgkqhkiG9w0BAQsFADBWMQswCQYDVQQGEwJK UDEOMAwGA1UECAwFVG9reW8xEDAOBgNVBAcMB1NoaWJ1eWExEzARBgNVBAoMCk1J WEksIEluYy4xEDAOBgNVBAMMB21peGkuanAwHhcNMjMwNjAyMDYyMDE4WhcNMzMx MTAxMDYyMDE4WjBWMQswCQYDVQQGEwJKUDEOMAwGA1UECAwFVG9reW8xEDAOBgNV BAcMB1NoaWJ1eWExEzARBgNVBAoMCk1JWEksIEluYy4xEDAOBgNVBAMMB21peGku anAwggGiMA0GCSqGSIb3DQEBAQUAA4IBjwAwggGKAoIBgQDqAUBSR414H9uMS4ib uI5zOWzOwQ3yNSHUuoJ09/Vz63uCM9kZoyVGs+6m+rnQMWBHp6fcJz++VKA2AeBn z59Upf8yxrBicGT9qA6cOiscp4dbWPGzK9KD3UJCQV6DL7Q8DG+busVtFuAJY1kb NkPemYHcy9CdbwqOriVnp0cloyB8ItqWTRrfuiTuB4OfvesGUOL4/tJetpLgydlX mUYcJlYph7uG55rkyovqXmpt81v/cF08wkH8MOCuCg1D2hslEXeXYG1dEVstOLYi kEc4tlpo+LdfOPY2gnrmw4K52dTLsWrXhjYSDkezbiQN9CIj9/yXvkVETXXd8ILZ +qDnZIOi1VBx2Pi4p1OCoTXfr95z1G8XSvNwfiAWK3Hy589z5PCTA3G4tMOZ1Amy faLA0f2fARCU3vNiz3vsXjGvvHeibUbtVFKd5O5+Hh//yh3jOjX9irgflzPUBJUz GM8f8Eq6jsCOdqhG//cM26NfPj62Ce5qyAD32VVHH9iuGrMCAwEAATANBgkqhkiG 9w0BAQsFAAOCAYEAW1ezTxL2RQGvUJHnWXC72mr/7fDJ5fdDclBNn1X2b0V5uHI7 bAXO1MTkWcN++w20GfJ5oDvGLHOXBRoAU2ieHBeQZ9szrKs50iPL40Hz9YksI3hV 0aHMsgEowv5TNLaYFUjccAsXB1+EG+Iqg66yryRycFFm6BEM/7akl0jcULnINQf2 0scboWzfGYoQCe5foPKPUdek1U2Xt57xkazpRZZnh3pQ62hq1Gw55LT3kl+Lt/37 Zz1RjE1T9/nkkNgrFqRbOuGDyt/1Y6wxNxumfIGZiCaAxL+fDD0DWpSN4ty9D3tZ +tmuVMnr+qwEaJiR6s8DNLnUtEcDkNBqItxWhQZcagA1X0hnuBMlGBtrP7MIbRLS xmQQppFtHpt7QQzo2MjVpIq29j2CBbKGBxMIXTNIhfHXNraVC42SLp2C/2jFNCq1 ul42Q1wK8z4q3sh2vFzegjQxDq9luJf2Ke6GcFjvsPB+ophCGFkjA6vs6AWgOL2e JKLy8bBQIuQ7KBgt -----END CERTIFICATE----- EOD; } protected function fetch_private_cert(&$request) { return; } } //Build a request object from the current request $request = OAuthRequest::from_request(); $signature = $request->get_parameter('oauth_signature'); //Initialize the new signature method $signature_method = new MixiSignatureMethod(); //Check the request signature @$signature_valid = $signature_method->check_signature($request, null, null, $signature); if (!$signature_valid) { header('HTTP/1.0 400 Bad Request'); echo "This request was spoofed"; } else { echo "Success! The data was validated"; }
上記プログラムの動作には、OAuth.php が必要です。
2010年5月18日時点の最新バージョンである r1171 では署名の生成方法に問題がありますので、以下のように修正してご利用ください。
--- OAuth.php.org 2010-05-17 17:25:38.000000000 +0900 +++ OAuth.php 2010-05-17 17:29:12.000000000 +0900 @@ -276,7 +276,7 @@ // and add those overriding any duplicates from GET or POST if (@substr($request_headers['Authorization'], 0, 6) == "OAuth ") { $header_parameters = OAuthUtil::split_header( - $request_headers['Authorization'] + $request_headers['Authorization'], false ); $parameters = array_merge($parameters, $header_parameters); } @@ -857,7 +857,7 @@ if (is_array($value)) { // If two or more parameters share the same name, they are sorted by their value // Ref: Spec: 9.1.1 (1) - natsort($value); + sort($value, SORT_STRING); foreach ($value as $duplicate_value) { $pairs[] = $parameter . '=' . $duplicate_value; }