★ FEATURED ARTICLE 拟在建项目详情接口用于根据项目id与发布时间publishTime取回项目标题、正文与建设单位。它通常作为“先搜索、再取详情”链路中的第二步先用搜索接口拿到列表和每条记录的标识再逐条拉取详情。本文从零开始说明第一次调用需要准备什么、最小请求怎么发、返回值怎么看。适用场景与能力边界典型用途包括把项目列表中的条目展开成完整正文做结构化入库在业务系统中展示建设单位和项目概况对搜索结果做二次筛选时需要正文内容做关键词匹配。接口返回的核心是三个业务字段标题、正文、建设单位。它不做搜索、不做列表分页也不提供项目的实时进度更新。换句话说这个接口是“按标识取详情”输入必须来自搜索结果的id与publishTime。需要特别注意publishTime的作用它是定位记录的必要条件之一而不是可选装饰。只传id可能无法唯一定位或匹配失败具体约束以文档为准。参数名支持publishTime与publishtime两种写法大小写不敏感接入时按代码风格选用即可不必为此纠结。调用前的准备需要三样东西一个从搜索结果中拿到的id、对应的publishTime以及一个 API Key。API Key 在平台控制台中复制。鉴权方式是固定的在请求头中写Authorization: Bearer 你的Key。这是该接口推荐的鉴权形式不要依赖 Query 参数传 Key。请求方法为POST地址为https://v1.apizero.cn/api/planned-detail参数以 JSON 形式放在请求体中并设置Content-Type: application/json。最小请求curl 示例把YOUR_API_KEY替换为实际 Keyid与publishTime替换为搜索接口返回的对应值curl -X POST https://v1.apizero.cn/api/planned-detail \ -H Authorization: Bearer YOUR_API_KEY \ -H Content-Type: application/json \ -d {id: 123456, publishTime: 2024-06-15}若代码中习惯全小写也可写成curl -X POST https://v1.apizero.cn/api/planned-detail \ -H Authorization: Bearer YOUR_API_KEY \ -H Content-Type: application/json \ -d {id: 123456, publishtime: 2024-06-15}publishTime的格式日期字符串还是时间戳应与搜索接口返回值保持一致具体格式以文档为准。Python 接入示例下面封装一个函数把搜索结果的单条记录直接映射成详情请求参数避免手工拼字段时出错import os import requests def fetch_planned_detail(item: dict, api_key: str | None None) - dict: item 为搜索接口返回的单条记录需含 id 与 publishTime record_id item.get(id) publish_time item.get(publishTime) or item.get(publishtime) if not record_id or not publish_time: raise ValueError(记录缺少 id 或 publishTime无法取详情) url https://v1.apizero.cn/api/planned-detail body {id: record_id, publishTime: publish_time} headers {Content-Type: application/json} key api_key or os.environ.get(APIZERO_KEY) if key: headers[Authorization] fBearer {key} resp requests.post(url, jsonbody, headersheaders, timeout20) resp.raise_for_status() payload resp.json() if payload.get(code) ! 0: raise RuntimeError(f获取详情失败: code{payload.get(code)}, msg{payload.get(msg)}) return payload[data] # 假设 search_items 来自搜索接口 # for item in search_items: # detail fetch_planned_detail(item) # print(detail.get(title), detail.get(builder))把“取参”和“请求”拆开的写法在批量场景中很有用可以在循环外统一处理异常对单条失败做跳过与记录而不是中断整批任务。返回字段解读成功响应的code 0data内保留业务字段并额外附带fetched_at与api。字段含义如下名称与结构以文档为准字段含义title项目标题content项目正文builder建设单位fetched_at本次数据抓取时间api数据来源标识三个业务字段里content通常是长文本可能含换行与 HTML 片段入库前应做清洗。builder是建设单位名称可能存在多家单位并列或为空的情况读取时做空值判断。fetched_at与api是元信息用于标注数据新鲜度与来源建议随业务字段一起存储便于后续审计。一个实践提醒content的长度可能超出某些数据库字段的默认限制建表时用TEXT或LONGTEXT不要用VARCHAR(255)硬扛。常见错误与排查现象可能原因排查方向code非 0提示参数缺失未传publishTime或id为空检查请求体两个字段是否都有值code非 0提示鉴权失败未使用Authorization: Bearer或 Key 无效按固定格式补请求头code非 0提示未找到记录id与publishTime不匹配用搜索接口原始返回值重试HTTP 415 或不支持缺少Content-Type: application/json补上请求头HTTP 429超出调用频率控制并发QPS 以文档为准第三行是接入初期最常见的问题手工改写或截断了publishTime导致与记录不匹配。务必原样透传搜索接口的返回值。工程化注意事项先搜索后详情不要跳过链路。详情接口的入参完全依赖搜索结果的标识单独构造id没有意义。把两步封装成一个业务方法调用方只传查询条件即可。批量拉取要做节流。对列表逐条取详情时加固定间隔或使用带并发上限的线程池避免瞬时打满限流。失败条目记录下来稍后重试不要在同一批里无限重试。详情做持久化不要每次现拉。项目详情内容变化频率低取回后入库存储fetched_at可作为是否需要更新的判断依据。这也减少了重复请求。正文清洗单独抽函数。去 HTML 标签、压缩空白、统一编码这些处理在多个数据源场景下都会复用不要散落在业务流程里。Key 只在服务端。通过后端代理调用密钥不进入前端代码或移动端包体。参考文档接口文档接口地址
阅读完成 · 觉得有帮助？
