ゲームサーバーから 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

Proxy

Gadgets Server から渡された opensocial_viewer_id の値

Trusted

アプリケーションID

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

OAuth Signature の生成

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

Base String の生成

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

1.Base String 生成に必要な値を準備します。

項目

説明

リクエストメソッド

API サーバーに対してリクエストするHTTPメソッド

API URL

API サーバーへのリクエストURL(クエリパラメータは含まない)

クエリパラメータ

API サーバーへのリクエストクエリパラメータ

パラメータ

下記のパラメータを参照

パラメータ

説明

参照元

oauth_consumer_key

アプリケーション毎のキー

アプリケーション登録時に発行

oauth_nonce

リクエスト毎にユニークな値

ゲームサーバーで生成

oauth_timestamp

UNIXタイムスタンプ

ゲームサーバーで生成

oauth_token

アクセストークン

Gadget サーバーからの Authorization リクエストヘッダの oauth_token の値

oauth_signature_method

署名方式

HMAC-SHA1固定

oauth_version

OAuthのバージョン

1.0固定

xoauth_requestor_id

アプリケーションを実行しているユーザID

Gadget サーバーからのクエリパラメータ 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 を指定します

2.クエリパラメータとパラメータはキーと値を "=" で連結した上で、キーでアルファベット昇順でソートしたものを "&" で連結します。

3.これらを URI エスケープして "&" で連結します。

Base String の生成例

パラメータ

リクエストメソッド

GET

API URL

http://app.example.com?foo=bar

oauth_consumer_key

abcdefghij1234567890

oauth_nonce

abcdefghij1234567890

oauth_timestamp

1234567890

oauth_token

abcdefghij1234567890

oauth_signature_method

HMAC-SHA1

oauth_version

1.0

xoauth_requestor_id

12345

GET&http%3A%2F%2Fapi.example.com&
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 パラメータに含めます。

参考資料

The OAuth Core 1.0 Protocol draft-hammer-oauth-10
OAuth Core 1.0 Revision A
OAuth Request Body Hash 1.0 Draft 4
OAuth Consumer Request 1.0 Draft 1
RESTful Protocol Specification v0.9

更新履歴

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

PREVIOUS

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

NEXT

API サーバーからゲームサーバーへのレスポンス