Method: enterprises.devices.issueCommand

向裝置發出指令。傳回的 Operation 資源會在 metadata 欄位中包含 Command。使用取得作業方法取得指令的狀態。

HTTP 要求

POST https://androidmanagement.googleapis.com/v1/{name=enterprises/*/devices/*}:issueCommand

這個網址使用 gRPC 轉碼語法。

路徑參數

參數
name

string

裝置名稱，格式為 enterprises/{enterpriseId}/devices/{deviceId}。

要求主體

要求主體包含 Command 的例項。

回應主體

如果成功，回應主體會包含 Operation 的執行例項。

授權範圍

需要下列 OAuth 範圍：

  • https://www.googleapis.com/auth/androidmanagement

詳情請參閱 OAuth 2.0 總覽。

指令

指令。

JSON 表示法 
{
  "type": enum (CommandType),
  "createTime": string,
  "duration": string,
  "userName": string,
  "errorCode": enum (CommandErrorCode),
  "newPassword": string,
  "resetPasswordFlags": [
    enum (ResetPasswordFlag)
  ],

  // Union field params can be only one of the following:
  "clearAppsDataParams": {
    object (ClearAppsDataParams)
  },
  "startLostModeParams": {
    object (StartLostModeParams)
  },
  "stopLostModeParams": {
    object (StopLostModeParams)
  }
  // End of list of possible types for union field params.

  // Union field status can be only one of the following:
  "clearAppsDataStatus": {
    object (ClearAppsDataStatus)
  },
  "startLostModeStatus": {
    object (StartLostModeStatus)
  },
  "stopLostModeStatus": {
    object (StopLostModeStatus)
  }
  // End of list of possible types for union field status.
}
欄位
type

enum (CommandType)

指令的類型。
createTime

string (Timestamp format)

指令建立時間的時間戳記。時間戳記是由伺服器自動產生。

RFC3339 世界標準時間「Zulu」格式的時間戳記，精確度達奈秒單位，最多九個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
duration

string (Duration format)

指令有效的持續時間。如果裝置未在這個時間內執行指令，指令就會失效。如果未指定，則預設時間長度為 10 分鐘。沒有時間長度上限。

時間長度以秒為單位，最多可有 9 個小數位數，並應以「s」結尾，例如："3.5s"。
userName

string

擁有裝置的使用者資源名稱，格式為 enterprises/{enterpriseId}/users/{userId}。伺服器會根據傳送指令的裝置自動產生這項資訊。
errorCode

enum (CommandErrorCode)

如果指令失敗，系統會顯示用來說明失敗的錯誤代碼。當呼叫端取消指令時，系統不會設定此值。
newPassword

string

對於 RESET_PASSWORD 類型的指令，可選擇指定新密碼。注意：如果新密碼是數字，則在 Android 14 裝置上必須至少包含 6 個字元。否則指令會失敗並顯示 INVALID_VALUE。
resetPasswordFlags[]

enum (ResetPasswordFlag)

對於 RESET_PASSWORD 類型的指令，可選擇指定旗標。

聯集欄位 params。指令專屬參數。請注意，有些指令不會使用這個功能，特別是 LOCK、RESET_PASSWORD、REBOOT 和 RELINQUISH_OWNERSHIP。日後這些指令也可能會使用這個值。

如果設定了這個值，就必須避免設定 new_password 和 reset_password_flags 欄位。params 只能是下列其中一項：
clearAppsDataParams

object (ClearAppsDataParams)

CLEAR_APP_DATA 指令的參數，用於清除裝置上指定應用程式的資料。請參閱 ClearAppsDataParams。如果已設定此值，建議您不要設定 type。在這種情況下，伺服器會自動將其設為 CLEAR_APP_DATA。您也可以明確將 type 設為 CLEAR_APP_DATA。
startLostModeParams

object (StartLostModeParams)

START_LOST_MODE 指令的參數，可將裝置設為遺失模式。請參閱 StartLostModeParams。如果已設定此值，建議您不要設定 type。在這種情況下，伺服器會自動將其設為 START_LOST_MODE。您也可以明確將 type 設為 START_LOST_MODE。
stopLostModeParams

