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

ゲームサーバーから API サーバーへのリクエスト

リクエスト形式​

API へのリクエストの仕方には Proxy モデルと Trusted モデルの二つがあります。

  Proxy モデル
    Gadgets Server により発行された opensocial_viewer_id に対応する access token を必要としたリクエスト

  Trusted モデル
    各アプリケーションごとにアクセス可能なリクエスト

これらのアクセス手段のサポート状況は各 API によって異なります。詳しくは API 各々のリファレンスをご参照下さい。

いずれのアクセス手段でも、API の Authorization には OAuth を用います。OAuth のリクエスト時に含める xoauth_requestor_id の値ですがモデル別に異なります。

モデルxoauth_requestor_id
ProxyGadgets Server から渡された opensocial_viewer_id の値
TrustedアプリケーションID

OAuth の署名生成については次のトピック「OAuth Signature の生成」をご参照下さい。

OAuth Signature の生成​

ゲームサーバから API サーバのリクエストでは、Authorization ヘッダにゲームサーバが生成した OAuth Signature を含めます。
この値をAPI サーバが検証する事で改ざん等の悪意あるリクエストを防ぎ、ゲームサーバからの正当なリクエストである事を確認します。

Base String の生成​

生成は以下の手順で行います。

  1. Base String 生成に必要な値を準備します。
項目説明
リクエストメソッドAPI サーバーに対してリクエストするHTTPメソッド
API URLAPI サーバーへのリクエストURL(クエリパラメータは含まない)
クエリパラメータAPI サーバーへのリクエストクエリパラメータ
パラメータ下記のパラメータを参照
パラメータ説明参照元
oauth_consumer_keyアプリケーション毎のキーアプリケーション登録時に発行
oauth_nonceリクエスト毎にユニークな値ゲームサーバーで生成
oauth_timestampUNIXタイムスタンプゲームサーバーで生成
oauth_tokenアクセストークンGadget サーバーからの Authorization リクエストヘッダの oauth_token の値
oauth_signature_method署名方式HMAC-SHA1固定
oauth_versionOAuthのバージョン1.0固定
xoauth_requestor_idアプリケーションを実行しているユーザIDGadget サーバーからのクエリパラメータ opensocial_viewer_id の値
  • Trusted モデル (OAuth Consumer Request) の場合は oauth_token をパラメータに含めません。
    • oauth_token が無い場合、OAuth Service Provider はそのリクエストを Consumer Request として解釈します
    • OAuth Consumer Request に関しての詳細な仕様は、OAuth Consumer Request 1.0 Draft 1 を参照して下さい。
  • Trusted モデルの際の xoauth_requestor_id はアプリケーション ID を指定します
  1. クエリパラメータとパラメータはキーと値を "=" で連結した上で、キーでアルファベット昇順でソートしたものを "&" で連結します。
  2. これらを URI エスケープして "&" で連結します。

Base String の生成例​

パラメータ値
リクエストメソッドGET
API URLhttp://app.example.com/?foo=bar
oauth_consumer_keyabcdefghij1234567890
oauth_nonceabcdefghij1234567890
oauth_timestamp1234567890
oauth_tokenabcdefghij1234567890
oauth_signature_methodHMAC-SHA1
oauth_version1.0
xoauth_requestor_id12345
GET&http%3A%2F%2Fapi.example.com%2F&
foo%3Dbar%26
oauth_consumer_key%3Dabcdefghij1234567890%26
oauth_nonce%3Dabcdefghij1234567890%26
oauth_signature_method%3DHMAC-SHA1%26
oauth_timestamp%3D1234567890%26
oauth_token%3Dabcdefghij1234567890%26
oauth_version%3D1.0%26
xoauth_requestor_id%3D12345

Signature の生成​

ベース文字列をアプリケーション時に発行された Consumer Secret と Authorization ヘッダの oauth_token_secret を "&" で連結した値をキーとして Authorization ヘッダの oauth_signature_method のアルゴリズム (現在はHMAC-SHA1固定です) でダイジェスト値を生成します。この値をさらに BASE64 エンコードすることによって Signature を生成することができます。

Authorization ヘッダの生成​

Authorizationヘッダに必要なパラメータは以下の通りです。

パラメータ
oauth_consumer_key
oauth_nonce
oauth_signature
oauth_signature_method
oauth_timestamp
oauth_token
oauth_version
xoauth_requestor_id
  1. パラメータのキーと値をURIエンコーディング。
  2. パラメータの値をダブルクォーテーション (") でくくる。
  3. パラメータのキーと値を "=" で連結。
  4. パラメータそれぞれをカンマ (,) で連結。
  5. オプションの realm パラメータを付加。

Authorization ヘッダの生成例​

OAuth realm="",
oauth_consumer_key="abcdefghij1234567890",
oauth_nonce="abcdefghij1234567890",
oauth_signature="X9KBpVUD0W17gNznsd568M9QPUI%3D",
oauth_signature_method="HMAC-SHA1",
oauth_timestamp="1234567890",
oauth_token="abcdefghij1234567890",
oauth_version="1.0",
xoauth_requestor_id="12345"

OAuth Request Body Hash (Optional)​

API サーバーへ POST/PUT リクエストを行う場合、Request Body に対して hash 値を計算し、その値を OAuth の署名計算に必要なキーとして加える事が出来ます。詳細な仕様に関しては OAuth Request Body Hash 1.0 Draft 4 を参照して下さい。

Request Body を検証に含める場合、Request Body 値の HASH 値を OAuth Signature の生成時と同じアルゴリズムで求め、その値をさらに base64 エンコードした値を oauth_body_hash パラメータに含めます。


参考資料​

OAuth Core 1.0 Revision A
OAuth Request Body Hash 1.0 Draft 4
OAuth Consumer Request 1.0 Draft 1

更新履歴​

  • 2013/03/15
    • ドキュメント移行