プラグインのアップロードガイド

このガイドは、独自のサーバープラグインを作成しているPhoton Enterprise Cloudのユーザーのみに関連する内容です。アップロードスクリプトと顧客の資格情報は必要に応じてEnterprise Cloudの顧客と個人ごとに共有します。

概念

Enterpriseの顧客は、プライベートPhoton Cloudにカスタムプラグインをアップロードすることができます。
各プラグインのアセンブリは、名前、バージョン、および顧客IDによって識別されます。
また、プラグインをアップロードする際の認証用にキーが必要です。
同じプラグインアセンブリの複数のバージョンを並行して使用することができます。
特定のバージョンのアップロードが終了した後、ユーザーはダッシュボードからそのバージョンを使用するようにアプリケーションを設定することができます。

ワークフロー

前提条件

必要となる顧客データ

アップロードのプロセスを説明するため、このセクションでは以下の値を使用します：

顧客: "SampleCustomer"
キー: "MyKey"
プラグイン: "MyPlugin"

プラグインファイル

プラグインコードをコンパイルします。出力は「bin」フォルダ（サブフォルダではありません）に設置する必要があります。「bin」フォルダを.zipファイルに追加してください：

MyPlugin.zip
    - /bin
        – MyPlugin.dll
        – PhotonHivePlugin.dll
        – *.dll

PowerShellを準備

最低限必要となるPowerShellのバージョンは3.0 (Windows Management Framework 3)です。

プラグインアップロードzipファイルをダウンロードします。Photon.PrivateCloud.Plugin.Client.SAS.zipファイルを右クリックし、"Unblock" ボタンを選択し、中身を解凍します。
アップロードスクリプトを実行しているマシンの日時を同期するよう、確認してください。同期されていない場合には、動作しない可能性があります。
新たなPowerShellウィンドウを開きます。プラグインアップロード用に新たなPowerShellセッションを開始することを推奨します。
デフォルトのWindows PowerShell 「Restricted」実行ポリシーがある場合には、変更する必要があります。
Set-ExecutionPolicy RemoteSignedを使用して「RemoteSigned」に設定することを推奨します。最新の実行ポリシーを取得するには、 Get-ExecutionPolicyを使用してください。
Microsoft TechNetの「Running Scripts」で、詳細を確認してください。
以下のように、スクリプト「Photon.PrivateCloud.Plugin.Client.SAS.psm1」から必要なモジュールをインポートします：

Import-Module .\Photon.PrivateCloud.Plugin.Client.SAS.psm1

モジュールにインポートされた利用可能なコマンドは、以下を使用してリスト化されます：

Get-Module Photon.PrivateCloud.Plugin.Client.SAS | Select-Object -ExpandProperty ExportedCommands

コマンドについてのヘルプを参照するには、上記のリストから利用可能なコマンド名でGet-Helpを使用します。

Add-PhotonPluginのヘルプを参照する場合の例:

Get-Help Add-PhotonPlugin -Detailed

アップロード

プラグインをアップロードするには、「Add-PhotonPlugin」コマンドを使用します：

Add-PhotonPlugin -Customer SampleCustomer -Plugin MyPlugin -File C:\MyPath\MyPlugin.zip -Key MyKey

アップロードスクリプトは、自動インクリメントされたバージョン番号を割り当てます。
成功した場合には、割り当てられたバージョン番号が返されます。

正常なアップロード後の出力例：

MD5 : 036eb2b33cbfbebdd5bf31474fbf53e4
Name : SampleCustomer/MyPlugin/1/MyPlugin.zip
LastModified : 3/25/16 7:49:58 PM +00:00
Length : 222222
Customer : SampleCustomer
Plugin : MyPlugin
Version : 1

検証

アップロードが終了したら、プラグインはプライベートPhoton Cloudサーバーに展開されます。
特定バージョンの展開の状況を確認するには、以下を参照してください：

Get-PhotonPluginStatus -Customer SampleCustomer -Plugin MyPlugin -Key MyKey -Version 1

利用可能なサーバー数と、完了したサーバー数が一致している場合には、プラグインはすぐに利用できる状態です。

