> ## 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` 命令系列為實驗性功能。其 CLI 介面可能會根據意見反應而變更或移除。

持續整合 (CI) 管線或其他無人值守的作業會以 Microsoft Entra ID 服務主體身分登入；請參閱[自動化 (服務主體) 驗證](https://docs.xbox.com/zh-TW/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` | 顯示一個服務主體的授與。 |
| `playfab service-principal set` | `/Studio/SetServicePrincipalAccess` | 視需要註冊服務主體，並**取代**其所有授與。 |
| `playfab service-principal revoke` | `/Studio/DeleteServicePrincipalAccess` | 從工作室移除服務主體及其所有授與。會先詢問；請參閱[安全性和破壞性作業](https://docs.xbox.com/zh-TW/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` 會傳回一頁：當還有更多項目時，回應的 `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`，然後將其傳遞給 `set`，並以其 `Version` 作為 `--expected-version`：

```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"] }
  ]
}
```

* 這兩個屬性都是必要的。空白清單表示不授與該類型的任何項目。
* 每個遊戲至少需要一個權限。若要移除某個遊戲的授與，請省略該遊戲。
* 屬性名稱不區分大小寫。無法辨識的屬性會視為錯誤，因此拼錯的 `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`，如果它們不是您想要設定的內容，請編輯該輸出，並將其傳遞給 `set`，以其 `Version` 作為 `--expected-version`。

## 範例

列出工作室的服務主體，並顯示其中一個的授與：

```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
```

以 `grants.json` (您從 `get` 儲存並編輯的檔案) 中的授與取代服務主體的授與：

```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/zh-TW/tools/xbox-cli/known-issues.md)
- [驗證](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/auth.md)
- [您的第一個試玩測試](https://docs.xbox.com/zh-TW/tools/xbox-cli/first-playtest.md)
- [內容](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/context.md)
- [組態](https://docs.xbox.com/zh-TW/tools/xbox-cli/configuration.md)