object (StopLostModeParams)

STOP_LOST_MODE 指令的參數，用於讓裝置退出遺失模式。請參閱 StopLostModeParams。如果已設定此值，建議您不要設定 type。在這種情況下，伺服器會自動將這個變數設為 STOP_LOST_MODE。您也可以明確將 type 設為 STOP_LOST_MODE。
聯集欄位 status。指令專屬的狀態。請注意，某些指令並未使用這個指令，特別是 LOCK、RESET_PASSWORD、REBOOT 和 RELINQUISH_OWNERSHIP。日後這些指令可能也會使用這個方法。status 只能是下列其中一項：
clearAppsDataStatus

object (ClearAppsDataStatus)

僅供輸出。CLEAR_APP_DATA 指令的狀態，可用於清除裝置中指定應用程式的資料。查看《ClearAppsDataStatus》。
startLostModeStatus

object (StartLostModeStatus)

僅供輸出。用於讓裝置進入遺失模式的 START_LOST_MODE 指令狀態。查看《StartLostModeStatus》。
stopLostModeStatus

object (StopLostModeStatus)

僅供輸出。讓裝置退出遺失模式的 STOP_LOST_MODE 指令狀態。查看《StopLostModeStatus》。

CommandType

指令類型。

列舉
COMMAND_TYPE_UNSPECIFIED 不允許此值。
LOCK 鎖定裝置，就像螢幕鎖定逾時一樣。
RESET_PASSWORD 重設使用者密碼。
REBOOT 重新啟動裝置。僅支援搭載 Android 7.0 (API 級別 24) 以上版本的完全受控裝置。
RELINQUISH_OWNERSHIP 從公司擁有的 Android 8.0 以上版本裝置中移除工作資料夾和所有政策，不再將裝置用於個人用途。與個人資料夾相關聯的應用程式和資料會保留。裝置確認指令後，就會從伺服器中刪除。
CLEAR_APP_DATA 清除指定應用程式的應用程式資料。這項功能適用於 Android 9 以上版本。請注意，應用程式可將資料儲存在其應用程式資料之外，例如外部儲存空間或使用者字典中。另請參閱 clearAppsDataParams。
START_LOST_MODE 將裝置設為遺失模式。僅支援完全受管理的裝置，或機構擁有的裝置 (含管理設定檔)。另請參閱 startLostModeParams。
STOP_LOST_MODE 讓裝置退出遺失模式。僅支援完全受管理的裝置，或機構擁有的裝置 (含管理設定檔)。另請參閱 stopLostModeParams。

CommandErrorCode

指令錯誤代碼。這是由伺服器填入的唯讀欄位。

列舉
COMMAND_ERROR_CODE_UNSPECIFIED 沒有錯誤。
UNKNOWN 發生不明錯誤。
API_LEVEL 裝置的 API 級別不支援這項指令。
MANAGEMENT_MODE 管理模式 (設定檔擁有者、裝置擁有者等) 不支援該指令。
INVALID_VALUE 指令含有無效的參數值。
UNSUPPORTED 裝置不支援指令。將 Android Device Policy 更新至最新版本後，或許就能解決這個問題。

ResetPasswordFlag

可用於 RESET_PASSWORD 指令類型的旗標。

列舉
RESET_PASSWORD_FLAG_UNSPECIFIED 系統會忽略這個值。
REQUIRE_ENTRY 在使用者輸入密碼之前，請勿允許其他管理員再次變更密碼。
DO_NOT_ASK_CREDENTIALS_ON_BOOT 請勿在裝置啟動時要求使用者提供憑證。
LOCK_NOW 重設密碼後鎖定裝置。

ClearAppsDataParams

與 CLEAR_APP_DATA 指令相關聯的參數，可用於清除裝置上指定應用程式的資料。

JSON 表示法 
{
  "packageNames": [
    string
  ]
}
欄位
packageNames[]