以下のコマンドを使用して、アカウントで利用可能な（アップロードされた）すべてのプラグインを確認することができます：

Get-PhotonPluginList -Customer SampleCustomer [-Plugin MyPlugin] -Key MyKey

「プラグイン」パラメータの使用は任意です。
このパラメータを使用すれば、1つのプラグインアセンブリの名前を指定するだけですべてのバージョンを確認できます。

設定

ダッシュボードに進み、新しいバージョンを使用するためプラグインを設定します。
バージョン文字列は、スクリプトの「Version」文字列と完全に一致しなければなりません。
Enterprise Cloudのプラグイン設定の詳細は、プラグインマニュアルで参照してください。

設定値の例:

AssemblyName = "MyPlugin.dll" (Plugins SDKと同様)
Type = "MyPlugin.PluginFactory" (Plugins SDKと同様)
Path = "SampleCustomer\MyPlugin"
Version = "Version" (アップロードスクリプトからの文字列)
[CustomKey1] = [CustomValue1]
...

古いプラグインバージョンを削除

多くのバージョンのプラグインをアップロードした場合には、今後使用しない古いバージョンを削除してください。
削除しない場合には、弊社はEnterprise Cloudに新しいサーバーを追加していますので、負荷が高くなります。結果的に新しいサーバーへの古いプラグインファイルの同期によって、処理に必要以上に時間を要する可能性があります。

これはプラグインの古いバージョンで使用するためのものです。新しいバージョンで利用するものではありません。
Enterprise Cloudサーバー上のプラグインは削除されず、サーバーと同期されているストレージからのみ削除されます。

この機能の背後にある考え方は次のとおりです。
ゲームが本番環境で実行されている場合、運用チームまたは自動スケール機能は、必要に応じてサーバーをいつでも追加/削除することができます。
サーバーを追加するたびに、すべての「legit」/「有効」（過去に削除されていない）プラグインバージョンがそのサーバーに同期されます。
長い開発プロセスの後、何百ものプラグインバージョンが存在する可能性があります。サーバーが追加されるたびに、それらのすべてのファイルを同期するのに時間がかかる場合があります。そのため、定期的にクリーンアップを行い、古いバージョンを削除することをお勧めします。

以下の例では、プラグインバージョン1を42によって削除する方法を示します：

Remove-PhotonPluginRange -Customer SampleCustomer -Plugin MyPlugin -Range 1,42 -Key MyKey -File MyPlugin.zip

推奨事項

バージョニング

現在、Photonのプラグインはサイド・バイ・サイドのアセンブリバージョニングのみをサポートしています：AppIDごとに1つのプラグインDLLバージョンです。

新しいプラグインバージョンを展開するには、以下の2つの方法を推奨します：

A. 「互換性のある」プラグインの展開：新たなクライアントバージョンは不要です。

新しいバージョンのプラグインアセンブリをアップロードします。
AppIDをステージングする際：新たなバージョンが予期されたとおりに動作している点を確認してください（推奨）。
新たなプラグインアセンブリバージョンを使用するため、本番のAppID設定を更新します。

B. 「互換性のない」プラグインの展開：新たなクライアントバージョンが必要です。

プラグインアセンブリの新たなバージョンをアップロードします。
新たな本番のAppIDを設定します。
新たなプラグインアセンブリバージョンを使用するため、新たな本番のAppIDを設定します。

静的フィールド

ルーム間やアプリケーション間で、同じプラグインが共有されます。
同じプラグインクラスの静的フィールドも、同様に共有されます。
静的フィールドの使用を回避できない場合、2つのアプリケーションで同じプラグインアセンブリの使用を回避するための方法は以下のとおりです：

異なる2つのプラグイン名の下に、同じプラグインファイルをアップロードします：

a- 名前Xでプラグインアーカイブをアップロード
b- 名前Yでプラグインアーカイブをアップロード
2つのアプリケーションに、「Path」以外は同じ設定を適用：

a- プラグインXを使用するようアプリAを設定："{customerName}\X"
b- プラグインYを使用するようアプリBを設定："{customerName}\X"

概念
ワークフロー

前提条件
アップロード
検証
設定
古いプラグインバージョンを削除
推奨事項