tech.guitarrapc.cóm

Technical updates

Unity Cloud Build を API で操作しよう

Unity のビルドといえば、長らく Mac + Jenkins などのCIツールという印象でした。昨年、Unity Cloud Build の存在を知ってはいたものの、いまいちという印象で回避してきました。

改めて触ってみると git連携、ビルド状況の把握、ユーザーのダウンロードフロー、コントリビュートなど機能がそろっており、非常に使いやすいことがわかりまます。

今回は Unity Cloud Build を API経由で触ってみましょう。

なぜ API が必要なのか

Unityは Beta リリース や Patch リリースが頻繁で週1回のペースで更新されます。更に、対象プラットフォームに合わせて多くのビルド構成が必要になります。

特にアセットとしては様々な環境に対応するため、Unityバージョン × プラットフォーム 分だけビルドを回す必要があります。

手作業で、ビルドターゲットをポチポチ作るのは10個までは我慢できてもそれ以上はむりでしょう。そこで、API を使って自動構成、自動ビルド、任意のビルド、ChatOps を実現することで人間の生活を送れます。

API Document

Unity Cloud Build API は Swagger ベースになっています。

Unity Cloud Build API

Swagger は強力無比なAPI基盤です。ここから直接APIを叩くこともできますし curl の実行サンプル、レスポンスJSONサンプルまで表示されています。

Unity Cloud Build の API Document 最高ですね。Visual Studio Team Service もこれぐらいAPIをわかりやすく公開してほしいものです。

クライアント生成

API を叩くのにクライアント生成する時代は、Swagger によって劇的に変化します。

Swagger でAPIを構成すると、そのAPI構成が json で自動的に吐き出されます。

クライアント URL : https://build-api.cloud.unity3d.com/api/v1/api.json

利用者は、そのjson を Swagger のクライアントコード生成に投げつけることで、クライアントコードが自動生成されるのです。もはや書かなくていいに等しいぐらいい十分なものができます。

https://generator.swagger.io/

Generator ページのPOST /gen/clients/{language} に以下を入れることで クラインとコードが生成され、レスポンスの link からダウンロードできるようになります。

language:csharp
body:
{
  "spec": {},
  "options": {},
  "swaggerUrl": "https://build-api.cloud.unity3d.com/api/v1/api.json",
  "securityDefinition": {
    "description": "string",
    "type": "string"
  }
}

あとは、生成されたコードをソースに埋めて、生成コードが依存している次の NuGet Package をプロジェクトにいれるだけです。

Install-Package RestSharp
Install-Package Newtonsoft.Json
Base64Encode メソッドの追加

とはいえ、実はクライアントコード生成が腐っているため、Base64Encode() メソッドが存在しません。追加してあげましょう。

gist.github.com

static メソッドとして追加して、各クラスで using static してあげるのが素早く簡潔な対応です。

using System;
using System.IO;
using System.Collections.Generic;
using System.Collections.ObjectModel;
using System.Linq;
using RestSharp;
using UnityCloudBuildApi.IO.Swagger.Client;
using UnityCloudBuildApi.IO.Swagger.Model;
using static UnityCloudBuildApi.Encode;

namespace UnityCloudBuildApi.IO.Swagger.Api
{
    ....
}

これらの対応 + サンプルを足した UnityCloudbuildApi を GitHub で公開しています。

github.com

では、作成したクライアントコードを使って、API 経由で Unity Cloud Build を操作してみましょう。

事前準備

認証

API を叩くためには、Unity Cloud Build の認証を取る必要があります。

Unity Cloud Build のマイページにアクセスするとAPI Key を取得できます。

https://build.cloud.unity3d.com/login/me/

パス一覧

ドキュメントが Swagger とともに公開されているのでみてみるといいでしょう。

Unity Cloud Build

API 実行

サンプルプロジェクトをソリューションにいれておきました。

LinqPad で見てみましょう。

gist.github.com

config 生成

Api に仕込む認証を config にセットして使いまわします。併せて OrganizationId や 対象の既存プロジェクトId もあるなら用意してもいいでしょう。

gist.github.com

プロジェクト API

各Api処理がそれぞれ用意されています。ProjectsApi(config) から、プロジェクトに関するApiが自在に叩けます。

gist.github.com

プロジェクト追加は、GUI の追加処理とほぼ同じです。直感的に扱えるので困ることもないでしょう。

ビルドターゲット API

ビルドターゲット、つまりターゲットプラットフォームやUnityバージョンの組み合わせです。最も増えるのでAPIで操作したい候補ですね。

gist.github.com

ビルド API

ビルドを実行したりするにはこの API を使います。ビルド状態の取得から、開始、停止まで自由に行えるので非常にいい感じです。

gist.github.com

まとめ

その他にも User や Organization、Billing、Config のAPIもありますが紹介はここまでにします。

Unity のビルド環境をクラウドサービスでできることは、とてもメリットが大きいのでぜひぜひ Unity Cloud Build に期待したいですね!

iOS などのスマホから、ビルド結果を直接インストールするのも容易です。最高ですね!