string

執行指令時會清除資料的應用程式套件名稱。

StartLostModeParams

與 START_LOST_MODE 指令相關聯的參數，可用於讓裝置進入遺失模式。如要將裝置設為遺失模式，必須提供至少一個參數 (不含機構名稱)。

JSON 表示法 
{
  "lostMessage": {
    object (UserFacingMessage)
  },
  "lostPhoneNumber": {
    object (UserFacingMessage)
  },
  "lostEmailAddress": string,
  "lostStreetAddress": {
    object (UserFacingMessage)
  },
  "lostOrganization": {
    object (UserFacingMessage)
  }
}
欄位
lostMessage

object (UserFacingMessage)

裝置處於遺失模式時，向使用者顯示的訊息。
lostPhoneNumber

object (UserFacingMessage)

裝置處於遺失模式並輕觸撥打給擁有者的按鈕時，系統會撥打的電話號碼。
lostEmailAddress

string

裝置處於遺失模式時，向使用者顯示的電子郵件地址。
lostStreetAddress

object (UserFacingMessage)

裝置處於遺失模式時，向使用者顯示的街道地址。
lostOrganization

object (UserFacingMessage)

在裝置處於遺失模式時向使用者顯示的機構名稱。

StopLostModeParams

這個類型沒有任何欄位。

與 STOP_LOST_MODE 指令相關聯的參數，可讓裝置退出遺失模式。

ClearAppsDataStatus

CLEAR_APP_DATA 指令的狀態，用於清除裝置中的指定應用程式資料。

JSON 表示法 
{
  "results": {
    string: {
      object (PerAppResult)
    },
    ...
  }
}
欄位
results

map (key: string, value: object (PerAppResult))

每個應用程式的結果，以及從套件名稱對應至相應清除結果。

這個物件中包含 "key": value 組合的清單，範例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。

PerAppResult

嘗試清除單一應用程式資料的結果。

JSON 表示法 
{
  "clearingResult": enum (ClearingResult)
}
欄位
clearingResult

enum (ClearingResult)

嘗試清除單一應用程式資料的結果。

ClearingResult

嘗試清除單一應用程式資料的結果。

列舉
CLEARING_RESULT_UNSPECIFIED 未指定結果。
SUCCESS 已成功清除這個應用程式的資料。
APP_NOT_FOUND 找不到這個應用程式，因此無法清除相關資料。
APP_PROTECTED 這個應用程式受到保護，因此無法清除這個應用程式的資料。舉例來說，如果應用程式需要對裝置功能至關重要，例如 Google Play 商店，就屬於這種情況。
API_LEVEL 裝置 API 級別不支援這個指令，因此無法清除這個應用程式的資料。

StartLostModeStatus

將裝置設為遺失模式的 START_LOST_MODE 指令狀態。

JSON 表示法 
{
  "status": enum (Status)
}
欄位
status

enum (Status)

狀態。詳情請參閱《StartLostModeStatus》。

狀態

狀態。詳情請參閱《StartLostModeStatus》。

列舉
STATUS_UNSPECIFIED 未指定。並未使用這個值。
SUCCESS 裝置已進入遺失模式。
RESET_PASSWORD_RECENTLY 管理員最近重設了裝置密碼，因此裝置無法進入遺失模式。
USER_EXIT_LOST_MODE_RECENTLY 使用者最近已退出遺失模式，因此裝置無法進入遺失模式。
ALREADY_IN_LOST_MODE 裝置已處於遺失模式。

StopLostModeStatus

讓裝置退出遺失模式的 STOP_LOST_MODE 指令狀態。

JSON 表示法 
{
  "status": enum (Status)
}
欄位
status

enum (Status)

狀態。詳情請參閱《StopLostModeStatus》。

狀態

狀態。詳情請參閱《StopLostModeStatus》。

列舉
STATUS_UNSPECIFIED 不明。系統不會使用這個值。
SUCCESS 裝置已退出遺失模式。
NOT_IN_LOST_MODE 裝置未處於遺失模式。