Help Center/ KooPhone/ API Reference/ APIs/ Application management/ Installing an App on an Instance

Updated on 2025-11-24 GMT+08:00

View PDF

Installing an App on an Instance

Function

Call this API to install applications in batches on a cloud phone instance. When this API is called, the value of fast_install determines whether the applications are installed in common mode or quick mode.

The API returns the task_id of the current installation task. The task_id has a fixed prefix ZGCA.

You can call the GetTask instance execution task query API to query the execution result based on the returned task ID.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

If you are using role/policy-based authorization, see Permissions Policies and Supported Actions for details on the required permissions.

If you are using identity policy-based authorization, the following identity policy-based permissions are required.

Action	Access Level	Resource Type (*: required)	Condition Key	Alias	Dependencies
koophone:cloudphoneResource:instanceAppInstall	Write	cloudphoneResource *	-	-	-

URI

POST /v1/instances/app/install

Request Parameters

**Table 1** Request header parameters
Parameter	Mandatory	Type	Description
x-request-id	No	String	Unique ID of a request.
x-Auth-Token	No	String	Tenant-level token.

**Table 2** Request body parameters
Parameter	Mandatory	Type	Description
fast_install	No	String	Installation type. 0: common installation 1: quick installation
object_name	Yes	String	Name of the application package after installation. A package name can contain a maximum of 100 characters, for example, com.tencent.mm.
file_name	Yes	String	File name (suffix included). The value can contain a maximum of 100 characters, for example, meituan.apk.
object_version	Yes	String	Application version. The value can contain a maximum of 100 characters, for example, 8.0.58.
object_size	Yes	String	Application size. Example: 120 (unit: MB)
biz_type	Yes	String	Installation package type. The value can contain a maximum of 64 characters, for example, apk. Currently, only APK applications can be installed.
content_type	Yes	String	Transmission mode. The value can contain a maximum of 64 characters. 1: OBS. Currently, only OBS download is supported. Example: application/octet-stream
content_md5	Yes	String	Verify the MD5 value of the APK file. This parameter can be left empty. It is optional and can contain a maximum of 200 characters.
install_package_url	Yes	String	OBS download URL of the APK package. The value can contain a maximum of 2000 characters.
instance_id_list	Yes	Array of strings	Cloud phone instance list. A single instance can contain a maximum of 32 characters, and the list can contain a maximum of 100 columns.

Response Parameters

Status code: 200

**Table 3** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error message.
data	RmInstallAppResp object	Application installation result.

**Table 4** RmInstallAppResp
Parameter	Type	Description
data	RmInstallAppDataResult object	Execution results.

**Table 5** RmInstallAppDataResult
Parameter	Type	Description
cmd_jobs	Array of CmdJob objects	Command task.
task_id	String	Task ID.

**Table 6** CmdJob
Parameter	Type	Description
instance_id	String	Instance list.
job_id	String	Asynchronization command task ID.

Status code: 400

**Table 7** Response body parameters
Parameter	Type	Description
error_code	String	0: successful. KOOPHONE.API.1000: The request parameter is incorrect. KOOPHONE.API.1001: Insufficient instance permissions. KOOPHONE.API.3008: The installation type parameter fast_install in the request is incorrect. KOOPHONE.API.62005: The app package already exists. KOOPHONE.API.62006: The app package size is not a digit. KOOPHONE.API.62006: The app package is too large. KOOPHONE.API.62016: The total size of application packages uploaded by the tenant exceeds the upper limit. KOOPHONE.API.3009: Failed to query the phone ID. KOOPHONE.API.9999: Internal service error.
error_msg	String	Error message.

Example Requests

Request parameters for installing an application on an instance.

/v1/instances/app/install

{
  "fast_install" : 1,
  "object_name" : "com.tencent.mm",
  "file_name" : "meituan.apk",
  "object_version" : "8.0.58",
  "object_size" : 120,
  "biz_type" : "apk",
  "content_type" : "application/octet-stream",
  "content_md5" : "fghfg",
  "install_package_url" : "https://obs-kpxa-zg.obs.cn-north-7.ulanqab.huawei.com:443/chp_admin/sh/KooPhone/1943225155684069378/1752229415749-2-com.tencent.mm.apk?AccessKeyId=HSTAZ7UE1341BOE861H2&Expires=1753252931&x-obs-security-token=hQpjbi1ub3J0aC03AQAABElIU1RBWjdVRTEzNDFCT0U4NjFIMo-pbpW_du_lXkPTraoMwCYVql1frNdxH_jI3n5jbQHT6gQxKRmZB9zIy8W11u7BnLAZQnxrX8SDIZQV1jvlf9HQbIdvncUjU4YhVximnMUckrYQEDlTUYjrXKxG9bXYeAHt66g7iODBfCRVLvx1jUkA4thsItjcQ-iPGR20FBi2qbk_AF5iOGT0Ig72UjqIVYo_JTbkDWRiAUr4uludn84f_CgYjTPE025u8A_VO2l4yij3cl4TSRxdNxM2gpS8g3vDWpLCZ2UTYbej5dBzQs-yizVaCZmh-kN3A0JmWIvGpOvkSEhKYyWqAonB5UXzO954oj8Oso2nl2UahCVlUtgkGoxMaufkABN_4odeQOFnTYUyxb01aGD3Sv_UQSA_9Tnmy71Hp3ASq6mxF3xLQfrDzDM9Yk0FkZ4t-DQ5FhfQ22L8bR9ru_bmIS6y9XlPC5gxmLp-2APJpUQMDn703Pyr7us4cc-iTA3MiB_rFywCidsDCnw4uwnBwKzvz9qXNhBrNMyvPHSphqT2TsuGaU_-0x_y8KFBdgnJQXLyM1mQY5I0eFOxA3H8WgOTJCL1oQ76Zkg-KXM7UjS_WWU-TFqSIhL-dauPadneL8kai1BS7bsIsg%3D%3D&Signature=BdSN1CfLprzjlaFUGFfnkU5d7lg%3D",
  "instance_id_list" : [ "XvH39QVW", "Vpp8rC4Y" ]
}

Example Responses

Status code: 200

Returned parameters of the instance installation application.

{
  "data" : {
    "data" : {
      "task_id" : "ZGCAorI8ocwK7U7_t0AfH26P-DjwDw8Yknf4",
      "cmd_jobs" : [ {
        "instance_id" : "XvH39QVW",
        "job_id" : "L0XM9bL0sFoKJo-6BEjFzN6ut2jsoH_1"
      }, {
        "instance_id" : "Vpp8rC4Y",
        "job_id" : "1564567b8bab40f34711234cb80d0123"
      } ]
    }
  },
  "error_code" : "0",
  "error_msg" : "OK"
}