跳轉到主要內容
XBOX 測試帳戶是以批次方式為 Partner Center 賣方建立的。這些命令可建立、更新及刪除批次、追蹤建立帳戶的作業,以及讀取批次和其中的帳戶。它們無法變更個別帳戶,而且絕不會傳回密碼。您的帳戶需要具備該賣方的 Partner Center 測試帳戶角色。 每個命令都採用 --seller-id。若未指定,命令會使用 XBOX_SELLER_ID 或以 xbox context set 儲存的賣方,其次使用您唯一的賣方;如果您有多個賣方,請傳遞 --seller-id。

命令

batch create、batch update 和 batch delete 在變更任何內容之前會先詢問,而且只會傳送一次,絕不重試。請參閱安全性和破壞性作業。

讀取批次的選項

標籤在 JSON 輸出和錯誤碼 (例如 test_account_keyword_invalid) 中會顯示為 keywords。--tag 會比對整個標籤,而不是標籤的一部分。 如果您無法讀取賣方的每個批次,並不會收到錯誤:batch list 只會傳回您建立的批次。

已到期的批次

當批次的 accessExpirationDate (其沙箱存取權結束的日期) 過去後,該批次就會到期。沒有日期的批次永遠不會到期。到期與否並不代表帳戶是否仍可登入。 batch list --expired 會讀取賣方的完整清單以找出已到期的批次,因此對於有許多批次的賣方,速度會較慢。它無法與 --include-sandboxes 合併使用;請對已到期的批次執行 batch get,以查看其沙箱存取權。

回應格式

list 會傳回:
  • 除非您傳遞 --include-sandboxes,否則 keywords 和 sandboxAccess 為 null。get 一律會傳回它們。
  • isComplete 表示建立作業已停止,而不是每個帳戶都已建立。請將 get 傳回的帳戶數與 batchSize 比較,並讀取 progress 以取得狀態訊息。
  • createdBy 是數值 Partner Center 使用者 ID。
  • jobId 是批次正在執行的作業,作業停止後即為 null。更新和刪除作業也會顯示在這裡,但只有建立作業可以使用 job wait 追蹤。
get 會傳回相同的批次物件,以及其帳戶:
每個帳戶只有 xuid、email、gamertag 和 isDeleted。xuid 是字串。

讀取批次時的錯誤

batch list、batch get 和 test-account get 失敗時會以 1 結束。當服務傳回 JSON 錯誤時,stderr 會收到 JSON 錯誤,其中包含 status、title、detail、回應包含時的 code,以及其 correlationId;大多數錯誤會在 detail 中加入提示。其他失敗會列印一行文字。請先檢查結束代碼,再剖析 stderr。

查閱帳戶

test-account get <email> 會指出包含某個帳戶的批次是否已到期。電子郵件必須以 @xboxtest.com 結尾。此命令會搜尋電子郵件範本與帳戶名稱相符的最新 10 個批次。如果在其中找不到帳戶,它會指出未搜尋較舊的批次,並列印 batch list 和 batch get 命令,讓您自行檢查。 它會傳回下列內容 (此處已縮短);batch 包含 batch list 傳回的每個批次欄位:
當批次尚未到期時,expiredOn 為 null。只有在不存在有效複本時,才會回報已刪除的帳戶,並設定 account.isDeleted。只要找到帳戶,無論是否已到期,命令都會以 0 結束,因此指令碼應讀取 expired。在下列情況下,它會以 1 結束:
  • 帳戶不在您可以看到的批次中。它可能屬於其他賣方 (請嘗試 --seller-id),或其批次是由其他開發人員建立,而您無法讀取賣方的每個批次。
  • 電子郵件出現在多個批次中。stderr 會為每個批次列出 batch get 命令。
  • 要求失敗,如讀取批次時的錯誤中所述。

建立批次

batch create 會啟動建立帳戶的作業,然後等候它停止。在批次刪除之前,這些帳戶會計入賣方的測試帳戶限制。 在終端機中,命令會顯示安全性問題選擇器、列出它將傳送的值 (包括您省略之選項的預設值),並要求您確認。接著,它會提示您輸入密碼和安全性答案、登入,然後傳送要求。--confirm (--yes、-y) 只會略過確認。 沒有終端機時,請傳遞 --password-file、--security-answer-file 和 --confirm。未指定 --confirm 時,命令會列印這些值、拒絕執行,且不傳送任何內容。

選擇安全性問題

在終端機中,當您既未傳遞 --security-question 也未傳遞 --security-answer-file 時,命令會顯示這些問題的編號選擇器。按 Enter 會選取第一個問題。若要在不使用選擇器的情況下選擇問題,請以 --security-question 傳遞其文字:
  1. What is your favorite hobby?
  2. Who is your favorite athlete?
  3. What is your maternal grandmother’s first name?
  4. What was your childhood best friend’s first name?
  5. What was the name of your first pet?
  6. What is your current best friend’s first name?
  7. What was your favorite city to visit as a child?
沒有終端機時,或有答案檔案但沒有問題時,問題為 What is your favorite hobby?。在選擇器中按 Ctrl+C 會取消,且不會建立任何項目。選擇問題並不代表確認建立。

秘密

