Files

杨柳杰 b450b512a2 init: mipu-open 对外开放项目统一管理仓库

- 添加 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>

2026-05-04 12:16:08 +08:00

4.0 KiB

Raw Blame History

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 字段包裹。

示例 - 有结果（搜索）：

{
  "itineraries": [
    {
      "itineraryId": "xxx",
      "outbound": {
        "segments": [...]
      },
      "price": {
        "total": 1200.00
      }
    }
  ],
  "sessionId": "session-xxx"
}

示例 - 有结果（预订）：

{
  "bookingId": "BK123456",
  "status": "HOLD",
  "expiryTime": "2025-01-20T12:00:00Z"
}

无结果（请求未找到或已过期）

当异步请求不存在或已过期时，返回 404 错误。

判断方式：响应体中 code: 404

示例 - 无结果：

{
  "code": 404,
  "msg": "Not found"
}

可能原因：

requestId 不存在
请求已过期（超过 24 小时）
请求属于其他租户（clientCode 不匹配）

请求仍在处理中

当异步请求仍在处理中时，会返回处理中的状态。

示例 - 处理中：

{
  "code": 202,
  "msg": "Processing",
  "requestId": "abc123-def456"
}

完整示例

请求示例

curl -X GET "https://api.example.com/async/query/abc123-def456" \
  -H "client-key: your-client-key" \
  -H "client-secret: your-client-secret"

响应示例（有结果）

{
  "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"
}

响应示例（无结果）

{
  "code": 404,
  "msg": "Not found"
}

常见问题

Q: 如何获取 requestId？

A: 当异步调用API返回 code: 202 时，响应中会包含 requestId 字段。

{
  "code": 202,
  "msg": "Async request accepted",
  "requestId": "abc123-def456"
}

Q: 结果会保留多久？

A: 异步请求的结果会保留 24 小时，超时后自动删除。

Q: 可以查询其他租户的请求吗？

A: 不可以。接口会根据认证信息中的 clientCode 进行租户隔离，只能查询本租户的请求。

Q: 建议的轮询策略是什么？

A: 建议每隔 2-5 秒查询一次，最多查询 10 次。如果 10 次后仍未获取结果，可能是航司响应较慢，建议稍后重试。

4.0 KiB Raw Blame History Unescape Escape