為配合主幹穩定開發模型，並確保生態系統的平台穩定性，我們將於 2026 年起，在第 2 季和第 4 季將原始碼發布至 AOSP。如要建構及貢獻 AOSP，建議使用 android-latest-release，而非 aosp-main。android-latest-release 資訊清單分支版本一律會參照推送至 AOSP 的最新版本。詳情請參閱「Android 開放原始碼計畫變更」一文。

GceManager

public class GceManager
extends Object

java.lang.Object
↳	com.android.tradefed.device.cloud.GceManager

這個輔助程式會管理 GCE 呼叫，以啟動/停止 GCE 並從中收集記錄。

摘要

常數
`String`	`GCE_HOSTNAME_KEY`
`String`	`GCE_INSTANCE_CLEANED_KEY`
`String`	`GCE_INSTANCE_NAME_KEY`
`String`	`GCE_IP_PRECONFIGURED_KEY`

公用建構函式
`GceManager(DeviceDescriptor deviceDesc, TestDeviceOptions deviceOptions, IBuildInfo buildInfo)` Ctor
`GceManager(DeviceDescriptor deviceDesc, TestDeviceOptions deviceOptions, IBuildInfo buildInfo, testResourceBuildInfos)` 這個建構函式已淘汰。請使用其他建構函式，我們暫時保留這個建構函式，以確保回溯相容性。
`GceManager(DeviceDescriptor deviceDesc, TestDeviceOptions deviceOptions, IBuildInfo buildInfo, String gceInstanceName, String gceHost)` Ctor，可用於直接提供要使用的 GCE 執行個體名稱的變數。

公用方法
`static boolean`	`AcloudShutdown(TestDeviceOptions options, IRunUtil runUtil, String instanceName, String hostname, boolean isIpPreconfigured)` 實際執行 Acloud，關閉虛擬裝置。
`void`	`cleanUp()`
`static File`	`getBugreportzWithSsh(GceAvdInfo gceAvd, TestDeviceOptions options, IRunUtil runUtil)` 使用 SSH 從裝置取得 bugreportz，避免發生任何 ADB 連線問題。
`HostOrchestratorUtil`	`getHostOrchestratorUtil()` 傳回 `HostOrchestratorUtil` 的例項。
`static String`	`getInstanceSerialLog(GceAvdInfo infos, File avdConfigFile, File jsonKeyFile, IRunUtil runUtil)` 讀取 Gce Avd 執行個體序列記錄的目前內容。
`static File`	`getNestedDeviceSshBugreportz(GceAvdInfo gceAvd, TestDeviceOptions options, IRunUtil runUtil)` 透過 SSH 取得巢狀執行個體的錯誤報告。
`static void`	`logAndDeleteFile(File tempFile, String dataName, ITestLogger logger)`
`static void`	`logDirectory(File remoteDirectory, String baseName, ITestLogger logger, LogDataType type)`
`static boolean`	`logNestedRemoteFile(ITestLogger logger, GceAvdInfo gceAvd, TestDeviceOptions options, IRunUtil runUtil, String remoteFilePath, LogDataType type)` 從巢狀執行個體擷取遠端檔案並記錄。
`static boolean`	`logNestedRemoteFile(ITestLogger logger, GceAvdInfo gceAvd, TestDeviceOptions options, IRunUtil runUtil, String remoteFilePath, LogDataType type, String baseName)` 從巢狀執行個體擷取遠端檔案並記錄。
`void`	`logSerialOutput(GceAvdInfo infos, ITestLogger logger)` 記錄 `GceAvdInfo` 所述裝置的序列輸出內容。
`static CommandResult`	`remoteSshCommandExecution(GceAvdInfo gceAvd, TestDeviceOptions options, IRunUtil runUtil, long timeoutMs, String... command)` 透過執行個體上的 SSH 執行遠端指令。
`boolean`	`shutdownGce()` 關閉與 `startGce()` 相關聯的 Gce 執行個體。
`GceAvdInfo`	`startGce(String ipDevice, String user, Integer offset, MultiMap<String, String> attributes, ITestLogger logger)` 嘗試使用 Acloud 或 Oxygen 啟動 GCE 執行個體。
`GceAvdInfo`	`startGce()`
`GceAvdInfo`	`startGce(String ipDevice, MultiMap<String, String> attributes)` 嘗試啟動 GCE 執行個體。
`GceAvdInfo`	`startGce(String ipDevice, String user, Integer offset, MultiMap<String, String> attributes)` 嘗試使用 Acloud 或 Oxygen 啟動 GCE 執行個體。
	`startMultiDevicesGce( buildInfos)` 這個方法已淘汰。 Remove this after master branch is updated.
	`startMultiDevicesGce( buildInfos, MultiMap<String, String> attributes)` 嘗試使用 Oxygen 啟動多部裝置的 GCE 執行個體。

