メインコンテンツへスキップ
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 は、アクセス権を付与するサービス プリンシパルではなく、 自分自身のサインインを構成します。

付与ファイル

set は、サービス プリンシパルのすべての付与を --grants-file の内容で置き換え、ファイルに 含まれていないスタジオの権限やタイトルを削除します。
ファイルを一から作成するのではなく、現在の付与から始めてください。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 が失敗した場合、set が成功するまで、サービス プリンシパルがスタジオへのアクセス権を持たない可能性があり、 パイプラインが停止するおそれがあります。
失敗した場合、付与が変更されたかどうかは示されないため、古いバージョンで set を再実行しないでください。 get を実行して付与と Version を確認し、設定しようとした内容と異なる場合は、 その出力を編集して、その Version を --expected-version として指定して set に渡します。

例

スタジオのサービス プリンシパルを一覧表示し、そのうちの 1 つの付与を表示します。
サービス プリンシパルの付与を、get から保存して編集した grants.json の内容で 置き換えます。
サービス プリンシパルとその付与をスタジオから削除します。
revoke の後、そのスタジオでのサービス プリンシパルの次の PlayFab 要求は失敗します。revoke は、 サービス プリンシパルに既にアクセス権がない場合にも成功します。アクセス権を復元するには、完全な付与のセットを指定して set を実行します。
最終更新日 2026年11月19日