Skip to main content

VM 作成時にカスタム スクリプトを実行する - VmStartupScript (プレビュー)

はじめに

この機能はプレビューです。今日から使い始めてフィードバックをいただけます。私たちに連絡する方法については、記事の最後で説明します。プレビュー中はテクニカル サポートが限定的であることに注意してください。
VmStartupScript を使用すると、PlayFab Multiplayer Servers (MPS) で使用される仮想マシン (VM) 上でカスタム スクリプトを実行できます。MPS はゲーム サーバーのホスティング用に最適化されており、需要に応じて動的にタイトルをスケールすることを容易にします。VM の初期化中に多数のサーバーを素早くカスタマイズする容易性を向上させるため、カスタム スクリプトはゲーム サーバーをホストするすべての基盤 VM 上で実行できます。カスタム ソフトウェアのインストール、セキュリティ設定の変更、ゲーム サーバーの出力とメトリクスを記録するカスタム サービスの使用など、さまざまなタスクを実行できます。
これは高度な機能であり、細心の注意を払って使用する必要があります。実行中のスクリプトは、管理者 (root) 権限で仮想マシン (VM) レベルで実行されます。適切に使用しないと、実行中のゲーム サーバーの通常のフローが中断されたり、まったく実行されなくなる可能性があります。スクリプトの内容についてはエンド ユーザーが責任を負います。

VmStartupScript の使用方法

VmStartupScript 機能を使用するには、カスタム スクリプトと、インストール予定の関連するすべてのソフトウェア (任意) を用意する必要があります。スクリプトは、仮想マシンが初期化されると実行を開始します。この操作は、各 VM でゲーム サーバーが起動する前に発生します。スクリプトが正常に実行を終了すると、MPS サービスはゲーム サーバーの初期化を完了し、StandingBy 状態にします。ゲーム サーバーのさまざまな状態の詳細については、マルチプレイヤー サーバーのライフサイクル を参照してください。 この機能を実際の運用環境で使用するには、開始前に 推奨される開発者ワークフロー を参照してください。

スクリプトを作成する

  • Linux VM の場合は PF_StartupScript.sh、Windows VM の場合は PF_StartupScript.ps1 というファイルを作成します。
  • ファイルにセットアップ/実行コマンドを追加します。必要に応じて、スクリプトで使用できる一般的な 環境変数 をいくつか使用できます。一部のアクションはサポートされていないか、VM が正常に起動せず、意図しない課金が発生する可能性があります。詳細については、サポートされていない事項 セクションを参照してください。
スクリプトの例については、VmStartupScriptGallery を参照してください。

ZIP ファイルの作成とアップロード

  1. スクリプトが使用または呼び出す予定の関連ソフトウェアをすべてフォルダーに集めます。スクリプトがサード パーティ ソフトウェアをインストールする場合は、実行中にダウンロードするか、ZIP ファイルにバンドルできます。何もインストールしない場合は、この手順をスキップしてください。
  2. 前のセクションで作成したスクリプト (.sh または .ps1) と、必要な場合は前のステップで集めたソフトウェアを含む ZIP ファイル (.zip) を作成します。スクリプト ファイルは ZIP ファイルのルートに配置し、ディレクトリ内に置かないでください。また、スクリプト ファイルの名前が PF_StartupScript.sh (Linux) または PF_StartupScript.ps1 (Windows) でない場合、実行されずゲーム サーバーの起動に失敗します。
  3. 以下のいずれかの方法で ZIP ファイルをアップロードします。
スクリプトが必要とするすべてのバイナリとアセットを ZIP ファイルに含めることをお勧めします。これにより実行が速くなり、MPS がゲーム サーバーを提供するまでの時間が短縮されます。ゲーム サーバーが実行される関連プラットフォーム用のアセットを必ず含めてください。たとえば、Linux サーバーを使用する場合は、「amd64」の Debian/Ubuntu パッケージを含める必要があります。

新しいビルドにカスタム スクリプトを適用する

.zip ファイルをアップロードした後、VmStartupScriptAssetReference プロパティを構成した上で MPS API を使用して新しいビルドを作成します。手順については、MPS API を使用したビルドの作成方法 を参照してください。
  • アップロードされたアセット ファイルへの参照を含む VmStartupScriptConfiguration.VmStartupScriptAssetReference プロパティを追加します。このプロパティは、CreateBuildWithCustomContainerCreateBuildWithManagedContainerCreateBuildWithProcessBasedServer など、すべての「CreateBuild」関連 API の一部です。
  • VmStartupScriptAssetReference.FileName プロパティに有効な値を追加します。この値は、アセット ファイルの名前と同じでなければなりません (例: vmstartupscriptassets.zip)。
  • VmStartupScriptAssetReference.MountPath プロパティは空である必要があります。VmStartupScript 機能ではサポートされていないためです。