受保護的方法
`static`	`buildShutdownCommand(File config, TestDeviceOptions options, String instanceName, String hostname, boolean isIpPreconfigured)`
`String`	`extractInstanceName(String bootupLogs)` 從 GCE 開機記錄檔擷取執行個體名稱。

常數

GCE_HOSTNAME_KEY

public static final String GCE_HOSTNAME_KEY

常數值： "gce-hostname"

GCE_INSTANCE_CLEANED_KEY

public static final String GCE_INSTANCE_CLEANED_KEY

常數值： "gce-instance-clean-called"

GCE_INSTANCE_NAME_KEY

public static final String GCE_INSTANCE_NAME_KEY

常數值： "gce-instance-name"

GCE_IP_PRECONFIGURED_KEY

public static final String GCE_IP_PRECONFIGURED_KEY

常數值： "gce-ip-pre-configured"

公用建構函式

GceManager

public GceManager (DeviceDescriptor deviceDesc, 
                TestDeviceOptions deviceOptions, 
                IBuildInfo buildInfo)

Ctor

參數
`deviceDesc`	`DeviceDescriptor`：與 GCE 裝置建立關聯的 `DeviceDescriptor`。
`deviceOptions`	`TestDeviceOptions`：與裝置相關聯的 `TestDeviceOptions`。
`buildInfo`	`IBuildInfo`：說明要啟動的 GCE 建構作業的 `IBuildInfo`。

GceManager

public GceManager (DeviceDescriptor deviceDesc, 
                TestDeviceOptions deviceOptions, 
                IBuildInfo buildInfo, 
                 testResourceBuildInfos)

這個建構函式已淘汰。
Use other constructors, we keep this temporarily for backward compatibility.

參數
`deviceDesc`	`DeviceDescriptor`
`deviceOptions`	`TestDeviceOptions`
`buildInfo`	`IBuildInfo`
`testResourceBuildInfos`

GceManager

public GceManager (DeviceDescriptor deviceDesc, 
                TestDeviceOptions deviceOptions, 
                IBuildInfo buildInfo, 
                String gceInstanceName, 
                String gceHost)

Ctor，可用於直接提供要使用的 GCE 執行個體名稱。

參數
`deviceDesc`	`DeviceDescriptor`：要與 GCE 裝置建立關聯的 `DeviceDescriptor`。
`deviceOptions`	`TestDeviceOptions`：與裝置相關聯的 `TestDeviceOptions`
`buildInfo`	`IBuildInfo`：說明要啟動的 GCE 建構作業的 `IBuildInfo`。
`gceInstanceName`	`String`：要使用的執行個體名稱。
`gceHost`	`String`：要使用的執行個體主機名稱或 IP。

公用方法

AcloudShutdown

public static boolean AcloudShutdown (TestDeviceOptions options, 
                IRunUtil runUtil, 
                String instanceName, 
                String hostname, 
                boolean isIpPreconfigured)

實際執行 Acloud 來關閉虛擬裝置。

參數
`options`	`TestDeviceOptions`：Acloud 選項的 `TestDeviceOptions`
`runUtil`	`IRunUtil`：執行 Acloud 的 `IRunUtil`
`instanceName`	`String`：要關閉的執行個體。
`hostname`	`String`：執行個體的主機名稱，僅適用於 Oxygen cuttlefish。
`isIpPreconfigured`	`boolean`：AVD 是否是在預先設定 IP 的遠端裝置上建立

傳回
`boolean`	成功時為 True

cleanUp

public void cleanUp ()

getBugreportzWithSsh

public static File getBugreportzWithSsh (GceAvdInfo gceAvd, 
                TestDeviceOptions options, 
                IRunUtil runUtil)

使用 SSH 從裝置取得 bugreportz，避免發生任何 ADB 連線問題。

參數
`gceAvd`	`GceAvdInfo`：說明裝置的 `GceAvdInfo`。
`options`	`TestDeviceOptions`：`TestDeviceOptions`，說明要用於 GCE 裝置的裝置選項。
`runUtil`	`IRunUtil`：執行指令的 `IRunUtil`。

傳回
`File`	指向 zip 錯誤報告的檔案，如果發生問題，則為空值。

擲回
	IOException

getHostOrchestratorUtil

public HostOrchestratorUtil getHostOrchestratorUtil ()

傳回 HostOrchestratorUtil 的例項。

傳回
`HostOrchestratorUtil`

getInstanceSerialLog

public static String getInstanceSerialLog (GceAvdInfo infos, 
                File avdConfigFile, 
                File jsonKeyFile, 
                IRunUtil runUtil)

