Version: jp

コマンドラインインターフェース

CLI のダウンロードリンク#

ダウンロードリンクはダウンロードページに移動されました。

概要#

Unity Cloud コマンドラインインターフェース（CLI）（mmbeta）は、Multiplay マッチメイキングの管理と操作を支援するツールです。

このガイドでは、読者がマッチ関数の開発に精通していることを前提とし、CLI を通じてマッチ関数を実行する方法や、マッチメイキング設定を管理する方法を中心に説明します。マッチ関数の開発については、マッチメイキングハウツーを参照してください。

内部的に言うと、CLI では Multiplay マッチメイキングサービスによって提供される REST エンドポイントが使用されます。開発者は、REST インターフェースを直接使用することもできます。REST エンドポイントを直接呼び出す方法については、マッチメーカーベータ版 API 関連ドキュメントを参照してください。

Unity Cloud CLI のマッチ関数セクションは、matchmaking function サブコマンドを発行することでアクセスできます。

$ mmbeta matchmaking function

以下のセクションでは、使用可能な各コマンドの詳細について説明します。

設定の初期化#

マッチメイキングコマンドがヒットするすべてのエンドポイントにアクセスの承認が必要です。この承認は、特定のプロジェクト ID に対して行われます。したがって、認証を受けるにはプロジェクト ID を設定する必要があります。

ローカル設定を最も迅速に稼働させる方法は、プロジェクト ID を取得した後、次のコマンドを実行することです。

$ mmbeta config set -n project -v <my project uuid>

Config コマンド#

config コマンドは、ローカル設定ファイルの値を取得したり設定したりするために使用します。設定ファイルは、config コマンドの初回使用時に作成されます。config コマンドでサポートされる主要コマンドは get と set です。

config コマンドを呼び出すには、次のコードを使用します。

$ mmbeta config

使用可能なサブコマンドとサポートされる引数の説明を取得するには、--help を渡します。

Config get コマンド#

現在のローカル設定ファイルの値を表示するには、get コマンドを使用します。

たとえば、設定を名前別に表示するには次のコマンドを実行します。

$ mmbeta config get --name project

これを実行すると、プロジェクト ID（未設定の場合は空の文字列）が返されます。

サポートされる引数とサポートされる get のターゲット名の詳細なリストを取得するには、次の help コマンドを実行します。

$ mmbeta config get --help

Config set コマンド#

set コマンドは、ローカル設定ファイルの値を設定するのに使用します。

たとえば、project 設定の値を \<my project uuid\> に設定するには、次のコマンドを実行します。

$ mmbeta config set -n project -v <my project uuid>

承認#

CLI では、シングルサインオンフローを使用して、承認チェックとログインがオンデマンドで実行されます。プロジェクト ID を設定した後、認証を必要とする最初のコマンドが実行されると、Unity のウェブサイトにリダイレクトされ、ログインのプロンプトが表示されます。

マッチメイキングコマンド#

マッチメイキングコマンドは、マッチ設定および関数の作成、準備、更新、削除機能を使用するために使われます。

Matchmaking function コマンド#

matchmaking function コマンドは、マッチ関数のライフサイクルの作成と管理、およびデバッグに使用されます。

Matchmaking function delete コマンド#

matchmaking function delete コマンドを使用すると、アップロードされたマッチ関数を削除できます。削除が正常に完了すると、指定された名前を持つ実行中の関数が停止され、プロジェクトのデプロイから削除されます。また、関数アーカイブがクラウドストレージから削除されます。これには、すべてのログの削除が含まれます。

$ mmbeta matchmaking function delete testfunc1
deleted

マッチ関数とアーカイブファイルが削除されると、コマンドの応答として「deleted」というメッセージが返されます。

Matchmaking function get コマンド#

matchmaking function get コマンドを使用すると、展開されたマッチ関数の現在のステータスを取得できます。出力は、以下のプロパティを含む JSON オブジェクトです。

プロパティ	型	値
name	String	マッチ関数の名前
md5Hash	String	アップロードされたマッチ関数アーカイブの Base64 エンコードされた MD5 ハッシュ
created	String	マッチ関数アーカイブが RFC 3339 形式で作成（アップロード）された日時
updated	String	マッチ関数が RFC 3339 形式で最後にアップロード（置換）された日時
status	Object	マッチ関数と任意の実行中インスタンスの状態とステータス

status JSON オブジェクトには以下のプロパティが含まれます。

