这个品类的数据长什么样
焦煤财报数据主要来源于境内外交易所公开披露的上市公司定期报告、煤炭行业协会发布的监测数据集。更新节奏分为两类：季度财报每季度末后30日内完成更新，年度财报每年度末后120日内更新，配套的行业供需数据每日更新。公开文档以PDF格式的定期报告与结构化JSON数据集为主，核心字段包含报告期、焦煤实际产量、内销外销数量、加权平均售价、单位生产成本等，产量单位为万吨，售价单位为元/吨，部分字段附带同比环比变化幅度。
这些特征在「HTTP 接口与外部系统」这一环带来什么约束
焦煤财报数据的品类限定性、固定更新周期与多格式特征，对HTTP接口与外部系统集成带来多项约束。需在接口请求中加入品类过滤参数，限定仅拉取焦煤相关数据，避免混入其他煤炭品类数据。按报告期范围查询的接口需支持报告期字段的精确匹配与区间筛选，适配定期财报的更新节奏。同时需兼容结构化API数据与非结构化PDF财报文档的拉取，配置不同的请求头与解析规则。另外，焦煤配套行业数据更新频次较高，需在外部系统中设置合理的缓存过期时长，平衡数据时效性与请求负载。
配置怎么定
| 配置项 | 建议取法 | 这样取的依据 |
|---|---|---|
external_api_filter | {"coal_type": "metallurgical_coal", "data_type": "financial_report"} | 焦煤财报需限定品类与数据类型，避免拉取到其他煤炭品类或非财报数据 |
external_api_timeout | 600 秒 | 焦煤年度财报PDF体积较大，完整拉取与解析需要较长响应时间 |
PARSE_FILE_MAX_SIZE | 20 MB | 公开披露的焦煤上市公司财报PDF通常不超过20 MB，超出阈值会触发接口拦截 |
cache_ttl_external_data | 86400 秒 | 焦煤行业配套供需数据每日更新，缓存一天可平衡时效性与请求频率 |
retry_count_on_fail | 3 次 | 交易所披露接口存在临时波动，重试可降低单次请求失败概率 |
response_field_mapping | {"产量": "output", "售价": "avg_price", "报告期": "report_date"} | 适配焦煤财报字段的行业术语映射，确保外部系统字段一致性 |
本页给出的参数取值均为常规建议，用于确定配置的起点。实际取值受材料形态、数据量与业务规则影响，具体问题需具体分析，建议在自有样本上实测后再定。
容易做错的三处
- 现象：接口请求返回
500 do request failed: Post "https://xxx" tls: failed to verify certificate，原因：未配置外部接口的TLS证书校验规则，或证书过期、域名不匹配，导致HTTPS请求被拦截。 - 现象：外部系统定时拉取焦煤财报数据时，出现大量异常请求导致配额耗尽，原因：未设置请求频率限制，未区分财报数据的更新时段，非工作时段仍触发重复拉取。
- 现象：解析焦煤财报文档后，核心产量字段为空，原因：未配置品类过滤参数，拉取到了其他煤炭品类的非匹配数据，导致字段解析失败。
怎么确认配好了
- 发起一次模拟请求，携带预设的过滤参数，检查返回结果仅包含焦煤相关财报数据。
- 上传一份公开的焦煤财报PDF文件，核对解析后提取的字段与配置的映射规则一致。
- 查看系统请求日志，确认请求频率符合预设的限制规则，无异常的高频请求。
- 触发一次超出超时阈值的请求，确认系统会返回明确的超时提示，不会无响应。
问题素材取自公开社区提问（2026-09-11 去重 4,834 条）。文中的配置项名称与取值区间需以所用版本的实际界面与文档为准；本页核验日 2026-09-14，当时的最新发布版本为 FastGPT v4.17.0。