讀取 Gce Avd 執行個體序列記錄的目前內容。

參數
`infos`	`GceAvdInfo`：描述執行個體的 `GceAvdInfo`。
`avdConfigFile`	`File`：AVD 設定檔
`jsonKeyFile`	`File`：服務帳戶 JSON 金鑰檔案。
`runUtil`	`IRunUtil`：執行指令的 `IRunUtil`。

傳回
`String`	如果發生錯誤，則為序列記錄輸出內容或空值。

getNestedDeviceSshBugreportz

public static File getNestedDeviceSshBugreportz (GceAvdInfo gceAvd, 
                TestDeviceOptions options, 
                IRunUtil runUtil)

透過 SSH 取得巢狀執行個體的錯誤報告。這項作業需要在巢狀虛擬執行個體中要求 adb。

參數
`gceAvd`	`GceAvdInfo`：說明裝置的 `GceAvdInfo`。
`options`	`TestDeviceOptions`：`TestDeviceOptions`，說明要用於 GCE 裝置的裝置選項。
`runUtil`	`IRunUtil`：執行指令的 `IRunUtil`。

傳回
`File`	指向 zip 錯誤報告的檔案，如果發生問題，則為空值。

擲回
	IOException

logAndDeleteFile

public static void logAndDeleteFile (File tempFile, 
                String dataName, 
                ITestLogger logger)

參數
`tempFile`	`File`
`dataName`	`String`
`logger`	`ITestLogger`

logDirectory

public static void logDirectory (File remoteDirectory, 
                String baseName, 
                ITestLogger logger, 
                LogDataType type)

參數
`remoteDirectory`	`File`
`baseName`	`String`
`logger`	`ITestLogger`
`type`	`LogDataType`

logNestedRemoteFile

public static boolean logNestedRemoteFile (ITestLogger logger, 
                GceAvdInfo gceAvd, 
                TestDeviceOptions options, 
                IRunUtil runUtil, 
                String remoteFilePath, 
                LogDataType type)

從巢狀執行個體擷取遠端檔案並記錄。

參數
`logger`	`ITestLogger`：要記錄檔案的 `ITestLogger`。
`gceAvd`	`GceAvdInfo`：說明裝置的 `GceAvdInfo`。
`options`	`TestDeviceOptions`：`TestDeviceOptions`，說明要用於 GCE 裝置的裝置選項。
`runUtil`	`IRunUtil`：執行指令的 `IRunUtil`。
`remoteFilePath`	`String`：檔案的遠端路徑。
`type`	`LogDataType`：記錄檔案的 `LogDataType`。

傳回
`boolean`	檔案是否已成功記錄。

logNestedRemoteFile

public static boolean logNestedRemoteFile (ITestLogger logger, 
                GceAvdInfo gceAvd, 
                TestDeviceOptions options, 
                IRunUtil runUtil, 
                String remoteFilePath, 
                LogDataType type, 
                String baseName)

從巢狀執行個體擷取遠端檔案並記錄。

參數
`logger`	`ITestLogger`：要記錄檔案的 `ITestLogger`。
`gceAvd`	`GceAvdInfo`：說明裝置的 `GceAvdInfo`。
`options`	`TestDeviceOptions`：`TestDeviceOptions`，說明要用於 GCE 裝置的裝置選項。
`runUtil`	`IRunUtil`：執行指令的 `IRunUtil`。
`remoteFilePath`	`String`：檔案的遠端路徑。
`type`	`LogDataType`：記錄檔案的 `LogDataType`。
`baseName`	`String`：用來記錄檔案的基本名稱。如果為空值，系統會使用實際檔案名稱。

傳回
`boolean`	檔案是否已成功記錄。

logSerialOutput

public void logSerialOutput (GceAvdInfo infos, 
                ITestLogger logger)

記錄 GceAvdInfo 所述裝置的序列輸出內容。

參數
`infos`	`GceAvdInfo`：描述執行個體的 `GceAvdInfo`。
`logger`	`ITestLogger`：記錄序列記錄的`ITestLogger`位置。

remoteSshCommandExecution

public static CommandResult remoteSshCommandExecution (GceAvdInfo gceAvd, 
                TestDeviceOptions options, 
                IRunUtil runUtil, 
                long timeoutMs, 
                String... command)

透過執行個體上的 SSH 執行遠端指令。

參數
`gceAvd`	`GceAvdInfo`：說明裝置的 `GceAvdInfo`。
`options`	`TestDeviceOptions`：`TestDeviceOptions`，說明要用於 GCE 裝置的裝置選項。
`runUtil`	`IRunUtil`：執行指令的 `IRunUtil`。
`timeoutMs`	`long`：指令的逾時時間 (以毫秒為單位)。0 表示沒有逾時。
`command`	`String`：要執行的遠端指令。