プロパティ	型	値
state	String	関数の現在の全体的な状態。次のいずれかのステートになります。 `Unknown`：内部エラー `NotRunning`：関数は展開されているが、現在実行中ではない `Pending`：関数は展開されており、開始プロセス中である `Running`：関数は展開されており、実行中である `Failed`：関数の展開が試行されて失敗したか、実行中に失敗し、再開できないエラーを示すステートの場合は、ログをダウンロードすることで詳細情報を確認できます（ログが利用可能な場合）。
instances	Array	関数の各実行中インスタンスの状態。この配列には、実行中のマッチ関数と同じ数の項目が含まれます。

instances 配列の各要素には、以下のプロパティを持つオブジェクトが含まれます。

プロパティ	型	値
state	String	関数インスタンスの現在の状態。これは全体的な関数ステータスの状態と似ています。各インスタンスの値は、次のいずれかのステートになります。 `Unknown`：内部エラー `Waiting`：インスタンスは展開または開始の処理中である `Running`：インスタンスは実行中である `Terminated`：インスタンスは展開されているが、終了されている（たとえば、更新バージョンの展開を準備している場合や、再起動を妨げるエラーが発生した場合など）。エラーを示すステートの場合は、ログをダウンロードすることで詳細情報を確認できます（ログが利用可能な場合）。
name	String	特定の関数インスタンスの名前。この名前はインスタンスごとに固有です。

state は全体的な状態を示す関数であり、他の状態にある特定のインスタンスを覆い隠す場合があります。少なくとも 1 つのインスタンスが実行中である場合、他のインスタンスが他の状態であっても、全体としての state は running になります。たとえば、実行中の関数 testfunc1 の場合、出力は次のコードスニペットのようになります。

$ mmbeta matchmaking function get testfunc1
{
    "name": "testfunc1",
    "md5Hash": "DG0UUW8fX/fwdaXW4MqedA==",
    "created": "2019-10-15T20:42:50.574+00:00",
    "updated": "2019-10-15T20:42:50.574+00:00",
    "status": {
        "state": "Running",
        "instances": [
            {
                "state": "Running",
                "name": "testfunc1-987fb8f97-lcbgp"
            },
            {
                "state": "Waiting",
                "name": "testfunc1-830ec7b0a-krvxs"
            }
        ]
    }
}

2 番目のインスタンスは Waiting ですが、少なくとも 1 つのインスタンスが Running であるため、全体的な状態は Running になります。優先順位は、Running、Pending、Failed、NotRunning、Unknown の順です。いずれかのインスタンスが達している最も顕著な状態によって、関数全体の状態が設定されます。たとえば、全体的な関数のステータスが Unknown になるのは、すべてのインスタンスが Unknown の場合だけです。

Matchmaking function list コマンド#

展開されたすべてのマッチ関数のステータスを取得するには、matchmaking function list コマンドを使用します。出力は、「functions」という関数ステータスの JSON 配列です。各オブジェクトは、get コマンドで使用されている構造体と一致します。これについては、Matchmaking function get コマンドのセクションで概説されています。たとえば、testfunc1 と testfunc2 という 2 つの実行中の関数がある場合、出力は次のコードスニペットのようになります。

$ mmbeta matchmaking function list
{
    "functions": [
        {
            "name": "testfunc1",
            "md5Hash": "DG0UUW8fX/fwdaXW4MqedA==",
            "created": "2019-10-15T20:42:50.574+00:00",
            "updated": "2019-10-15T20:42:50.574+00:00",
            "status": {
                "state": "Running",
                "instances": [
                    {
                        "state": "Running",
                        "name": "testfunc1-987fb8f97-lcbgp"
                    },
                    {
                        "state": "Waiting",
                        "name": "testfunc1-830ec7b0a-krvxs"
                    }
                ]
            }
        },
        {
            "name": "testfunc2",
            "md5Hash": "J4/3RR9OhwLz7PEOBNk5XQ==",
            "created": "2019-10-15T20:43:01.193+00:00",
            "updated": "2019-10-15T20:43:01.193+00:00",
            "status": {
                "state": "Running",
                "instances": [
                    {
                        "state": "Running",
                        "name": "testfunc2-576b47b6f9-q6dff"
                    }
                ]
            }
        }
    ]
}

Matchmaking function upload コマンド#

matchmaking function upload コマンドを使用すると、コンパイルされたマッチ関数とその関数を実行するために必要なその他すべてのアセンブリを含んだ .zip アーカイブをアップロードすることで、マッチ関数を作成または置換できます。