密碼和安全性答案絕不會以選項值或環境變數的形式接受,因此它們不會出現在 shell 歷程記錄、處理程序清單和記錄中。每一項都來自:
  • 其 --password-file 或 --security-answer-file。結尾的單一換行符號會被移除。
  • 以 - 取代路徑,從 stdin 讀取。兩者中只有一個可以讀取 stdin。
  • 未指定檔案選項時,終端機中不會回顯您所輸入內容的提示。
密碼必須為 8 到 16 個字元,且至少包含下列其中三種:小寫字母、大寫字母、數字和符號。底線不算是符號。密碼不能與安全性答案相同。

等候和結束代碼

等候期間,命令會將進度列印至 stderr。它會將最終作業寫入 stdout,格式與 job get 相同。

結果不明時

當 CLI 無法判斷服務是否已建立批次時 (例如在要求傳送後連線中斷,或服務傳回 5xx 錯誤),它會以 3 結束。它絕不會再次傳送建立要求。stderr 會以 UTC 列印要求開始的時間,以及下列步驟:
  1. 等候幾分鐘;仍在建立中的批次可能尚未列出。
  2. 執行 xbox test-account batch list --mine --email-prefix <prefix>,並尋找具有相同電子郵件前置詞和範本,且在該時間或之後建立的批次。
  3. 如果該批次的 jobId 已設定,請使用 xbox test-account job wait <job-id> --batch-id <batch-id> 追蹤它。如果 jobId 為 null,表示作業已停止;請使用 xbox test-account batch get <batch-id> 檢查它。
  4. 只有在不存在此類批次時,才再次建立。
列印的命令會保留您使用的賣方、設定檔和登入選項,因此您可以直接複製使用。

建立時的錯誤

失敗時會將 JSON 錯誤寫入 stderr,其中包含 status、title、detail,以及回應包含時的 code。請依據 code 進行分支處理,而不是依據 detail。

追蹤建立作業

batch create 會在作業被接受後立即列印批次和作業 ID。作業可能會執行數天,因此您可以隨時停止等候,稍後再追蹤: 兩者都會傳回作業:
state 為 running、succeeded 或 failed。作業失敗時,errorCode 為 test_account_job_failed。job wait 會重試暫時性的讀取失敗,例如節流或連線中斷。

追蹤作業時的錯誤

這些錯誤碼指向作業 ID、--batch-id 或 --seller-id:

更新批次

batch update 會變更批次中的每個帳戶:它可以授與帳戶更多沙箱的存取權、移除存取權、變更該存取權的到期時間,以及新增或取代批次的標籤。接著,它會等候直到批次顯示變更。 在終端機中,命令會先在批次目前的值旁邊顯示每個要求的變更、在批次仍有作業執行時發出警告,然後詢問。傳遞 --confirm (--yes、-y) 即可略過提示。沒有終端機且未指定 --confirm 時,它會列印變更、拒絕執行,且不傳送任何內容。 請至少傳遞一項變更。一個批次最多可以有 20 個標籤。--replace-tags 和 --clear-tags 會保留記錄是哪個工具建立批次的標籤,此標籤不計入限制。變更沙箱或到期時間需要這些沙箱的存取權;延長到期時間則需要批次上每個沙箱的存取權。 更新完成後,命令會傳回批次的值:
批次顯示變更後,state 為 updated;搭配 --no-wait 或等候先結束時,則為 updating。當批次已具有每個要求的值時,不會變更任何內容:state 為 unchanged、jobId 為 null,且命令以 0 結束。更新作業無法使用 job get 或 job wait 追蹤。

更新時的等候和結束代碼

更新時的錯誤

無代碼的 404 或 405 表示無法使用更新批次功能。

刪除批次

batch delete 會刪除整個批次,然後等候直到它消失。批次中的每個帳戶都會失去其沙箱存取權,且其測試帳戶記錄會被刪除。帳戶的 Microsoft 帳戶和 XBOX 設定檔不會關閉。 在終端機中,命令會先顯示批次的電子郵件範本、大小和建立者、在批次仍有作業執行時發出警告,然後詢問。傳遞 --confirm (--yes、-y) 即可略過提示。沒有終端機且未指定 --confirm 時,它會列印將要刪除的內容、拒絕執行,且不傳送任何內容。沒有大量刪除功能;請一次刪除一個批次。 命令會傳回:
批次消失後,state 為 deleted;搭配 --no-wait 或等候先結束時,則為 deleting。刪除作業無法使用 job get 或 job wait 追蹤;刪除執行期間,批次會顯示其 jobId。

刪除時的等候和結束代碼

刪除時的錯誤

無代碼的 404 或 405 表示無法使用刪除批次功能。

表格輸出

每個命令都接受 --output table。時間以 UTC 顯示,摘要行會寫入 stderr,因此 stdout 只包含表格。

範例

這些命令會列出及讀取批次、帳戶和作業:
建立包含五個帳戶的批次。命令會提示您輸入密碼和安全性答案,然後要求您確認:
在無人看管的情況下建立批次,從檔案讀取秘密、不顯示提示,並最多等候 30 分鐘:
最多等候兩小時,讓建立作業完成:
新增沙箱,並設定沙箱存取權的到期時間。命令會顯示變更、要求您確認,然後等候直到批次顯示這些變更:
在無人看管且不等候的情況下新增兩個標籤:
以一個標籤取代所有標籤:
刪除批次。命令會顯示批次、要求您確認,然後等候直到它消失:
在無人看管且不等候的情況下,刪除其他開發人員建立的批次:
最後修改於 2026年11月19日