本指南說明如何使用 gcloud beta device-run CLI 執行獨立 Android 執行檔，並在 Google Cloud 控制台中查看結果。並假設您已有 Google Cloud 帳戶和專案。
如要從 Firebase Test Lab 遷移至 Developer Device Platform，請參閱遷移指南、指令和旗標對照表，以及 AI 代理的遷移技能。
如要使用這項 Google Cloud CLI，您必須提供 Google Cloud 專案 ID。如需指令摘要，請參閱 gcloud beta device-run。
事前準備
這些步驟假設您已完成下列事項：
- 已建立 Google Cloud 專案。
- 按照快速入門導覽課程設定 Developer Device Platform。
- 已在終端機中使用
gcloud進行驗證。 - 查看Device Run 總覽，瞭解一般資訊。
- 準備獨立的 Android 執行檔 (例如編譯的 C++ 二進位檔、基準測試執行工具或殼層指令碼)。
步驟 1：設定可執行的執行作業
Android 執行檔選項
- 多部裝置：如要在多部裝置上執行同一個可執行檔，請提供
--device旗標，並以半形逗號分隔多個裝置 ID (例如--device shiba-34,tokay-36)，或提供多個--device旗標，每個旗標指定不同的裝置 ID (例如--device shiba-34 --device tokay-36)。 - 將檔案推送至裝置：在執行前，使用
--other-files-to-push=SOURCE=DEST,...將其他檔案 (例如機器學習模型權重、測試輸入或.so共用程式庫) 推送至裝置。SOURCE支援本機路徑和 Cloud Storage (gs://...) 路徑，而DEST是裝置上的目的地路徑。 - 從裝置提取檔案：執行完成後，使用
--paths-to-pull=DEVICE_PATH,...從裝置提取產生的檔案或目錄。 - 自訂 Cloud Storage bucket：使用
--bucket-name=指定現有的 Cloud Storage bucket 名稱 (不含gs://配置或路徑)。如未指定 bucket，Google Cloud CLI 會使用或建立名為PROJECT_ID-devicerun的預設 bucket。 - 不穩定測試重試：設定每項工作或 shard 的重試次數上限，以處理不穩定問題：
--flaky-test-attempts=3(預設為1次)。 - 裝置環境和診斷：設定裝置螢幕方向 (
--orientation=portrait或landscape)、語言代碼 (--locale=en-US)、模擬 GPS 位置 (--coordinates=LATITUDE,LONGITUDE)、螢幕錄影 (--video=always或on-failure)、dumpsys收集 (--dumpsys=always或on-failure) 或bugreport收集 (--bugreport=always或on-failure)。 - 標籤：使用
--labels=KEY=VALUE,...將使用者定義的鍵/值標籤附加至工作階段。 - 可執行引數：使用
--executable-args=ARG,...以逗號分隔的清單或重複旗標，將指令列引數傳遞至執行檔。每個元素都會成為一個引數，因此請將以空格分隔的指令列改寫為以半形逗號分隔的形式 (例如--executable-args="--input=a.file,--threads=4")。如要傳遞本身包含半形逗號的引數，請在值前面加上^SEP^，指定不同的分隔符號 (例如--executable-args="^;^--shape=1,224,224,3;--threads=4")。 - 環境變數：使用
--executable-env-vars=KEY=VALUE,...為裝置上的可執行程序設定環境變數 (例如--executable-env-vars=LD_LIBRARY_PATH=/data/local/tmp/lib)。 - Executable timeout：限制可執行檔的執行時間長度：
--executable-timeout=10m(有效範圍為1m至3h，預設值為5m，不含裝置準備和清理時間)。
同步和非同步執行
根據預設，提交指令會封鎖 (同步)。系統會等待執行檔完成，並列印結果摘要表。
如要在將檔案上傳至 Cloud Storage 後立即提交工作階段並返回，請新增 --async 旗標：
gcloud beta device-run sessions submit android-executable \
--device shiba-35 \
--executable ./MY_EXECUTABLE \
--async
這項操作會立即傳回工作階段 ID。接著，您可以使用 sessions wait 指令等待作業完成：
gcloud beta device-run sessions wait SESSION_ID
指令會封鎖，直到工作完成為止。
多部裝置
如要在多部裝置上執行相同的執行檔，請提供 --device 旗標，並以半形逗號分隔多個裝置 ID，或提供多個 --device 旗標，每個旗標指定不同的裝置 ID。
gcloud beta device-run sessions submit android-executable \
--device shiba-34,tokay-36 \
--executable ./MY_EXECUTABLE
或：
gcloud beta device-run sessions submit android-executable \
--device shiba-34 \
--device tokay-36 \
--executable ./MY_EXECUTABLE
執行檔逾時
限制執行檔的執行時間：
gcloud beta device-run sessions submit android-executable \
--device shiba-35 \
--executable ./MY_EXECUTABLE \
--executable-timeout=10m
執行作業的有效範圍為 1m 至 3h，預設值為 5m。
步驟 2：選擇裝置
使用 device-run CLI，Android 執行檔可在可用的實體和虛擬裝置上執行。如要查看可用裝置的完整清單，請前往互動式裝置目錄，或執行以下指令：
gcloud beta device-run devices list
輸出內容範例：
ID MAKE NAME MODEL FORM OS_VERSION CAPACITY AVAILABILITY PRODUCTS
tegu-35 Google Pixel 9a tegu PHYSICAL 35 MEDIUM LOW Automation, Streaming
tokay-34 Google Pixel 9 tokay PHYSICAL 34 HIGH HIGH Automation, Streaming
請參閱裝置目錄，瞭解如何篩選這份清單。如要指定特定裝置執行，請在提交指令中使用對應的 ID (例如 tegu-35)。
步驟 3：執行可執行檔
提交獨立的 Android 執行檔。
如要直接在 Android 裝置上執行獨立執行檔 (例如編譯的 C++ 二進位檔、LiteRT 等裝置端機器學習基準執行工具，或殼層指令碼)，而不將其封裝至 APK，請使用 sessions submit
android-executable 指令。
Android 執行檔必須使用下列旗標：
- 裝置：使用
--device指定裝置：--device shiba-35 - Executable：使用
--executable指定可執行檔的本機或 Cloud Storage 路徑：--executable /path/to/my_executable
如要執行可執行檔，請發出類似下列的指令，並使用您自己的裝置 ID 和可執行檔路徑：
gcloud beta device-run sessions submit android-executable \
--device shiba-34 \
--executable /path/to/my_executable \
--executable-args="--input=/data/local/tmp/file.name,--threads=4" \
--other-files-to-push=/path/to/model.tflite=/data/local/tmp/model.tflite \
--paths-to-pull=/data/local/tmp/output
您可以在 Cloud Storage 路徑 (例如 gs://BUCKET_NAME/automation/sessions/SESSION_ID/) 找到工作的結果報表資料夾。請查看指令輸出內容，找出類似 https://console.cloud.google.com/storage/browser/BUCKET_NAME/automation/sessions/SESSION_ID/ 的連結。
步驟 4：探索及管理可執行檔執行作業
無論是 sessions submit android-executable 指令的非同步或同步模式，您都可以使用 sessions describe 指令，在執行期間查詢工作狀態，或在完成後取得結果：
gcloud beta device-run sessions describe SESSION_ID
輸出內容會總結執行結果，並提供Google Cloud 控制台中的結果連結。例如：
Session SESSION_ID finished with result [FAILED].
Result files are stored at [https://console.cloud.google.com/storage/browser/BUCKET_NAME/automation/sessions/SESSION_ID/].
JOB NAME EXECUTION NAME EXECUTION RESULT
job-000 all FAILED: 2 test cases failed, 5 passed
使用下列指令，列出所有執行中和已完成的工作階段：
gcloud beta device-run sessions list
輸出內容會列出專案中的工作階段，類似以下內容：
SESSION_ID START_TIME STATE
session-4825e153 2026-07-28T16:38:43.155Z DONE
session-813ca602 2026-07-28T22:40:32.415Z DONE
session-67cd0570 2026-07-16T08:25:55.474Z DONE
session-17cc299c 2026-07-14T14:31:33.649Z DONE
session-911d0763 2026-07-09T00:39:02.051Z DONE
session-4e943fea 2026-07-15T23:08:32.252Z DONE
session-0132e458 2026-08-20T18:33:19.751Z DONE
session-1077f07b 2026-07-28T22:35:43.848Z DONE
session-71b054c6 2026-07-15T01:15:41.643Z DONE
session-4f8b2e45 2026-08-06T23:11:56.161Z DONE
sessions list 指令支援所有標準 Google Cloud CLI 旗標選項。例如：
gcloud beta device-run sessions list --limit 5
結果會類似於：
SESSION_ID START_TIME STATE
session-4825e153 2026-07-28T16:38:43.155Z DONE
session-813ca602 2026-07-28T22:40:32.415Z DONE
93ec2df2-d5bf-4c36-b7f7-c2a4fb0dc3ce 2026-07-03T05:10:58.015Z DONE
session-67cd0570 2026-07-16T08:25:55.474Z DONE
session-17cc299c 2026-07-14T14:31:33.649Z DONE
如要找出所有執行中的工作階段，請執行：
gcloud beta device-run sessions list --filter RUNNING
假設您有執行中的工作階段，就會看到類似下方的結果：
SESSION_ID START_TIME STATE
session-d7ff8b81 RUNNING
否則，您將收到 Listed 0 items.
如要取消執行中的工作階段，請執行下列指令並附上工作階段 ID：
gcloud beta device-run sessions cancel SESSION_ID
由於工作階段僅標示為取消，因此指令會立即傳回。取消作業會在後端以非同步方式進行。
如果工作階段已結束，系統只會顯示目前狀態。要求取消已完成的工作階段不會發生錯誤。
後續步驟
接下來，請執行 Android 檢測設備測試，或尋找及分析記錄。