b450b512a2
- 添加 mipu-api 作为 git submodule (Claude Code Skill) - 迁移 API 文档源文件到 docs/ 目录统一维护 - 添加 Gitea Actions 工作流：tag推送自动打包docs并发布Release - Skill 运行时自动从 mipu-open Release 下载最新文档 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
188 lines
4.0 KiB
Markdown
188 lines
4.0 KiB
Markdown
<!-- mipuyun-api-doc: async-query -->
|
||
# async/query - 异步查询
|
||
|
||
# 异步查询（async/query）API 说明文档
|
||
|
||
## 用户使用场景
|
||
|
||
> 本接口目的是：
|
||
> 当异步调用API返回code:202时，通过本接口查询异步请求的结果。
|
||
|
||
## 使用时机
|
||
|
||
> 当异步调用API返回 `code: 202` 时，表示请求已接收并正在后台处理。
|
||
> 此时响应中会包含 `requestId`，使用本接口查询处理结果。
|
||
|
||
## 性能指标
|
||
|
||
> - 响应速度：毫秒级（直接从缓存读取）
|
||
> - 请求频率QPS：无限制
|
||
> - 数据保留时间：24小时
|
||
|
||
## 请求说明
|
||
|
||
| **请求地址** | https://${endpoint}/async/query/{requestId} |
|
||
| --- | --- |
|
||
| **请求方法** | GET |
|
||
| **注意事项** | Header 必须带认证信息。 |
|
||
|
||
## 请求参数
|
||
|
||
### Header
|
||
|
||
| **参数名称** | **类型** | **是否必选** | **示例值** | **说明** |
|
||
| --- | --- | --- | --- | --- |
|
||
| client-key | String | 是 | xxxxx | 联系我们获取生产环境 key |
|
||
| client-secret | String | 是 | xxxxx | 联系我们获取生产环境 secret |
|
||
|
||
### 路径参数
|
||
|
||
| **参数名称** | **类型** | **是否必选** | **示例值** | **说明** |
|
||
| --- | --- | --- | --- | --- |
|
||
| requestId | String | 是 | abc123-def456 | 异步请求返回的 requestId |
|
||
|
||
## 响应说明
|
||
|
||
### 有结果（请求已处理完成）
|
||
|
||
当异步请求已处理完成，**直接返回原始响应数据**（不包裹在统一响应结构中）。
|
||
|
||
**判断方式**：响应体中直接包含业务数据字段（如 `itineraries`、`bookingId` 等），无 `code` 字段包裹。
|
||
|
||
**示例 - 有结果（搜索）**：
|
||
|
||
```json
|
||
{
|
||
"itineraries": [
|
||
{
|
||
"itineraryId": "xxx",
|
||
"outbound": {
|
||
"segments": [...]
|
||
},
|
||
"price": {
|
||
"total": 1200.00
|
||
}
|
||
}
|
||
],
|
||
"sessionId": "session-xxx"
|
||
}
|
||
```
|
||
|
||
**示例 - 有结果（预订）**：
|
||
|
||
```json
|
||
{
|
||
"bookingId": "BK123456",
|
||
"status": "HOLD",
|
||
"expiryTime": "2025-01-20T12:00:00Z"
|
||
}
|
||
```
|
||
|
||
### 无结果（请求未找到或已过期）
|
||
|
||
当异步请求不存在或已过期时，返回 404 错误。
|
||
|
||
**判断方式**：响应体中 `code: 404`
|
||
|
||
**示例 - 无结果**：
|
||
|
||
```json
|
||
{
|
||
"code": 404,
|
||
"msg": "Not found"
|
||
}
|
||
```
|
||
|
||
**可能原因**：
|
||
1. `requestId` 不存在
|
||
2. 请求已过期（超过 24 小时）
|
||
3. 请求属于其他租户（clientCode 不匹配）
|
||
|
||
### 请求仍在处理中
|
||
|
||
当异步请求仍在处理中时，会返回处理中的状态。
|
||
|
||
**示例 - 处理中**：
|
||
|
||
```json
|
||
{
|
||
"code": 202,
|
||
"msg": "Processing",
|
||
"requestId": "abc123-def456"
|
||
}
|
||
```
|
||
|
||
## 完整示例
|
||
|
||
### 请求示例
|
||
|
||
```bash
|
||
curl -X GET "https://api.example.com/async/query/abc123-def456" \
|
||
-H "client-key: your-client-key" \
|
||
-H "client-secret: your-client-secret"
|
||
```
|
||
|
||
### 响应示例（有结果）
|
||
|
||
```json
|
||
{
|
||
"itineraries": [
|
||
{
|
||
"itineraryId": "itinerary-001",
|
||
"outbound": {
|
||
"segments": [
|
||
{
|
||
"carrier": "CA",
|
||
"flightNumber": "CA123",
|
||
"origin": "PEK",
|
||
"destination": "SHA",
|
||
"departureTime": "2025-01-20T08:00:00",
|
||
"arrivalTime": "2025-01-20T10:00:00"
|
||
}
|
||
]
|
||
},
|
||
"price": {
|
||
"currency": "CNY",
|
||
"total": 1200.00
|
||
}
|
||
}
|
||
],
|
||
"sessionId": "session-xxx"
|
||
}
|
||
```
|
||
|
||
### 响应示例（无结果）
|
||
|
||
```json
|
||
{
|
||
"code": 404,
|
||
"msg": "Not found"
|
||
}
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
### Q: 如何获取 requestId？
|
||
|
||
A: 当异步调用API返回 `code: 202` 时，响应中会包含 `requestId` 字段。
|
||
|
||
```json
|
||
{
|
||
"code": 202,
|
||
"msg": "Async request accepted",
|
||
"requestId": "abc123-def456"
|
||
}
|
||
```
|
||
|
||
### Q: 结果会保留多久？
|
||
|
||
A: 异步请求的结果会保留 24 小时，超时后自动删除。
|
||
|
||
### Q: 可以查询其他租户的请求吗？
|
||
|
||
A: 不可以。接口会根据认证信息中的 clientCode 进行租户隔离，只能查询本租户的请求。
|
||
|
||
### Q: 建议的轮询策略是什么？
|
||
|
||
A: 建议每隔 2-5 秒查询一次，最多查询 10 次。如果 10 次后仍未获取结果，可能是航司响应较慢，建议稍后重试。
|