> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> PlayFab Multiplayer Servers の VM 作成時にカスタム スクリプトを実行する VmStartupScript プレビュー機能を使用して、エージェントのインストールやログのルーティングを可能にします。

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

## はじめに

<Info>
  この機能はプレビューです。今日から使い始めてフィードバックをいただけます。私たちに連絡する方法については、記事の最後で説明します。プレビュー中はテクニカル サポートが限定的であることに注意してください。
</Info>

VmStartupScript を使用すると、PlayFab Multiplayer Servers (MPS) で使用される仮想マシン (VM) 上でカスタム スクリプトを実行できます。MPS はゲーム サーバーのホスティング用に最適化されており、需要に応じて動的にタイトルをスケールすることを容易にします。VM の初期化中に多数のサーバーを素早くカスタマイズする容易性を向上させるため、カスタム スクリプトはゲーム サーバーをホストするすべての基盤 VM 上で実行できます。カスタム ソフトウェアのインストール、セキュリティ設定の変更、ゲーム サーバーの出力とメトリクスを記録するカスタム サービスの使用など、さまざまなタスクを実行できます。

<Note>
  これは高度な機能であり、細心の注意を払って使用する必要があります。実行中のスクリプトは、管理者 (root) 権限で仮想マシン (VM) レベルで実行されます。適切に使用しないと、実行中のゲーム サーバーの通常のフローが中断されたり、まったく実行されなくなる可能性があります。スクリプトの内容についてはエンド ユーザーが責任を負います。
</Note>

<iframe src="https://www.youtube.com/embed/oc-X7rHCwUU" width="100%" height="400" allowFullScreen frameBorder="0" />

## VmStartupScript の使用方法

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

