コンテンツにスキップ

RESTful API 概要

Avatar Play の RESTful API は、自社アプリのサーバサイド(以下、自社サーバ)から呼び出せる機能を提供します。

Info

本機能はβ版のため、将来仕様が変更する可能性があります。

主な機能

RESTful API が提供する主な機能は次のとおりです。詳しくはリファレンスを参照してください。

  • アバターを作成するAPI
  • アバターの基本情報(アバター画像URLなど)を取得するAPI
  • 着せ替えアプリと接続するためのAPI
  • アイテムを付与するためのAPI
  • UI Kit のショップ/ガチャを利用するためのAPI

認証の設定方法

RESTful API へは、JSON Web Tokens(以下、JWT)を使った安全で標準的な方法でアクセスできます。Google Cloud の認証基盤を採用しており、Google Cloud が提供するAPI キーサービス アカウントが必要となります。

Info

API キーとサービス アカウントは、アプリケーションを識別するために利用されます。

事前準備

  1. まだ作成していない場合、Google Cloud プロジェクトを作成します。API キーとサービス アカウントのみの利用の場合、課金の設定は不要です。
  2. RESTful API へのアクセス権持つユーザーが所属するGoogleグループを作成し、グループのメールアドレスを Avatar Play 担当者へ伝えます。

DeNA側のセットアップが完了すると、次のステップに進めます。

RESTful API の有効化

Google Cloud プロジェクト内で、Avatar Play の RESTful API を有効化します。

  1. Google Cloud コンソールの「API とサービス」より、「API と サービスを有効化」リンクをクリックし、API ライブラリを開きます。
  2. キーワード「avatarplay」で検索し、「avatarplay Avatar Play API」を選択します。表示されない場合、DeNA側のセットアップが完了していない可能性があります。
  3. 提供元が dena.jp であることを確認し、APIを有効化します。

API キーの作成

次に、自社アプリに紐づく API キーを作成します。Google Cloud コンソールの「API とサービス > 認証情報」より、API キーを作成できます。「API の制限」より、用途を「avatarplay Avatar Play API」のみに制限しておくことを推奨します。

API キーは Avatar Play がアプリを特定するために用いられるため、アプリを跨って利用できません。開発環境、本番環境のアプリが存在する場合、それぞれ異なるAPI キーを作成します。

Info

API キーは後述のサービス アカウントキーほど厳重に管理する必要はありません。

サービス アカウントの作成

次に、自社アプリに紐づくサービス アカウントを作成します。Google Cloud コンソールの「IAM と管理 > サービス アカウント」よりサービス アカウントを作成できます。権限の追加は必要ありません。

後述するサービス アカウントキーは漏洩しないよう厳重に管理する必要があるため、サービス アカウントも開発環境、本番環境でそれぞれ異なるものを作成することを推奨します。

Avatar Play コンソールでアプリに紐付ける

Avatar Play コンソールのアプリ一覧より、アプリの設定画面まで進み、画面下の「RESTful API 向けの設定」の項目から暗号化した API キーとサービス アカウントのメールアドレスを登録します。

API キーの値はSHA256でハッシュ化した文字列を指定します。

# Macでのコマンド例
$ echo -n {API キー} | shasum -a 256
854834d71cfb50b614d34863a601fc22375c0c39b477bbb83e63105f1863280a  -

紐付けが設定されてから、RESTful API で利用できるようになるまでに数日かかることがあります。進捗状況は Avatar Play 担当者にご確認ください。DeNA側のセットアップが完了すると、次のステップに進めます。

サービス アカウントキーの作成

認証に必要なJWTを生成するためには、サービス アカウントキーが必要です。Google Cloud コンソールの「IAM と管理 > サービス アカウント」より、サービス アカウントキーを作成できます。サービス アカウントキーは安全な経路で自社サーバが参照できる場所に配置します。

Warning

サービス アカウントキーが漏洩すると、API へ不正にアクセスできてしまいます。サービス アカウントキーは DeNA 側に共有されないため、パートナーデベロッパー様側で管理するものとなります。

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 := ioutil.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 のドキュメント「認証されたリクエストを送信する」なども参照してください。

RESTful API へのアクセス

生成したJWTを Authorization ヘッダに設定して RESTful API へアクセスします。

以下のようにレスポンスが返れば成功です。

$ curl "https://api.avatarplay3d.com/v1/Echo?key={API キー}&message=hello" -H "Authorization: Bearer {JWT}"
{
 "message": "hello"
}


最終更新日: 2021-02-16