xbox) 的設計是既可由人員執行,也可由 AI 代理程式和指令碼執行。它的命令採用明確的引數,資料命令會寫入 JSON,而錯誤會以非零結束代碼輸出至 stderr。此頁面適用於代理程式以及設定代理程式的人員:說明如何登入、選擇命令作用的對象、讀取其輸出、找到正確的 API,以及在變更任何內容之前應詢問的事項。
變更任何內容之前
登入的使用者通常對生產遊戲和賣方具有系統管理員權限,而伺服器端沒有任何機制可阻止錯誤的呼叫。安全性和破壞性作業列出了 CLI 會詢問和不會詢問的事項。其餘部分則由您負責:- 只有名稱以
Get、List或Search開頭的 PlayFab 作業,才視為唯讀。將其他所有作業,以及每個會建立、變更或刪除內容的xbox命令,都視為生產變更。 - 在進行生產變更之前,請向使用者顯示命令,並以一句話說明它會變更什麼,以及在哪個遊戲或賣方上變更,包括該目標是否來自已儲存的內容。只有在使用者同意之後才執行,即使您的執行階段不需詢問就會執行
xbox也一樣。同意只涵蓋您所顯示的呼叫。 - 在每次生產變更時,都以旗標傳遞遊戲或賣方。已儲存的內容由作業系統使用者的每個工作階段共用,因此可能在使用者同意與您呼叫之間發生變更。
- 在執行
xbox pc sandbox set(會為 PC 上的每個人切換沙箱) 之前,以及在執行xbox pc sandbox launch-apps(會關閉 Microsoft Store 和 XBOX 應用程式) 之前,請先詢問。 - 不要以新增
--confirm(或--yes) 來取代詢問。CLI 無法分辨是誰新增的。 - 在要求使用
xbox xbl config publish發佈至 RETAIL 之前,請先以--validate-only執行它,並向使用者顯示它列出的成就。然後將--configset設定為其 JSON 輸出中的SourceVersion來進行發佈。RETAIL 中的成就無法移除;請參閱 RETAIL 發佈所新增的成就。 - 如果生產變更失敗且其結果不明,該變更可能已經套用。請在重試之前讀取受影響的狀態;請參閱中斷的寫入會回報其結果不明。
- 除非使用者要求您變更,否則請勿變更已儲存的內容。
xbox context set、xbox context unset和xbox context profile delete會變更每個工作階段的預設值。
登入
auth status 會以代碼 0 結束並回報 {"signedIn":false},因此請依據 signedIn 進行分支。非零的結束代碼表示它無法檢查,而錯誤會在 stderr 上。除非登入的使用者在遊戲上具有 Admin 權限,否則 PlayFab 呼叫會失敗。請參閱驗證。
選擇遊戲或賣方
以旗標傳遞遊戲或賣方,例如--playfab-title-id ABC123。若未指定,命令會使用 XBOX_ 環境變數或以 xbox context set 儲存的值;如需了解哪一個優先,請參閱內容。執行 xbox context get --output json-compact 以查看已儲存的內容,並在呼叫任何實質作業之前,先與使用者確認一次遊戲。
讀取輸出
結合--data-only 和 --output json-compact,即可在單一行上只取得承載:
--data-only 時,發生錯誤時 stdout 會是空的,因此請在剖析 stdout 之前先檢查結束代碼。
playfab file upload、download 和 delete 不會寫入任何內容至 stdout,而且其 stderr 訊息可能會變更,因此請檢查其結束代碼。請參閱檔案。
說明會標示實驗性命令,其介面可能會變更。請參閱實驗性命令。
速率限制
當 XBOX 服務回應 HTTP 429 時,請等候後再重試;CLI 不會為您重試。當服務指定等候時間時,錯誤會指出秒數,而結構化錯誤也會以retryAfterSeconds 攜帶此值。錯誤碼為 rate_limited 的 429 表示您在短時間內傳送了太多要求,因此請放慢速度。
尋找正確的 PlayFab API
xbox playfab api <api-path> 可呼叫任何 PlayFab API 作業。路徑為 /<Prefix>/<Operation>,例如 /MultiplayerServer/ListBuildSummariesV2,而要求本文是該作業的 JSON 要求物件。PlayFab 對兩者都有文件說明:
- PlayFab Swagger 規格為機器可讀格式。每個檔案都會依路徑列出其作業,以及其要求和回應結構描述與必要欄位。這些檔案是以 PlayFab 的 API 群組命名,而不是以路徑的第一個區段命名,因此請在檔案的
paths中搜尋作業:/Catalog和/Inventory位於Economy.swagger.json中,而/Match、/Lobby和/MultiplayerServer位於Multiplayer.swagger.json中。每個作業的security欄位會指出它接受的認證:SecretKey、EntityToken、SessionTicket,或對於不需要認證的作業 (例如玩家登入呼叫) 則為None。有些作業也會在其描述中列出允許的實體權杖類型。 - PlayFab REST API 參考以適合人員閱讀的方式涵蓋相同的作業。
SessionTicket,或只接受玩家或遊戲伺服器實體權杖的作業,都不會獲得授權。呼叫失敗時,其錯誤回應通常會指出問題所在,例如 InvalidParameter 或 MissingParameter。如需詳細資訊,請參閱 PlayFab API 整合。
在 Windows 上的 Git Bash 中,請為命令設定 MSYS_NO_PATHCONV=1,否則 Git Bash 會在 CLI 收到 API 路徑之前將其轉換為 Windows 路徑。請參閱從 Windows 上的 Git Bash 執行。
避免祕密出現在記錄中
- 當要求本文可能包含祕密時,請使用
--body-file而不是--body傳遞它,讓它不會出現在殼層歷程記錄和處理序清單中。playfab mps certificate upload和playfab mps secret upload會拒絕--body,因為它們的本文一定包含祕密。 - 不要將祕密放在組態檔和環境變數中。
ClientId、TenantId和 OAuth 範圍是識別碼,而不是祕密。 - PlayFab 回應可能包含玩家、庫存或經濟系統資料。對代理程式所記錄的任何內容進行修訂、保留和存取控制,由代理程式的擁有者負責。