この機能を実際の運用環境で使用するには、開始前に [推奨される開発者ワークフロー](#recommended-development-workflow) を参照してください。

### スクリプトを作成する

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

スクリプトの例については、[VmStartupScriptGallery](https://github.com/PlayFab/VmStartupScriptGallery) を参照してください。

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

1. スクリプトが使用または呼び出す予定の関連ソフトウェアをすべてフォルダーに集めます。スクリプトがサード パーティ ソフトウェアをインストールする場合は、実行中にダウンロードするか、ZIP ファイルにバンドルできます。何もインストールしない場合は、この手順をスキップしてください。
2. 前のセクションで作成したスクリプト (.sh または .ps1) と、必要な場合は前のステップで集めたソフトウェアを含む ZIP ファイル (.zip) を作成します。スクリプト ファイルは ZIP ファイルのルートに配置し、ディレクトリ内に置かないでください。また、スクリプト ファイルの名前が **PF\_StartupScript.sh** (Linux) または **PF\_StartupScript.ps1** (Windows) でない場合、実行されずゲーム サーバーの起動に失敗します。
3. 以下のいずれかの方法で ZIP ファイルをアップロードします。

* [PlayFab Game Manager](/services/playfab/multiplayer/servers/deploy-using-game-manager#assets-for-builds) を使用する
* [GetAssetUploadUrl API](https://learn.microsoft.com/en-us/rest/api/playfab/multiplayer/multiplayer-server/get-asset-upload-url) 呼び出しから返される URL に、ヘッダー \{"x-ms-blob-type": "BlockBlob"} を付けて PUT リクエストを発行する。
* [PowerShell コマンドレット](/services/playfab/multiplayer/servers/deploy-using-powershell-api#upload-an-asset) を使用する。

<Note>
  スクリプトが必要とするすべてのバイナリとアセットを ZIP ファイルに含めることをお勧めします。これにより実行が速くなり、MPS がゲーム サーバーを提供するまでの時間が短縮されます。ゲーム サーバーが実行される関連プラットフォーム用のアセットを必ず含めてください。たとえば、Linux サーバーを使用する場合は、「amd64」の Debian/Ubuntu パッケージを含める必要があります。
</Note>

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

.zip ファイルをアップロードした後、**VmStartupScriptAssetReference** プロパティを構成した上で MPS API を使用して新しいビルドを作成します。手順については、[MPS API を使用したビルドの作成方法](/services/playfab/multiplayer/servers/deploy-using-powershell-api) を参照してください。

* アップロードされたアセット ファイルへの参照を含む **VmStartupScriptConfiguration.VmStartupScriptAssetReference** プロパティを追加します。このプロパティは、[CreateBuildWithCustomContainer](https://learn.microsoft.com/en-us/rest/api/playfab/multiplayer/multiplayer-server/create-build-with-custom-container)、[CreateBuildWithManagedContainer](https://learn.microsoft.com/en-us/rest/api/playfab/multiplayer/multiplayer-server/create-build-with-managed-container)、[CreateBuildWithProcessBasedServer](https://learn.microsoft.com/en-us/rest/api/playfab/multiplayer/multiplayer-server/create-build-with-process-based-server) など、すべての「CreateBuild」関連 API の一部です。
* **VmStartupScriptAssetReference.FileName** プロパティに有効な値を追加します。この値は、アセット ファイルの名前と同じでなければなりません (例: **vmstartupscriptassets.zip**)。
* **VmStartupScriptAssetReference.MountPath** プロパティは空である必要があります。VmStartupScript 機能ではサポートされていないためです。

<Note>
  **MountPath** プロパティに値を設定すると、ビルドの作成操作は失敗します。
</Note>

以下のコード例は、Linux Containers を使用したビルドを作成し、**vmstartupscriptassets.zip** 内のスクリプトを使用して VM をカスタマイズします。

```csharp theme={null}
var request = new CreateBuildWithCustomContainerRequest()
{ 
    ContainerImageReference = new ContainerImageReference()
    {
         ImageName= "testimagename",
         Tag= "0.1"
    },
    ContainerFlavor = ContainerFlavor.CustomLinux,
    BuildName = "testbuildwithvmstartupscript",
    VmSize = AzureVmSize.Standard_D2as_v4,
    MultiplayerServerCountPerVm = 3,
    Ports= new List<Port>
    {
        new Port()
        {
            Name= "port",
            Num= 123,
            Protocol = ProtocolType.TCP   
        }
    },
    RegionConfigurations = new List<BuildRegionParams> { new BuildRegionParams()
    {
        Region = "EastUs",
        StandbyServers = 3,
        MaxServers = 6

    } 
    },
    VmStartupScriptConfiguration = new VmStartupScriptParams()
    {
        VmStartupScriptAssetReference = new AssetReferenceParams()
        {
            FileName = "vmstartupscriptassets.zip"
        }
    }
};
var result = await PlayFabMultiplayerAPI.CreateBuildWithCustomContainerAsync(request);
```

VmStartupScript は VM の「Propping」ステージで実行され、ゲーム サーバーを起動するには正常に終了する必要があります。失敗した場合 (終了コードが 0 以外)、VM は「Running」状態に遷移せず、デバッグのために VM に RDP/SSH で接続する必要があります。詳細については、[推奨される開発者ワークフロー](#recommended-development-workflow) を参照してください。VM は VmStartupScript の実行を再試行し続けます。

## 特別な考慮事項

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

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

### 環境変数

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

| 名前                              | 説明                          |
| ------------------------------- | --------------------------- |
| PF\_TITLE\_ID                   | PlayFab タイトル ID             |
| PF\_BUILD\_ID                   | PlayFab MPS ビルド ID          |
| PF\_VM\_ID                      | MPS 仮想マシン ID                |
| PF\_REGION                      | VM がホストされる Azure リージョン      |
| PF\_PUBLIC\_IPV4\_ADDRESS       | VM のパブリック IP アドレス           |
| PF\_FQDN                        | VM のパブリック IP に対応する完全修飾ドメイン名 |
| PF\_SHARED\_CONTENT\_FOLDER\_VM | VM 全体で共有されるコンテンツを含むフォルダー    |

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

スクリプトからは以下のアクションを行うべきではありません。VM とゲーム サーバーのライフサイクルを中断する可能性が高くなります。

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

## ポート

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

### 使用方法

VM ごとに最大 5 個のポートを要求できます。各ポートについて、プロトコル (TCP または UDP) と名前を指定する必要があります。2 つのポートを要求する方法の例を以下に示します。

```csharp theme={null}
VmStartupScriptConfiguration = new VmStartupScriptParams()
{
    VmStartupScriptAssetReference = new AssetReferenceParams()
    {
        FileName = "vmstartupscriptassets.zip"
    },
    PortRequests = new List<VmStartupScriptPortRequest>()
        {
            new VmStartupScriptPortRequest()
            {
                Name = "port0",
                Protocol = ProtocolType.TCP
            },
            new VmStartupScriptPortRequest()
            {
                Name = "port1",
                Protocol = ProtocolType.UDP
            }
        }
}
```

ポートを要求した場合、ポートに関する情報を取得するのに役立つ以下の環境変数がスクリプトで使用できます。

| 名前                                           | 説明                                                                              |
| -------------------------------------------- | ------------------------------------------------------------------------------- |
| PF\_STARTUP\_SCRIPT\_PORT\_COUNT             | VmStartupScript のポート数                                                           |
| PF\_STARTUP\_SCRIPT\_PORT\_NAME\_(index)     | リクエストで説明されているポート名                                                               |
| PF\_STARTUP\_SCRIPT\_PORT\_PROTOCOL\_(index) | リクエストで説明されているポートのプロトコル                                                          |
| PF\_STARTUP\_SCRIPT\_PORT\_INTERNAL\_(index) | プログラムが VM でバインドすべきポート                                                           |
| PF\_STARTUP\_SCRIPT\_PORT\_EXTERNAL\_(index) | 外部エンドポイントで開かれるポート。外部クライアントは、INTERNAL ポートにバインドしているプログラムに接続するためにこのポートを使用する必要があります |

たとえば、上記のサンプル スクリプトで要求された 2 つのポートの場合、VmStartupScript で以下の環境変数が見つかると期待できます。

```bash theme={null}
PF_STARTUP_SCRIPT_PORT_COUNT

PF_STARTUP_SCRIPT_PORT_INTERNAL_0
PF_STARTUP_SCRIPT_PORT_EXTERNAL_0
PF_STARTUP_SCRIPT_PORT_NAME_0
PF_STARTUP_SCRIPT_PORT_PROTOCOL_0

PF_STARTUP_SCRIPT_PORT_INTERNAL_1
PF_STARTUP_SCRIPT_PORT_EXTERNAL_1
PF_STARTUP_SCRIPT_PORT_NAME_1
PF_STARTUP_SCRIPT_PORT_PROTOCOL_1
```

<Info>
  ゲーム サーバー用に開かれるポートと同様に、ポートに接続するクライアントを認証するのはあなたの責任です。MPS はこれらのポートに対する認証機構を提供しません。
</Info>

<Note>
  割り当てられるポートは 20000 番から始まることに気付くでしょう。ただし、この値は将来変更される可能性があるため、スクリプトにハードコードせず、常に環境変数を使用して適切なポート情報を取得することをお勧めします。
</Note>

## 開発/デバッグ

VmStartupScript 機能を使用する前に、GitHub 上のオープン ソース リポジトリ ([VmStartupScriptGallery](https://github.com/PlayFab/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 Forums](https://community.playfab.com/) と [Discord](https://aka.ms/msftgamedevdiscord) を使用してサポートを受け、フィードバックを提供してください。VmStartupScriptGallery リポジトリのスクリプトに問題がある場合や、新しいスクリプトを要求したい場合は、GitHub で [issue をオープン](https://github.com/PlayFab/VmStartupScriptGallery/issues) してください。


## Related topics

- [シークレットの管理 (プレビュー)](/ja-jp/services/playfab/multiplayer/servers/manage-secrets.md)
- [スクリプト作成ツール](/ja-jp/tools/tools-console/wdp/script-authoring-tool.md)
- [タッチ操作プレビューのカスタマイズ](/ja-jp/build/core-features/common/game-streaming/tak-editor/game-streaming-tak-editor-customize-preview.md)
- [Azure Functions コンテキスト モデルを使用した PlayFab CloudScript](/ja-jp/services/playfab/live-service-management/service-gateway/automation/cloudscript-af/CloudScript-af-context.md)
- [プレイヤー カスタム プロパティによる高度なセグメント化](/ja-jp/services/playfab/live-service-management/game-configuration/segmentation/advanced-segmentation.md)