# API迁移指南

本文主要介绍了信鸽免费版本到腾讯云版本的接口迁移说明，包括 V3 和 V2 的推送接口、账号接口和标签接口的差异。

## 请求域名地址变动说明

**请求参数变动说明**

| 协议字段              | 字段含义说明 | 变动说明                                                                                                                                |
| ----------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| openapi.xg.qq.com | 域名     | <p>请根据购买的集群选择对应的域名地址：<br>1. 广州集群：api.tpns.tencent.com<br>2. 中国香港集群：api.tpns.hk.tencent.com<br>3. 新加坡集群：api.tpns.sgp.tencent.com</p> |

## V3 接口协议变动说明

[腾讯云版本 V3 接口协议格式](https://cloud.tencent.com/document/product/548/39061)对比[免费版本V3接口协议格式](https://xg.qq.com/docs/server_api/v3/rest_api_summary.html)基本相同。 协议中部分字段格式以及命名有变化，具体差异如下：

### 鉴权方式

免费版本使用 `AppId + SecretKey` 进行 `Basic Auth` 鉴权。([免费版本鉴权说明](https://xg.qq.com/docs/server_api/v3/rest_api_summary.html#%E9%89%B4%E6%9D%83%E6%96%B9%E5%BC%8F))

腾讯云版本使用 `AccessId + SecretKey` 进行 `Basic Auth` 鉴权。([腾讯云版本鉴权说明](https://cloud.tencent.com/document/product/548/39062))

> **腾讯云版本没有对应 AppId 字段， 需要使用对应的应用 id `AccessId` 和密钥 `SecretKey` 进行鉴权**。

### 推送接口

[腾讯云版本推送接口协议](https://cloud.tencent.com/document/product/548/39064) 格式和 [免费版本](https://xg.qq.com/docs/server_api/v3/push_api_v3.html) 基本相同, 主要区别如下:

**请求参数变动说明**

| 协议字段            | 字段含义说明                     | 免费版                                                                                                                         | 腾讯云版                    |
| --------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| custom\_content | Android 推送自定义参数            | 字段格式： json                                                                                                                  | 字段格式：需要序列化为 json string |
| custom          | iOS 推送自定义参数                | 字段格式： json                                                                                                                  | 字段格式：需要序列化为 json string |
| push\_id        | 账号列表推送和设备列表推送时，需要填写的推送任务ID | <p>账号列表推送和设备列表推送时，<br>第一次推送该值填0，系统会创建<br>对应的推送任务，并且返回对应的<br>pushid：123，后续推送push\_id填<br>123(同一个文案）表示使用与123 id 对应的文案进行推送</p> | 不再支持该字段对应功能             |

### 账号绑定接口

[腾讯云版本账号绑定协议格式](https://cloud.tencent.com/document/product/548/39070) 和 [免费版本](https://xg.qq.com/docs/server_api/v3/account-api.html) 完全相同，无需特别改动。

### 账号查询接口

[腾讯云版本账号查询协议格式](https://cloud.tencent.com/document/product/548/39071) 和 [免费版本](https://xg.qq.com/docs/server_api/v3/account-api.html#%E8%B4%A6%E5%8F%B7-%E8%AE%BE%E5%A4%87%E7%BB%91%E5%AE%9A%E6%9F%A5%E8%AF%A2%EF%BC%88%E6%89%B9%E9%87%8F%E6%93%8D%E4%BD%9C%EF%BC%89) 基本相同，主要区别如下：

**响应参数变动说明**

| 协议字段      | 字段含义说明 | 变动说明           |
| --------- | ------ | -------------- |
| ret\_code | 操作返回码  | 字段名变更为 retCode |
| err\_msg  | 操作响应消息 | 字段名变更为 errMsg  |

### 标签绑定接口

[腾讯云版本标签绑定协议格式](https://cloud.tencent.com/document/product/548/39067) 和 [免费版本](https://xg.qq.com/docs/server_api/v3/tag_api_v3.html) 基本相同，主要区别如下：

**请求参数变动说明**

| 协议字段             | 字段含义说明                                                               | 免费版                                                                                 | 腾讯云版                                                             |
| ---------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| tag\_token\_list | <p>当进行标签和设备批量绑定/解绑时，提供需要绑定/解绑<br>的标签设备列表，operator\_type =9,10时必填</p> | 字段格式：\[\["tag1","token1"]，\["tag2","token2"]]，每个对里面标签在前，token在后， 列表中每个元素为 jsonArray | 字段格式：\[{"tag":"tag123", "token":"token123"}]，列表中每个原始为 jsonObject |

### 返回码

腾讯云版本错误码是一套全新的返回码，和免费版本不同。\
&#x20;免费版返回码定义参考：[免费版返回码](https://xg.qq.com/docs/server_api/v3/push_api_v3.html#%E9%94%99%E8%AF%AF%E7%A0%81)\
&#x20;腾讯云版返回码定义参考：[腾讯云版返回码](https://cloud.tencent.com/document/product/548/39080)<br>

## V2 接口协议变动说明

**腾讯云版本不再支持V2 协议接口**

V2 版本对应的V3 版本接口参考如下：

| V2接口     | V2接口url                          | V3 接口          | V3 接口url       | 接口定义说明                                                           |
| -------- | -------------------------------- | -------------- | -------------- | ---------------------------------------------------------------- |
| 全量推送     | /v2/push/all\_device             | 推送接口           | /v3/push/app   | 参考[推送接口文档](https://cloud.tencent.com/document/product/548/39064) |
| 标签推送     | /v2/push/tags\_device            | 推送接口           | /v3/push/app   | 参考[推送接口文档](https://cloud.tencent.com/document/product/548/39064) |
| 账号群推     | /v2/push/account\_list           | 推送接口           | /v3/push/app   | 参考[推送接口文档](https://cloud.tencent.com/document/product/548/39064) |
| 设备单推     | /v2/push/single\_device          | 推送接口           | /v3/push/app   | 参考[推送接口文档](https://cloud.tencent.com/document/product/548/39064) |
| 账号单推     | /v2/push/single\_account         | 推送接口           | /v3/push/app   | 参考[推送接口文档](https://cloud.tencent.com/document/product/548/39064) |
| 超大批量账号推送 | /v2/push/account\_list\_multiple | 不支持，可使用号码包推送替代 |                |                                                                  |
| 超大批量设备推送 | v2/push/device\_list\_multiple   | 不支持，可使用号码包推送替代 |                |                                                                  |
| 批量新增标签   | /v2/tags/batch\_set              | 标签绑定接口         | /v3/device/tag | 参考[标签接口文档](https://cloud.tencent.com/document/product/548/39067) |
| 批量删除标签   | /v2/tags/batch\_del              | 标签绑定接口         | /v3/device/tag | 参考[标签接口文档](https://cloud.tencent.com/document/product/548/39067) |