傳回
`CommandResult`	`CommandResult`，其中包含執行結果。

shutdownGce

public boolean shutdownGce ()

關閉與 startGce() 相關聯的 Gce 執行個體。

傳回
`boolean`	如果要求 GCE 關機時未封鎖，則傳回 true。

startGce

public GceAvdInfo startGce (String ipDevice, 
                String user, 
                Integer offset, 
                MultiMap<String, String> attributes, 
                ITestLogger logger)

嘗試使用 Acloud 或 Oxygen 啟動 GCE 執行個體。

參數
`ipDevice`	`String`：執行 AVD 的 GCE 執行個體初始 IP，`null`如不適用
`user`	`String`：AVD 的使用者執行主機，`null` (如不適用)
`offset`	`Integer`：主機中 AVD 的裝置編號偏移量，`null` 如不適用
`attributes`	`MultiMap`：與目前叫用作業相關聯的屬性，用於將適用資訊傳遞至 GCE 執行個體，並新增為 VM 中繼資料
`logger`	`ITestLogger`：裝置啟動記錄的記錄位置。`ITestLogger`

傳回
`GceAvdInfo`	描述 GCE 執行個體的 `GceAvdInfo`。可能是 BOOT_FAIL 執行個體。

擲回
	com.android.tradefed.targetprep.TargetSetupError
`TargetSetupError`

startGce

public GceAvdInfo startGce ()

傳回
`GceAvdInfo`

擲回
`TargetSetupError`

startGce

public GceAvdInfo startGce (String ipDevice, 
                MultiMap<String, String> attributes)

嘗試啟動 GCE 執行個體。

參數
`ipDevice`	`String`：執行 AVD 的 GCE 執行個體初始 IP，`null`如不適用
`attributes`	`MultiMap`：與目前叫用作業相關聯的屬性，用於將適用資訊傳遞至 GCE 執行個體，並新增為 VM 中繼資料

傳回
`GceAvdInfo`	描述 GCE 執行個體的 `GceAvdInfo`。可能是 BOOT_FAIL 執行個體。

擲回
	com.android.tradefed.targetprep.TargetSetupError
`TargetSetupError`

startGce

public GceAvdInfo startGce (String ipDevice, 
                String user, 
                Integer offset, 
                MultiMap<String, String> attributes)

嘗試使用 Acloud 或 Oxygen 啟動 GCE 執行個體。

參數
`ipDevice`	`String`：執行 AVD 的 GCE 執行個體初始 IP，`null`如不適用
`user`	`String`：AVD 的使用者執行主機，`null` (如不適用)
`offset`	`Integer`：主機中 AVD 的裝置編號偏移量，`null` 如不適用
`attributes`	`MultiMap`：與目前叫用作業相關聯的屬性，用於將適用資訊傳遞至 GCE 執行個體，並新增為 VM 中繼資料

傳回
`GceAvdInfo`	描述 GCE 執行個體的 `GceAvdInfo`。可能是 BOOT_FAIL 執行個體。

擲回
	com.android.tradefed.targetprep.TargetSetupError
`TargetSetupError`

startMultiDevicesGce

public  startMultiDevicesGce ( buildInfos)

這個方法已淘汰。
更新主分支後，請移除此項目。

參數
`buildInfos`

傳回

擲回
`TargetSetupError`

startMultiDevicesGce

public  startMultiDevicesGce ( buildInfos, 
                MultiMap<String, String> attributes)

嘗試使用 Oxygen 啟動多部裝置的 GCE 執行個體。

參數
`buildInfos`	：`ERROR(/List)`
`attributes`	`MultiMap`：與目前叫用作業相關聯的屬性

傳回
	描述 GCE Avd 資訊的 `ERROR(/List)`。

擲回
`TargetSetupError`

受保護的方法

buildShutdownCommand

protected static  buildShutdownCommand (File config, 
                TestDeviceOptions options, 
                String instanceName, 
                String hostname, 
                boolean isIpPreconfigured)

參數
`config`	`File`
`options`	`TestDeviceOptions`
`instanceName`	`String`
`hostname`	`String`
`isIpPreconfigured`	`boolean`

傳回

extractInstanceName

protected String extractInstanceName (String bootupLogs)

從 GCE 開機記錄擷取執行個體名稱。搜尋「name」：「gce-」模式，擷取名稱。我們從記錄檔中擷取資訊，而非結果檔案，因為在 GCE 啟動失敗時，嘗試的執行個體名稱不會顯示在 JSON 中。

參數
`bootupLogs`	`String`

傳回
`String`