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

# サービス プリンシパル

> Entra のサービス プリンシパルに対して、スタジオとそのタイトルへの PlayFab のアクセス権を付与、調査、取り消します。

`playfab service-principal` コマンド ファミリーは試験段階 (Experimental) です。CLI インターフェイスは、フィードバックに基づいて
変更または削除される可能性があります。

継続的インテグレーション (CI) パイプラインやその他の無人ジョブは、Microsoft
Entra ID のサービス プリンシパルとしてサインインします。
[自動化 (サービス プリンシパル) の認証](https://docs.xbox.com/ja-jp/tools/xbox-cli/authentication.md#automation-service-principal-authentication)を参照してください。
PlayFab は、ユーザーが PlayFab スタジオでサービス プリンシパルにアクセス権を付与した後でのみ、そのサービス プリンシパルを受け入れます。
これらのコマンドは、それらの付与を管理します。

これらのコマンドを実行できるのは、スタジオに対する **Admin** 権限を持つ、サインインしているユーザーのみです。
`XBOX_AUTHENTICATION__MODE` でサービス プリンシパル モードが選択されている場合は実行が拒否されるため、代わりに
`xbox auth login` でサインインしてください。

| コマンド | PlayFab API パス | 説明 |
| - | - | - |
| `playfab service-principal list` | `/Studio/ListServicePrincipals` | スタジオに登録されているサービス プリンシパルを一覧表示します。 |
| `playfab service-principal get` | `/Studio/GetServicePrincipalAccess` | 1 つのサービス プリンシパルの付与を表示します。 |
| `playfab service-principal set` | `/Studio/SetServicePrincipalAccess` | 必要に応じてサービス プリンシパルを登録し、そのすべての付与を**置き換え**ます。 |
| `playfab service-principal revoke` | `/Studio/DeleteServicePrincipalAccess` | サービス プリンシパルとそのすべての付与をスタジオから削除します。事前に確認を求めます。[安全性と破壊的な操作](https://docs.xbox.com/ja-jp/tools/xbox-cli/safety.md)を参照してください。 |

| コマンド | オプション |
| - | - |
| `service-principal list` | `--studio-id` (必須)、`--limit` (1 ～ 100)、`--continuation-token`。 |
| `service-principal get` | `--studio-id`、`--principal-tenant-id`、`--principal-object-id` (すべて必須)。 |
| `service-principal set` | `--studio-id`、`--principal-tenant-id`、`--principal-object-id`、`--display-name`、`--grants-file` (すべて必須)、`--expected-version`。 |
| `service-principal revoke` | `--studio-id`、`--principal-tenant-id`、`--principal-object-id` (すべて必須)。 |

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

## 付与ファイル

> [!WARNING]
>
> `set` は、サービス プリンシパルのすべての付与を `--grants-file` の内容で置き換え、ファイルに
> 含まれていないスタジオの権限やタイトルを削除します。

ファイルを一から作成するのではなく、現在の付与から始めてください。`get` の出力を保存し、
その `StudioPermissions` と `TitleGrants` を編集してから、その `Version` を `--expected-version` として指定して
`set` に渡します。

```bash theme={null}
xbox playfab service-principal get \
  --studio-id 1234567890ABCDEF \
  --principal-tenant-id 22222222-3333-4444-5555-666666666666 \
  --principal-object-id 33333333-4444-5555-6666-777777777777 \
  > grants.json
```

付与ファイルには、`get` の出力全体、その `data`、その中の `ServicePrincipal` オブジェクト、
または付与のみを指定できます。

```json theme={null}
{
  "StudioPermissions": [],
  "TitleGrants": [
    { "TitleId": "ABC123", "Permissions": ["Admin"] }
  ]
}
```

* 両方のプロパティが必須です。空のリストの場合、その種類の付与は行われません。
* 各タイトルには少なくとも 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` が失敗した場合

> [!WARNING]
>
> `set` が失敗した場合、`set` が成功するまで、サービス プリンシパルがスタジオへのアクセス権を持たない可能性があり、
> パイプラインが停止するおそれがあります。

失敗した場合、付与が変更されたかどうかは示されないため、古いバージョンで `set` を再実行しないでください。
`get` を実行して付与と `Version` を確認し、設定しようとした内容と異なる場合は、
その出力を編集して、その `Version` を `--expected-version` として指定して `set` に渡します。

## 例

スタジオのサービス プリンシパルを一覧表示し、そのうちの 1 つの付与を表示します。

```bash theme={null}
xbox playfab service-principal list \
  --studio-id 1234567890ABCDEF

xbox playfab service-principal get \
  --studio-id 1234567890ABCDEF \
  --principal-tenant-id 22222222-3333-4444-5555-666666666666 \
  --principal-object-id 33333333-4444-5555-6666-777777777777
```

サービス プリンシパルの付与を、`get` から保存して編集した `grants.json` の内容で
置き換えます。

```bash theme={null}
xbox playfab service-principal set \
  --studio-id 1234567890ABCDEF \
  --principal-tenant-id 22222222-3333-4444-5555-666666666666 \
  --principal-object-id 33333333-4444-5555-6666-777777777777 \
  --display-name "Nod Publishers build" \
  --grants-file grants.json \
  --expected-version 3
```

サービス プリンシパルとその付与をスタジオから削除します。

```bash theme={null}
xbox playfab service-principal revoke \
  --studio-id 1234567890ABCDEF \
  --principal-tenant-id 22222222-3333-4444-5555-666666666666 \
  --principal-object-id 33333333-4444-5555-6666-777777777777 \
  --confirm
```

`revoke` の後、そのスタジオでのサービス プリンシパルの次の PlayFab 要求は失敗します。`revoke` は、
サービス プリンシパルに既にアクセス権がない場合にも成功します。アクセス権を復元するには、完全な付与のセットを指定して
`set` を実行します。


## Related topics

- [既知の問題](https://docs.xbox.com/ja-jp/tools/xbox-cli/known-issues.md)
- [Auth](https://docs.xbox.com/ja-jp/tools/xbox-cli/commands/auth.md)
- [認証](https://docs.xbox.com/ja-jp/tools/xbox-cli/authentication.md)
- [最初のプレイテスト](https://docs.xbox.com/ja-jp/tools/xbox-cli/first-playtest.md)
- [コンテキスト](https://docs.xbox.com/ja-jp/tools/xbox-cli/commands/context.md)