関数が新規の場合、その関数はターゲットプロジェクト ID で展開および開始されます。
既存の関数を置換する関数の場合、現在展開されている関数は停止され、アップロードされた関数バイナリで置換されます。

note

関数が置換されると、古いログにはアクセスできなくなります。置換関数をアップロードする前に、今後参照用に使う可能性がある過去のログをすべてダウンロードするようにしてください。

このユーザーガイドでは、マッチ関数の作成およびビルドのプロセスを詳細に説明しません。これ以降の手順では、関数がすでにビルドされ、関数アセンブリ（および関数を実行するために必要なすべてのアセンブリ）が単一フォルダー階層内で特定されていることを前提とします。マッチ関数の作成とビルドの詳細については、概要に記載されているドキュメントを参照してください。

マッチ関数アーカイブの作成#

現在、マッチ関数をアップロード用に準備するための自動パッケージ化ツールはありません。開発者は、マッチ関数を実行するために必要なすべてのデータを含んだ .zip アーカイブを作成する必要があります。

マッチ関数がビルドされた後、そのマッチ関数と、その他すべての依存アセンブリが配置されている出力フォルダーを特定します（たとえば、関数ディレクトリ下の bin/Debug/netcoreapp3.0 フォルダー）。.zip アーカイブには出力フォルダー全体と任意の数のサブフォルダーを含めることができますが、最小要件として、マッチ関数の実行に必要なすべてのアセンブリがマッチ関数自体と同じディレクトリに存在する必要があります。つまり、マッチ関数がアーカイブファイル内で複数のディレクトリの深さまでネストされていても、依存関係が同じディレクトリ内に存在していれば、その関数を検索して実行することができるということです。

.zip アーカイブは 50MiB 以下のサイズにする必要があります。生成されたアーカイブが 50MiB を超える場合は、不要なファイル（PDB やその他のデバッグファイル）を削除してください。一般に、必要なのは DLL ファイルだけです。その他のファイルは無視されます。

マッチ関数のアップロード#

