RESTful API 概要¶
Avatar Play の RESTful API は、自社アプリのサーバサイド(以下、自社サーバ)から呼び出せる機能を提供します。
主な機能¶
RESTful API が提供する主な機能は次のとおりです。詳しくはリファレンスを参照してください。
- アバターを作成するAPI
- アバターの基本情報(アバター画像URLなど)を取得するAPI
- 着せ替えアプリと接続するためのAPI
- アイテムを付与するためのAPI
- UI Kit のショップ/ガチャを利用するためのAPI
認証の設定方法¶
RESTful API へは、JSON Web Tokens(以下、JWT)を使った安全で標準的な方法でアクセスできます。Google Cloud の認証基盤を採用しており、Google Cloud が提供するAPI キーとサービス アカウントが必要となります。
Info
API キーとサービス アカウントは、アプリケーションを識別するために利用されます。
事前準備¶
- まだ作成していない場合、Google Cloud プロジェクトを作成します。API キーとサービス アカウントのみの利用の場合、課金の設定は不要です。
- RESTful API へのアクセス権持つユーザーが所属するGoogleグループを作成し、グループのメールアドレスを Avatar Play 担当者へ伝えます。
DeNA側のセットアップが完了すると、次のステップに進めます。
RESTful API の有効化¶
Google Cloud プロジェクト内で、Avatar Play の RESTful API を有効化します。
- Google Cloud コンソールの「API とサービス」より、「API と サービスを有効化」リンクをクリックし、API ライブラリを開きます。
- キーワード「avatarplay」で検索し、「avatarplay Avatar Play API」を選択します。表示されない場合、DeNA側のセットアップが完了していない可能性があります。
- 提供元が
dena.jp
であることを確認し、APIを有効化します。
API キーの作成¶
次に、自社アプリに紐づく API キーを作成します。Google Cloud コンソールの「API とサービス > 認証情報」より、API キーを作成できます。「API の制限」より、用途を「avatarplay Avatar Play API」のみに制限しておくことを推奨します。
API キーは Avatar Play がアプリを特定するために用いられるため、アプリを跨って利用できません。開発環境、本番環境のアプリが存在する場合、それぞれ異なるAPI キーを作成します。
Info
API キーは後述のサービス アカウントキーほど厳重に管理する必要はありません。
JWT 認証¶
API を本番サービスで利用する場合は、JWT 認証を利用してください。検証目的での利用であれば、API キーのみでアクセスすることも可能です。その場合、 本項は読み飛ばしてください。
サービス アカウントの作成¶
次に、自社アプリに紐づくサービス アカウントを作成します。Google Cloud コンソールの「IAM と管理 > サービス アカウント」よりサービス アカウントを作成できます。権限の追加は必要ありません。
後述するサービス アカウントキーは漏洩しないよう厳重に管理する必要があるため、サービス アカウントも開発環境、本番環境でそれぞれ異なるものを作成することを推奨します。
サービス アカウントキーの作成¶
認証に必要なJWTを生成するためには、サービス アカウントキーが必要です。Google Cloud コンソールの「IAM と管理 > サービス アカウント」より、サービス アカウントキーを作成できます。サービス アカウントキーは安全な経路で自社サーバが参照できる場所に配置します。
Warning
サービス アカウントキーが漏洩すると、API へ不正にアクセスできてしまいます。サービス アカウントキーは DeNA 側に共有されないため、パートナーデベロッパー様側で管理するものとなります。
Avatar Play コンソールでアプリに紐付ける¶
Avatar Play コンソールのアプリ一覧より、アプリの設定画面まで進み、画面下の「RESTful API 向けの設定」の項目から暗号化した API キーと、JWT 認証を有効化するにはサービス アカウントのメールアドレスを登録します。
API キーの値はSHA256でハッシュ化した文字列を指定します。
# Macでのコマンド例
$ echo -n {API キー} | shasum -a 256
854834d71cfb50b614d34863a601fc22375c0c39b477bbb83e63105f1863280a -
サービス アカウントを登録した場合、API を利用できるようになるまでに数日かかることがあります。進捗状況は Avatar Play 担当者にご確認ください。API キーのみを登録した場合は、直ちに API を利用できます。
RESTful API へのアクセス¶
API キーのみの場合¶
API のホストは api-ko.avatarplay3d.com
になります。以下のようにレスポンスが返れば成功です。
$ curl "https://api-ko.avatarplay3d.com/v1/Echo?key={API キー}&message=hello"
{
"message": "hello"
}
JWT 認証を利用する場合¶
自社サーバのプログラムから、サービス アカウントキー使ってJWTを生成します。これはJWTを使った一般的な認証実装になります。パラメータ aud
には、Avatar Play が発行したアプリIDを指定します。
// Go言語での実装例
now := time.Now().Unix()
jwt := &jws.ClaimSet{
Iat: now,
Exp: now + 60*60, // 有効期限を1時間とする場合
Iss: "{サービス アカウントのメールアドレス}",
Aud: "{アプリID}",
Sub: "{サービス アカウントのメールアドレス}",
PrivateClaims: map[string]interface{}{
"email": "{サービス アカウントのメールアドレス}",
}
}
jwsHeader := &jws.Header{
Algorithm: "RS256",
Typ: "JWT",
}
// サービス アカウントキーファイルの読み込み
keyBody, err := os.ReadFile("{サービス アカウントキーのファイルパス}")
if err != nil {
http.Error(w, "failed to read key file", http.StatusInternalServerError)
return
}
conf, err := google.JWTConfigFromJSON(keyBody)
if err != nil {
http.Error(w, "failed to read key body", http.StatusInternalServerError)
return
}
// 秘密鍵のパース
block, _ := pem.Decode(conf.PrivateKey)
parsedKey, err := x509.ParsePKCS8PrivateKey(block.Bytes)
if err != nil {
http.Error(w, "failed to parse key", http.StatusInternalServerError)
return
}
rsaKey, _ := parsedKey.(*rsa.PrivateKey)
// JWTトークンの生成
jwtToken, err := jws.Encode(jwsHeader, jwt, rsaKey)
if err != nil {
http.Error(w, "failed to encode key", http.StatusInternalServerError)
return
}
// jwtToken の値を Authorization ヘッダに指定
JWTの実装例は Google Cloud のドキュメント「認証されたリクエストを送信する」なども参照してください。
API のホストは api.avatarplay3d.com
になります。生成したJWTを Authorization
ヘッダに設定して RESTful API へアクセスします。以下のようにレスポンスが返れば成功です。
$ curl "https://api.avatarplay3d.com/v1/Echo?key={API キー}&message=hello" -H "Authorization: Bearer {JWT}"
{
"message": "hello"
}