MountPath プロパティに値を設定すると、ビルドの作成操作は失敗します。
以下のコード例は、Linux Containers を使用したビルドを作成し、vmstartupscriptassets.zip 内のスクリプトを使用して VM をカスタマイズします。
VmStartupScript は VM の「Propping」ステージで実行され、ゲーム サーバーを起動するには正常に終了する必要があります。失敗した場合 (終了コードが 0 以外)、VM は「Running」状態に遷移せず、デバッグのために VM に RDP/SSH で接続する必要があります。詳細については、推奨される開発者ワークフロー を参照してください。VM は VmStartupScript の実行を再試行し続けます。

特別な考慮事項

Linux では、PF_StartupScript.sh ファイルを実行可能としてマークする必要がありますか?

MPS がスクリプト ファイルを実行する前に、実行可能としてマークし、Windows の行末 (“\r\n”) を Linux のもの (“\n”) に変換します。したがって、この 2 つについて心配する必要はありません。

環境変数

以下は、スタートアップ スクリプトで使用できる環境変数です。

サポートされていない事項

スクリプトからは以下のアクションを行うべきではありません。VM とゲーム サーバーのライフサイクルを中断する可能性が高くなります。
  • スタートアップ スクリプトの実行中にブロックしないでください。ゲーム サーバーを作成するには、スクリプトが正常に終了する必要があります。バックグラウンドで実行する必要がある場合は、Linux では systemd サービスとして、Windows では Windows サービスとしてインストールできます。
  • ポート 30000 以降はゲーム サーバー用に使用され、ポート 56001 は VmAgent プロセス (MPS ゲーム サーバー オーケストレーター実行可能ファイル) が使用しているため、これらのポートを使用しないでください。
  • D: (Windows) または /mnt (Linux) パス上のファイルは、VmAgent の動作に必要なため、変更しないでください (PF_SHARED_CONTENT_FOLDER_VM のような編集可能なコンテンツを含むフォルダーは除く)。
  • VmStartupScript 内、またはそれによって起動されるアプリから GSDK を使用しないでください。GSDK は GameServers からのみ使用する必要があります。
  • MPS Control Plane との通信に問題が発生するため、仮想マシンを手動で再起動しないでください。

ポート

VmStartupScript 機能を使用する場合、各 VM で公開するポートをいくつか要求することができます。これらのポートは、スクリプトによって起動される任意のプログラムで使用できます。MPS がゲーム サーバー用に開くポートとは異なります。

使用方法

VM ごとに最大 5 個のポートを要求できます。各ポートについて、プロトコル (TCP または UDP) と名前を指定する必要があります。2 つのポートを要求する方法の例を以下に示します。
ポートを要求した場合、ポートに関する情報を取得するのに役立つ以下の環境変数がスクリプトで使用できます。 たとえば、上記のサンプル スクリプトで要求された 2 つのポートの場合、VmStartupScript で以下の環境変数が見つかると期待できます。
ゲーム サーバー用に開かれるポートと同様に、ポートに接続するクライアントを認証するのはあなたの責任です。MPS はこれらのポートに対する認証機構を提供しません。
割り当てられるポートは 20000 番から始まることに気付くでしょう。ただし、この値は将来変更される可能性があるため、スクリプトにハードコードせず、常に環境変数を使用して適切なポート情報を取得することをお勧めします。

開発/デバッグ

VmStartupScript 機能を使用する前に、GitHub 上のオープン ソース リポジトリ (VmStartupScriptGallery) にあるこれらのサンプル スクリプトを確認することをお勧めします。コントリビューションを歓迎します!

推奨される開発ワークフロー

最初に、単一の VM でテスト ビルドを作成してください。この VM は、本番ビルドをデプロイする予定の VM と同じ仕様である必要があります。この単一の VM がデプロイされたら、RDP/SSH で接続し、必要なファイルをコピーして、スクリプトが成功するまで編集/実行を試みることができます。 この VM が起動し、スクリプトが期待どおりに動作することを確認したら、スクリプトとアセットを .zip ファイルに配置できます。その後、アップロードし、それを使用してビルドを作成してみることができます。コストを節約するため、再び単一 VM のビルドを作成してみて、スクリプトが動作することを確信したらスケールアップします。 スクリプトの実行に問題が発生した場合は、RDP/SSH で VM にログインし、スクリプトの標準出力と標準エラー ストリームを確認するために、PF_StartupScriptStdOut.txt および PF_StartupScriptStdErr.txt ファイルをチェックしてデバッグできます。これらのファイルは、Windows では D: ドライブに、Linux では /mnt に配置されています。 スクリプトは複数回実行される可能性があるため、冪等 (idempotent) である必要があります。たとえば、スクリプトが外部リソースをダウンロードしようとしてネットワークの問題で失敗した場合、MPS はスクリプト全体の実行を再試行します。

サポート

MPS サービスは、VmStartupScript にあるものは何でも実行します。ただし、スクリプトの一部としてインストール/実行される個々のアクションや実行可能ファイルに対するサポートは、チームからは提供されません。 プレビュー期間中、PlayFab Community ForumsDiscord を使用してサポートを受け、フィードバックを提供してください。VmStartupScriptGallery リポジトリのスクリプトに問題がある場合や、新しいスクリプトを要求したい場合は、GitHub で issue をオープン してください。
最終更新日 2026年8月25日