マッチ関数を含んだ .zip アーカイブを作成したら、CLI を使用してそのマッチ関数をアップロードし、後でそれを識別するために使用される名前を付けます。この名前は、特定の IMatchFunction 実装に付けられた名前とは関係なく指定できます。また、この名前は、小文字、英数字、'-' または '.' から構成される RFC 1123 準拠の文字列とし、最初と最後の文字を英数字にする必要があります。検証に使用される正規表現は「[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*」です。

たとえば、IMatchFunction 実装「BestMatchFunction」の場合であれば、BestMatchFunction.zip というビルドフォルダーの .zip アーカイブを作成し、検証に合格する名前を付けます（たとえば、「bestfunction」）。その後、次のコードを使用して CLI から関数をアップロードし、展開します。

$ mmbeta matchmaking function upload bestfunction BestMatchFunction.zip
{
    "uri": "https://example.com/path/to/function/archive"
}

成功した場合、レスポンスは次の 1 つのプロパティを含む JSON オブジェクトになります。

プロパティ	型	値
uri	String	クラウドストレージからアップロードされたアーカイブファイルにアクセスするための URI

関数がアップロードされると、その関数はプロジェクトの実行中のマッチメーカーに自動的に展開されます。展開された関数のステータスを取得するには、matchmaking function get コマンドまたは matchmaking function list コマンドを使用します。

デフォルトでは、マッチ関数を展開すると、アーカイブ内に最初に見つかった IMatchFunction 実装が実行されます。アーカイブ内に複数の実装がある場合は、最初に見つかった実装が実行されます。検索順序は非決定的です。アーカイブ内に複数の IMatchFunction 実装が存在する場合は、オプションの --implementation フラグを使用して、使用する名前付きインスタンスを指定します。このシナリオでは、「BestMatchFunction」が IMatchFunction を実装するクラスの名前になります。

$ mmbeta matchmaking function upload bestfunction ManyFunctions.zip -i BestMatchFunction
{
    "uri": "https://example.com/path/to/function/archive"
}

Matchmaking function logs コマンド#

matchmaking function logs コマンドを使用すると、指定したマッチ関数によって生成されたログのユーザー定義部分を取り出すことができます。デフォルトでは、ログの最後の 30 分はマッチ関数の各実行中インスタンスから取り出されます。この時間範囲はコマンドラインで調整できます。

たとえば、「bestfunction」というマッチ関数の場合、次のコマンドを使用することで、ログの最後の 30 分を取り出すことができます。

$ mmbeta matchmaking logs --name bestfunction
{
    "logs": {
        "bestfunction-d6c7bd777-vbjff": "...",
        "bestfunction-b7420f454-veupd": "..."
    }
}

レスポンスは、指定した（またはデフォルトの）時間範囲に実行されていた関数の各インスタンスの raw ログを含んだ、「logs」という JSON オブジェクトです。最上位オブジェクトの形式は次のとおりです。

プロパティ	型	値
logs	Object	プロパティのリストで、各プロパティはマッチ関数インスタンスの名前とそのインスタンスのログです。

ログオブジェクトの内部のプロパティの形式は次のとおりです。

プロパティ	型	値
instance-name	String	ログ値の `string` を持つマッチ関数の特定のインスタンスの名前。

ログエントリにはシリアライズされた JSON オブジェクトが含まれることがありますが、形式は最終的に開発者が定義します。文字列には、タブや改行などの書式設定文字列を含めることもできます。

別の時間範囲を指定するには、--time パラメーターを使用して、何秒分のログを含めるかを指定します。時間は常に現在の時刻からさかのぼってカウントされるため、--time 60 を渡した場合は 1 分前から現在までのログが取得されます。たとえば、1 時間前からのログを取得するには、次のコマンドを使用します。

$ mmbeta matchmaking logs --name bestfunction --time 3600

ログのライフサイクル#

マッチ関数を削除すると、そのマッチ関数に関連付けられているログも削除されます。また、現在展開されているマッチ関数を更新されたバージョンで置換すると、前のバージョンのログが削除されます。delete または upload コマンドを発行する前に、必要なログをダウンロードしてください。

Matchmaking config コマンド#

matchmaking config コマンドは、マッチメイキング設定の CRUD 管理を実行するために使用します。

Matchmaking config upload コマンド#

matchmaking config upload コマンドは、ローカルファイルを設定ストアにアップロードするために使用します。このコマンドを呼び出すには、次のコードを使用します。

$ mmbeta matchmaking config upload --name "dm config prod" --path /localpath/matchConfig.json
Created config with id: 'dm config prod'

名前には、ファイルシステムのファイル名に使われるほとんどの文字を使用できます。

指定された名前の設定がすでに存在する場合は、その設定が更新されます。
指定された設定が存在しない場合は、新規に作成されます。

設定の検証時にエラーがある場合、エラーは次の構造体を持つ検証エラーメッセージの配列として表示されます。

$ mmbeta matchmaking config upload --name "dm config prod" --path /localpath/matchConfig.json
Error: modifying config: Config Validation failed:
[
  {
    "resultCode": "NullMatchGeneratorName",
    "message": "'Matchmaking.Name' a config name must be specified.",
    "detailLink": null
  }
]

note

mmbeta matchmaking config create --path /localpath/matchConfig.json コマンドは CLI から非推奨となりました。代わりに、upload コマンドを使用して名前を指定し、ランダムガイドが作成されないようにすることをお勧めします。互換性を確保するため、API では以前のバージョンの CLI が引き続きサポートされています。

Matchmaking config modify コマンド#

matchmaking config modify コマンドは、ローカルファイルを設定ストアにアップロードするために使用します。このプロセスでは、以前のバージョンのファイルが置き換えられます。なお、設定 ID が必須パラメーターであることに注意してください。

$ mmbeta matchmaking config modify --id <config guid>--path /localpath/matchConfig.json

検証エラーは JSON として返され、create コマンドと同じ構造体が使用されます。

Matchmaking config delete コマンド#

matchmaking config delete コマンドは、既存の設定を削除するために使用します。id 引数を指定する必要があることに注意してください。

$ mmbeta matchmaking config delete --id <config uuid>

Matchmaking config get コマンド#

matchmaking config get コマンドは、指定された ID に関連付けられた設定の JSON 本文を返します。

$ mmbeta matchmaking config get --id <config uuid>

Matchmaking config list コマンド#

matchmaking config list コマンドは、すべての設定を取得し、それらを JSON テキストとして返します。デフォルトでは、結果は設定名の昇順でソートされます。

$ mmbeta matchmaking config list

結果には JSON ディクショナリの形式が使用されます。各キーは設定名、値は有効な設定ファイル全体を表す JSON オブジェクトです。

{
    "<config 1 uuid>": {
        /*  config json */
    },
    "<config 2 uuid>": {
        /*  config json */
    },
    ...
}