跳轉到主要內容
試玩測試可讓選定的玩家群組在發行之前試玩遊戲。playtest 命令會讀取 Partner Center 中遊戲的試玩測試,並可建立、更新、發佈及刪除試玩測試。create、update、publish 和 delete 在進行變更之前會先詢問。 create、update、publish 和 delete 為實驗性功能:其選項和輸出可能會變更或移除。請參閱實驗性命令。

命令

引數和選項

範例

列出試玩測試、取得其中一個,並比較兩個:
為對象建立試玩測試:
變更試玩測試的結束日期:
發佈試玩測試:
刪除試玩測試:

讀取試玩測試

playtest list 會寫入 playtests 陣列。其表格有 PLAYTEST ID、NAME、STATUS、TYPE、START 和 END 欄。摘錄如下:
playtest get 會依服務傳回的內容寫入試玩測試。etag 是要傳遞給 update --if-match 的版本,而 audiences.audienceIds 會列出可以加入的對象。其表格有 FIELD 和 VALUE 列。 playtest diff 會寫入 hasDiffData、current 和 compared。當 hasDiffData 為 false 時,表示沒有可比較的內容,並會省略 compared。其表格只會在 FIELD、CURRENT 和 COMPARED 欄中顯示不同的欄位。圖像不會進行比較。

建立試玩測試

playtest create 會建立私人草稿試玩測試,並以與 playtest get 相同的方式寫入它。再次執行它會建立另一個試玩測試;請使用 playtest delete 移除您不需要的試玩測試。 每次建立都會傳送等冪索引鍵;除非您傳遞 --idempotency-key,否則它會是新的 GUID。重複使用某個索引鍵的建立,會傳回該索引鍵所建立的試玩測試,並忽略任何不同的選項。 當結果不明時 (例如發生逾時之後),命令會以 3 結束,並列印以相同索引鍵重試的命令:
如果第一個要求已建立試玩測試,重試會傳回該試玩測試,否則會建立它。當選項包含換行符號時,只會列印索引鍵;請搭配 --idempotency-key 和該索引鍵執行相同的命令。如果重試遭到拒絕 (例如因為結束日期已過),請先檢查 playtest list,再以新的索引鍵建立試玩測試。

套件

試玩測試可以有一個 PC 套件和一個主機套件。請從 xbox package list 選擇已準備好用於試玩測試的套件,並將其 id 傳遞給其平台的選項:
在 update 上,您省略的套件選項會保留其套件,新的 ID 會取代它,而 "" 會移除它:

更新試玩測試

任何更新都會讓已發佈的試玩測試回到草稿狀態,就像在 Partner Center 中編輯它一樣。請使用 playtest publish 再次發佈它,讓玩家可以使用。
playtest update 只會變更您傳遞的選項,且至少需要一個選項。它會以與 playtest get 相同的方式寫入更新後的試玩測試。在 Partner Center 中設定的遊戲美術圖案會保留;連結至試玩測試的其他美術圖案則會以預留位置取代。 若要避免覆寫其他人的變更,請在 --if-match 中傳遞來自 playtest get 的 etag。其周圍的雙引號為選用,而 *、弱式 (W/) etag 和 etag 清單會遭到拒絕:
當結果不明時,命令會以 3 結束。請先使用 playtest get 檢查試玩測試,再重試。

選擇對象

對象是賣方在 Partner Center 中管理的玩家群組,例如測試人員。請將來自 audience list 的 id 傳遞給 --audience-id,並重複指定以加入更多對象:
未指定 --audience-id 時,create 會建立沒有對象的試玩測試,而 update 會保留現有對象。在 update 上,您傳遞的 ID 會取代試玩測試的所有對象。若要移除每個對象,請只傳遞 "":
"" 無法與對象 ID 合併使用,且 create 會拒絕它。試玩測試至少需要一個對象才能發佈。

發佈試玩測試

如果遊戲使用 XBOX services,請在發佈之前設定其設定和禁運。請參閱在試玩測試中使用 XBOX services。
發佈會從試玩測試的開始日期起,將其提供給其對象。命令會發佈它最先讀取的版本;如果試玩測試在這之間有所變更,發佈會失敗並傳回 412,且不會變更任何內容。 在要求您確認之前,命令會檢查遊戲的 XBOX services 設定 (例如其禁運日期是否晚於試玩測試的結束日期),並在 stderr 上列出任何需要檢閱的項目。這些檢查僅供參考;--confirm 會直接發佈而不詢問。 接著,服務會執行自己的檢查。當其中一項檢查封鎖發佈時,不會將任何內容排入佇列,而命令會在 stderr 上列出每項檢查,並以 1 結束。請修正錯誤,然後再次發佈。因缺少年齡分級而遭封鎖的試玩測試,需要在 Partner Center 中完成年齡分級問卷。 發佈排入佇列後,命令會等候直到試玩測試為 Scheduled、Live 或 PublishFailed,並以與 playtest get 相同的方式寫入它。按下 Ctrl+C 會停止等候,但發佈會繼續進行。搭配 --no-wait 時,命令會在發佈排入佇列後立即寫入 publishJobId 和任何 warnings;請使用 playtest get 追蹤它。

刪除試玩測試

playtest delete 會刪除它最先讀取的試玩測試版本。它會等候直到試玩測試為 Deleted 或已消失,然後寫入服務的回應 (含 status)。按下 Ctrl+C 會停止等候,但刪除會繼續進行。搭配 --no-wait 時,它會在刪除排入佇列後立即寫入回應。發生 412 之後,刪除可能已排入佇列,因此請等候一分鐘,並先使用 playtest get 檢查,再重新刪除。

日期

--start 和 --end 接受 ISO 8601 日期和時間,例如 2026-11-01T09:00:00-07:00 或 2026-11-01T16:00:00Z。沒有時間的日期表示 UTC 午夜,而沒有時差的時間為 UTC。當更新只傳遞一個日期時,服務會將它與試玩測試的另一個日期進行比對檢查。

錯誤

除非上述結束代碼表格另有說明,否則失敗會寫入 stderr 並以 1 結束。create 和 update 在結果不明時會以 3 結束。服務傳回的失敗會包含其 HTTP 狀態,而 --verbose 會加入服務的回應,其 code 欄位如下所示: 對於其他失敗,命令會顯示服務的訊息。429 表示您傳送了過多要求;請依照訊息所述的時間等候,然後再試一次。
最後修改於 2026年11月19日