Dai0814
139 lines
4.6 KiB
Markdown
139 lines
4.6 KiB
Markdown
---
|
|
title: 白名单转发
|
|
description: 通过 apiv3.5iot.cn 访问中国移动物联网能力开放平台 V5 接口
|
|
outline: deep
|
|
---
|
|
|
|
# 白名单转发
|
|
|
|
本目录说明如何通过 `apiv3.5iot.cn` 访问中国移动物联网能力开放平台 V5 接口。平台仅提供安全代理转发，不改变中国移动 V5 接口的请求方法、请求参数、响应结构和业务语义。
|
|
|
|
## 服务地址
|
|
|
|
客户侧统一使用：
|
|
|
|
```text
|
|
https://apiv3.5iot.cn
|
|
```
|
|
|
|
V5 接口的请求路径保持与中国移动官方接口一致，将官方域名替换为平台域名即可：
|
|
|
|
```text
|
|
https://apiv3.5iot.cn/v5/{官方接口路径}
|
|
```
|
|
|
|
例如，官方接口路径为 `/v5/ec/query/sim-basic-info` 时，客户侧请求路径为：
|
|
|
|
```http
|
|
POST https://apiv3.5iot.cn/v5/ec/query/sim-basic-info
|
|
```
|
|
|
|
平台会将该请求转发至：
|
|
|
|
```text
|
|
https://api.iot.10086.cn/v5/ec/query/sim-basic-info
|
|
```
|
|
|
|
> [!IMPORTANT] 使用 POST 时务必携带 JSON 请求体
|
|
> 中国移动 V5 接口对 `POST` 只接受 JSON 格式。通过代理请求时必须设置
|
|
> `Content-Type: application/json`，并在请求体中传入参数；
|
|
> 未带该请求头或使用表单编码（`application/x-www-form-urlencoded`）会返回
|
|
> `{"status":"11012","message":"POST请求仅支持JSON格式","result":[]}`。
|
|
>
|
|
> 若使用 `GET`，则以 Query 参数传参，无需设置 `Content-Type`。
|
|
|
|
## 调用前准备
|
|
|
|
调用 V5 业务接口前，需要先从平台取得以下信息：
|
|
|
|
| 参数 | 说明 |
|
|
| --- | --- |
|
|
| `appid` | 第三方应用唯一标识 |
|
|
| `password` | 应用密钥 |
|
|
| `transid` | 按官方规则生成的事务编码 |
|
|
| `token` | 通过共享 Token 接口获取的运营商令牌 |
|
|
|
|
其中 `transid` 由客户生成，通常遵循 `appid + YYYYMMDDHHMISS + 8位数字序列`；中国移动通常不校验此事务编号。具体规则及字段约束以中国移动当前发布的接口文档为准。
|
|
|
|
|
|
|
|
## 业务接口示例
|
|
|
|
以下接口字段摘自中国移动 V5 接口清单，用于说明代理路径的写法。完整接口、字段、错误码和版本变更请以官方文档为准。
|
|
|
|
### 单卡基本信息查询
|
|
|
|
```http
|
|
POST https://apiv3.5iot.cn/v5/ec/query/sim-basic-info
|
|
```
|
|
|
|
请求参数：
|
|
|
|
| 参数 | 类型 | 说明 |
|
|
| --- | --- | --- |
|
|
| `transid` | string | 事务编码 |
|
|
| `token` | string | V5 Token |
|
|
| `msisdn` | string | 物联卡号码 |
|
|
| `iccid` | string | ICCID；与 `msisdn`、`imsi` 按官方规则选择 |
|
|
| `imsi` | string | IMSI |
|
|
|
|
请求示例：
|
|
|
|
```json
|
|
{
|
|
"transid": "113712264334542026051515200001000",
|
|
"token": "c5e1cad63e654237052be9908f989bf3515b3bdaeca904dd2e904061b65e8153",
|
|
"iccid": "898608501624D0000009"
|
|
}
|
|
```
|
|
|
|
响应主要字段：
|
|
|
|
| 参数 | 类型 | 说明 |
|
|
| --- | --- | --- |
|
|
| `status` | string | `0` 表示成功，非 `0` 表示失败 |
|
|
| `message` | string | 错误或提示信息 |
|
|
| `result` | array | 查询结果 |
|
|
| `result[].msisdn` | string | 物联卡号码 |
|
|
| `result[].iccid` | string | ICCID |
|
|
| `result[].imsi` | string | IMSI |
|
|
| `result[].activeDate` | string | 首次激活日期 |
|
|
| `result[].openDate` | string | 开卡时间 |
|
|
|
|
响应示例：
|
|
|
|
```json
|
|
{
|
|
"status": "0",
|
|
"message": "正确",
|
|
"result": [
|
|
{
|
|
"msisdn": "1442206200009",
|
|
"imsi": "460240406200009",
|
|
"iccid": "898608501624D0000009",
|
|
"activeDate": "2025-03-26 15:49:50",
|
|
"openDate": "2025-03-13 16:52:10",
|
|
"remark": ""
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
|
|
|
|
## 请求与响应约定
|
|
|
|
- V5 接口支持的请求方法、参数位置（Query 或 Form）、参数格式和字段大小写均以中国移动官方文档为准。
|
|
- `GET` 与 `POST` 均可通过本代理访问。使用 `POST` 时**必须**设置 `Content-Type: application/json` 并携带 JSON 请求体，否则返回 `11012`；使用表单编码亦不被接受。
|
|
- 代理会以平台固定出口地址访问中国移动，因此客户端侧的来源 IP 无需加入中国移动白名单；请勿在请求中自行添加 `X-Forwarded-For`、`X-Real-IP` 等来源标识请求头，中国移动会依据其判定 IP 鉴权，携带非白名单地址将返回 `12003`。
|
|
- 平台不将 V5 响应包装成 iotLCM V3 的 `code/message/data` 结构，客户应直接按照中国移动 V5 响应结构解析。
|
|
- 运营商 Token 具有有效期，收到 Token 失效类错误后应重新获取，不建议长期缓存。
|
|
|
|
## 官方资料
|
|
|
|
接口完整清单、参数定义、返回示例、错误码和 SDK 示例请参阅：
|
|
|
|
[中国移动物联网能力开放平台 V5 接口文档下载页面](https://api.iot.10086.cn/api/index.html#/resourceCenter/docDownload)
|
|
|
|
平台代理入口仅替换访问域名，不替代中国移动官方接口规范。
|