Updated on 2024-08-09 GMT+08:00

Installing an APK

Function

This asynchronous API is used to install APKs on cloud phones. The system downloads specified APKs and installs them on the cloud phones. To install a single-APK application, run the install command. Only one APK can be installed at a time. If multiple APKs are specified at a time, only the first APK will be successfully installed. To install a multiple-APK application, run the install-multiple command to install multiple APKs (a single APK is split into multiple APKs). Only multiple APKs of the same application can be installed at a time. Before calling this API, ensure that the CPH service has been authorized to operate OBS buckets. For details, see Delegating CPH to Operate OBS Buckets.

  • The management plane performance is limited. Executing ADB commands in batches on the same cloud phone server blocks the execution of other tasks on the cloud phone.

  • You are advised to install APKs by developing an app store. You can only install an APK up to 2 GB in an OBS bucket on a cloud phone. If an APK exceeds 2 GB, an error message will be returned.

URI

POST /v1/{project_id}/cloud-phone/phones/commands

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Specifies the project ID.

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

Specifies the user token. It can be obtained by calling an Identity and Access Management (IAM) API. The value of X-Subject-Token in the response header is the user token.

Table 3 Request body parameters

Parameter

Mandatory

Type

Description

command

Yes

String

To install a single APK, set this parameter to install. To install multiple APKs, set this parameter to install-multiple.

content

Yes

String

Specifies the APK file in the specified OBS bucket. (The APK file must be uploaded to the specified bucket in advance.) Only letters, digits, underscores (_), periods (.), slashes (/), colons (:), and hyphens (-) are allowed. Only .apk files can be pushed.

In single-APK scenarios, only one APK file can be installed, and the maximum length is 1,024 bytes. In multi-APK scenarios, a maximum of 50 APK files separated by spaces can be installed, and the maximum length is 8,100 bytes. example: obs://obs-bucket-name/obs-file-path/file.apk

phone_ids

No

Array of strings

Specifies the ID list of cloud phones. This parameter is mandatory when there is no parameter server_ids. If there is parameter server_ids, set phone_ids only.

server_ids

No

Array of strings

Specifies the ID list of cloud phone servers. This parameter is mandatory when there is no parameter phone_ids. If there is parameter phone_ids, set phone_ids only.

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter

Type

Description

request_id

String

Specifies the unique request ID.

jobs

Array of PhoneJob objects

Specifies the task list.

Table 5 PhoneJob

Parameter

Type

Description

phone_id

String

Specifies the unique ID of a cloud phone. This parameter is contained in tasks related to cloud phones.

job_id

String

Specifies the unique ID of a task.

error_code

String

Specifies the error code.

error_msg

String

Specifies the error message.

Example Requests

  • Installing an APK file on cloud phones listed in phone_ids

    POST https://{CPH Endpoint}/v1/{project_id}/cloud-phone/phones/commands
    
    {
      "command" : "install",
      "content" : "-t -r obs://push-bucket/my_apps/test.apk",
      "phone_ids" : [ "1234567b8bab40ffb711234cb80d0234", "1678567b8bab40f93711234cb80d0764" ]
    }
  • Installing APK files on cloud phones in phone_ids

    POST https://{CPH Endpoint}/v1/{project_id}/cloud-phone/phones/commands
    
    {
      "command" : "install-multiple",
      "content" : "-t -r obs://push-bucket/my_apps/test_part1.apk obs://push-bucket/my_apps/test_part_2.apk obs://push-bucket/my_apps/test_part3.apk",
      "phone_ids" : [ "1234567b8bab40ffb711234cb80d0234", "1678567b8bab40f93711234cb80d0764" ]
    }

Example Responses

Status code: 200

OK

{
  "request_id" : "6837531fd3f54550927b930180a706bf",
  "jobs" : [ {
    "phone_id" : "1234567b8bab40ffb711234cb80d0234",
    "job_id" : "1564567b8bab40f34711234cb80d0123"
  }, {
    "phone_id" : "1678567b8bab40f93711234cb80d0764",
    "job_id" : "1564567b8bab40f34711234cb80d5678"
  } ]
}

Status Codes

Status Code

Description

200

OK

Error Codes

See Error Codes.