Method: enterprises.devices.issueCommand

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

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)

指令效期。如果裝置在這段期間內未執行，這個指令會失效。如未指定，預設時間長度為十分鐘。時間長度沒有上限。

時間長度以秒為單位，最多可有 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 裝置並未處於遺失模式。