跳轉到主要內容
playfab service-principal 命令系列為實驗性功能。其 CLI 介面可能會根據意見反應而變更或移除。 持續整合 (CI) 管線或其他無人值守的作業會以 Microsoft Entra ID 服務主體身分登入;請參閱自動化 (服務主體) 驗證。只有在有人於 PlayFab 工作室中授與服務主體存取權之後,PlayFab 才會接受該服務主體。這些命令可管理這些授與。 只有已登入且具備工作室 Admin 權限的人員才能執行這些命令。當 XBOX_AUTHENTICATION__MODE 選取服務主體模式時,這些命令會拒絕執行,因此請改用 xbox auth login 登入。 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 選項會設定您自己的登入,而不是您要授與存取權的服務主體。

授與檔案

set 會以 --grants-file 的內容取代服務主體的所有授與,並移除檔案中未包含的任何工作室權限或遊戲。
請從目前的授與開始,而不是從頭撰寫檔案。儲存 get 的輸出、編輯其 StudioPermissions 和 TitleGrants,然後將其傳遞給 set,並以其 Version 作為 --expected-version:
授與檔案可以是 get 的完整輸出、其 data、其中的 ServicePrincipal 物件,或僅包含授與:
  • 這兩個屬性都是必要的。空白清單表示不授與該類型的任何項目。
  • 每個遊戲至少需要一個權限。若要移除某個遊戲的授與,請省略該遊戲。
  • 屬性名稱不區分大小寫。無法辨識的屬性會視為錯誤,因此拼錯的 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,如果它們不是您想要設定的內容,請編輯該輸出,並將其傳遞給 set,以其 Version 作為 --expected-version。

範例

列出工作室的服務主體,並顯示其中一個的授與:
以 grants.json (您從 get 儲存並編輯的檔案) 中的授與取代服務主體的授與:
從工作室移除服務主體及其授與:
執行 revoke 之後,服務主體在工作室中的下一個 PlayFab 要求將會失敗。當服務主體已經不具有任何存取權時,revoke 也會成功。若要還原存取權,請使用完整的授與集執行 set。
最後修改於 2026年11月19日