playfab service-principal コマンド ファミリーは試験段階 (Experimental) です。CLI インターフェイスは、フィードバックに基づいて
変更または削除される可能性があります。
継続的インテグレーション (CI) パイプラインやその他の無人ジョブは、Microsoft
Entra ID のサービス プリンシパルとしてサインインします。
自動化 (サービス プリンシパル) の認証を参照してください。
PlayFab は、ユーザーが PlayFab スタジオでサービス プリンシパルにアクセス権を付与した後でのみ、そのサービス プリンシパルを受け入れます。
これらのコマンドは、それらの付与を管理します。
これらのコマンドを実行できるのは、スタジオに対する Admin 権限を持つ、サインインしているユーザーのみです。
XBOX_AUTHENTICATION__MODE でサービス プリンシパル モードが選択されている場合は実行が拒否されるため、代わりに
xbox auth login でサインインしてください。
list は --output table を受け付けます。その他のコマンドは受け付けません。list は 1 ページを返します。
さらに結果がある場合は応答の ContinuationToken が設定され、その値を --continuation-token に設定して
list を再度実行すると、次のページを取得できます。
識別子
--studio-idは、付与を所有するスタジオを指定します。これらのコマンドは PlayFab タイトルを受け取らないため、--playfab-title-idと保存されたコンテキストは適用されません。--principal-tenant-idと--principal-object-idは、サービス プリンシパルを識別します。これらは、サービス プリンシパルの Entra ID テナントと、アプリの登録ではなくエンタープライズ アプリケーションのオブジェクト ID です。サービス プリンシパルとして サインインしている場合、xbox auth statusはこれをobjectIdとして報告します。- アプリケーション (クライアント) ID は渡しません。PlayFab はサービス プリンシパルの最初のトークンからこれを記録し、
listとgetはこれをClientIdとして報告します。 - グローバル オプションの
--tenant-idと--client-idは、アクセス権を付与するサービス プリンシパルではなく、 自分自身のサインインを構成します。
付与ファイル
ファイルを一から作成するのではなく、現在の付与から始めてください。get の出力を保存し、
その StudioPermissions と TitleGrants を編集してから、その Version を --expected-version として指定して
set に渡します。
get の出力全体、その data、その中の ServicePrincipal オブジェクト、
または付与のみを指定できます。
- 両方のプロパティが必須です。空のリストの場合、その種類の付与は行われません。
- 各タイトルには少なくとも 1 つの権限が必要です。タイトルの付与を削除するには、そのタイトルを省略します。
- プロパティ名の大文字と小文字は区別されません。認識されないプロパティはエラーになるため、
TitleGrantsのスペルを誤っても、すべてのタイトルの付与が削除されることはありません。 - ファイルの
TenantId、ObjectId、DisplayNameが存在する場合は、--principal-tenant-id、--principal-object-id、--display-nameと一致する必要があります。サービス プリンシパルの 名前を変更するには、ファイル内のDisplayNameも変更するか、削除します。
想定されるバージョン
サービス プリンシパルの付与を変更するたびに新しいVersion が割り当てられ、get と
set がこれを返します。--expected-version を指定すると、付与がまだそのバージョンである場合を除き、set は何も変更しません。
そのため、付与を読み取った後に他のユーザーが行った変更を元に戻してしまうことはありません。
--expected-version 0 は、サービス プリンシパルにまだアクセス権がないことを要求します。
--expected-version を指定しない場合、set は現在の状態にかかわらず付与を置き換えます。
付与ファイルに Version がある場合は、--expected-version が必須であり、その値と一致する必要があります。
一致しない場合は、get を再度実行し、その出力に対して編集をやり直してください。それでも付与を置き換えるには、
ファイルから Version を削除し、--expected-version を省略します。
set が失敗した場合
失敗した場合、付与が変更されたかどうかは示されないため、古いバージョンで set を再実行しないでください。
get を実行して付与と Version を確認し、設定しようとした内容と異なる場合は、
その出力を編集して、その Version を --expected-version として指定して set に渡します。
例
スタジオのサービス プリンシパルを一覧表示し、そのうちの 1 つの付与を表示します。get から保存して編集した grants.json の内容で
置き換えます。
revoke の後、そのスタジオでのサービス プリンシパルの次の PlayFab 要求は失敗します。revoke は、
サービス プリンシパルに既にアクセス権がない場合にも成功します。アクセス権を復元するには、完全な付与のセットを指定して
set を実行します。