# 提交插桩任务

## 功能介绍

调用此接口提交插桩任务。插桩任务耗时与提交的so文件大小有关，例如22MB的so文件完成插桩任务大约需要4分钟。
> 说明
>
> 请勿频繁调用该接口，建议本次插桩任务结束后再调用该接口。

## 接口原型

|承载协议|HTTPS|
|-----|-----------------------------------------------------------------------|
|接口方向|开发者服务器 -> 华为服务器|
|接口方法|POST|
|接口URL|https://connect-api.cloud.huawei.com/api/gpos/binary/instrumentation|
|数据格式|* 请求：Content-Type: application/json * 响应：Content-Type: application/json|

## 请求参数

### Header

|参数|类型|必选(M)/可选(O)|说明|
|:------------|:-----|:----------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|Content-Type|string|M|固定取值为"application/json"。|
|client_id|string|M|客户端ID，即[创建API客户端](https://developer.huawei.com/consumer/cn/doc/games-guides/games-binary-optimization-agc-works-0000002342950440#section2939558155118)中生成的客户端ID。|
|Authorization|string|M|认证信息，格式为"Authorization: Bearer ${access_token}"，其中access_token为调用[获取Token](https://developer.huawei.com/consumer/cn/doc/games-references/games-api-binary-optimization-obtain-token-0000002408001421)接口返回的access_token。|
|projectId|string|M|在AppGallery Connect[创建项目和应用](https://developer.huawei.com/consumer/cn/doc/games-guides/games-binary-optimization-agc-works-0000002342950440#section210054711512)后的项目ID。最大长度20个字符。|

### Body

> 说明
>
> 在相同**packageName** 和**version** 的情况下，若待传文件的**objectId**和之前某次未执行失败的插桩任务传入的完全一样，则会直接返回之前已生成的插桩任务ID。

|参数|类型|必选(M)/可选(O)|说明|
|:----------|:------------------------------------------------------------------------------------------------------------------------------------|:----------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|soFileInfos|List<[InstrumentationSoInfo](#ZH-CN_TOPIC_0000002374241876__zh-cn_topic_0000001862646064_zh-cn_topic_0000001623654464_p121438156417)>|M|文件信息。最多20条。|
|packageName|string|M|原始so文件所在游戏的包名，与[创建项目和应用](https://developer.huawei.com/consumer/cn/doc/AppGallery-connect-Guides/binary-optimization-agc-works-0000001588520205#section210054711512)时保持一致。最大长度256个字符。|
|version|string|M|原始so文件所在游戏的版本号，例如"1.0.0"。最大长度64个字符。|
|note|string|O|插桩任务的备注信息，最大长度1024个字符。|

InstrumentationSoInfo参数说明

|参数|类型|必选(M)/可选(O)|说明|
|:---------|:-----|:----------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|soObjectId|string|M|原始so文件的对象ID，即调用[获取so文件上传地址](https://developer.huawei.com/consumer/cn/doc/AppGallery-connect-References/binary-optimization-obtain-url-0000001863302878)接口返回的objectId。最大长度512个字符。|
|portStart|int|O|工具包中trigger工具触发采集profile数据的端口号，请填写未被占用的端口号，默认端口号3040。端口号范围为1024到65535，且跟设备上使用的端口号不冲突。 > 说明 > * 若修改默认值，[采集profile数据](https://developer.huawei.com/consumer/cn/doc/AppGallery-connect-Guides/binary-optimization-profile-0000001569513905)时也要设置同样的端口号。 > * 每个so需要分别配置不同的端口号，否则在采集profile数据时，若同时采集，会有冲突。|

## 请求示例

```screen
POST /api/gpos/binary/instrumentation
Host: connect-api.cloud.huawei.com
Content-Type: application/json
client_id: ***
Authorization: Bearer ***
projectId: ***

{
     "soFileInfos": [
       {
          "soObjectId": "pvt_2/GameCenter_perf_900_9/2/v3/8VJBonG4T1CyxP88MM0IuQ/xxx.so",
          "portStart": 3041
        }
     ],
    "packageName": "com.test.company",
    "version": "1.0.0",
    "note":"任务备注信息"
}
```

## 响应参数

|参数|类型|必选(M)/可选(O)|说明|
|:---|:------------------------------------------------------------------------------------------------------------------------------------------|:----------|:-----------------------------------------------------------------|
|ret|[CommonRet](#ZH-CN_TOPIC_0000002374241876__zh-cn_topic_0000001862646064_zh-cn_topic_0000001623654464_p1170913233715)|M|包含返回码及描述信息的JSON字符串，格式为{"code":*retcode* , "msg": "*description*"}。|
|data|[SubmitBinaryInstrumentationResult](#ZH-CN_TOPIC_0000002374241876__zh-cn_topic_0000001862646064_zh-cn_topic_0000001623654464_p886916120356)|O|若调用成功，将返回插桩任务ID。|

CommonRet参数说明

|参数|类型|必选(M)/可选(O)|说明|
|:---|:-----|:----------|:---------------------------|
|code|int|O|[返回码](#section745914375139)。|
|msg|string|O|描述信息。|

SubmitBinaryInstrumentationResult参数说明

|参数|类型|必选(M)/可选(O)|说明|
|:------|:-----------|:----------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------|
|taskIds|List<string>|M|插桩任务ID列表，调用[获取插桩结果](https://developer.huawei.com/consumer/cn/doc/games-references/games-api-binary-optimization-get-pile-result-0000002408001433)接口即可查询任务信息。|

## 响应示例

```screen
{
    "ret": {
        "code": 0,
        "msg": "Success"
    },
    "data": {
        "taskIds": [
            "1402057803161487616"
        ]
    }
}
```

## 返回码

|code|msg|Description|
|:---|:----------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|0|Success.|成功。|
|1004|Unfinished task number has reached limit.|当前未完成的插桩任务数累计超过20个。|
|1012|file info num not match.|soObjectId传入错误，请检查与调用[获取文件上传地址](https://developer.huawei.com/consumer/cn/doc/AppGallery-connect-References/binary-optimization-obtain-url-0000001863302878#ZH-CN_TOPIC_0000001863302878__zh-cn_topic_0000001536629733_p59601167012)接口后返回的objectId是否一致。|
|3001|invalid parameters.|参数错误。|