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"
}

最終更新日: 2023-02-03