在Coze里跟外部真实数据打交道HTTP请求节点几乎是绕不开的一环。今天直接用最典型的“天气API对接”场景把Coze HTTP请求节点的配置流程、参数传递、响应解析完整过一遍重点讲清楚动态参数到底怎么用。这个需求的典型场景是用户在智能体里问“北京今天冷不冷”“上海明天会下雨吗”我们让智能体去真实天气接口拉数据而不是让大模型凭训练数据瞎编。看完这篇你不仅能跑通一个固定的天气查询还能把城市名、查询单位全部做成动态参数做到任意城市、任意单位随手查。1. 选型与整体思路为什么是HTTP请求节点加天气API1.1 这个实战解决什么问题Coze智能体本身的能力边界在于“生成”和“理解”它不具备实时获取外部数据的能力。你要问它“今天天气怎么样”它只能根据训练时见过的历史信息给一个模糊回答甚至可能编造数据。这时候就需要通过HTTP请求节点让工作流主动去调用外部API把真实数据拉回来再交给大模型加工成自然语言。这个需求非常典型。天气数据是实时性要求极高的信息几乎每次查询答案都可能不同。用HTTP请求节点对接天气API是我做Coze工作流时最常用、也最适合新手入门的一类场景。它足够简单但也有几个必须搞清楚的坎API密钥怎么配、动态参数怎么传、返回的JSON怎么解析。把这三点吃透了往后对接任何外部接口——查快递、查汇率、查股票套路都是一模一样的。1.2 天气API怎么选选天气API是第一步也是很多人容易踩坑的地方。市面上的天气接口不少但拿来做Coze工作流教学我比较推荐心知天气。原因很直接它支持中文城市名直接查询比如location北京就能返回北京的天气数据不需要先调一个“城市编码转换接口”再查天气这对新手极其友好。我还对比过高德天气和和风天气。高德天气的优点是接口免费额度相对充足但它要求传入城市的adcode码比如北京是110000这意味着你必须先有一张城市编码表或者先调用它的地理编码接口把“北京”转成adcode再查天气链路长了一层新手容易绕晕。和风天气的免费版额度也还行但有些接口对QPS限制比较严格调试的时候时不时会碰到限流。心知天气在“查询方便”和“返回结构简单”这两个维度上最均衡适合作为教学案例。选型时有几个参数可以重点看是否支持中文城市名直查、返回字段是否包含实时温度和中英文天气描述、免费额度是否够个人使用、返回格式是不是标准JSON。这四个条件都满足才能真正做到“拿来就能用”。1.3 动态参数的设计思路所谓动态参数说人话就是不要把城市名写死在请求地址里而是让它成为一个“变量”由用户输入、上游节点或系统参数动态填充。这是整个实战的题眼也是从“跑通”到“能用”的关键分水岭。具体来说如果我在HTTP请求节点里把URL写成https://api.seniverse.com/v3/weather/now.json?location北京key你的密钥那这个工作流就废了因为每个城市都要单独做一个节点。正确做法是在“开始”节点里定义一个输入参数city然后在HTTP请求节点的参数配置里引用这个city变量。用户问“上海天气”我们就往city里传“上海”请求发出时Coze会自动把“上海”拼到URL后面一次工作流就能服务所有城市。这种“参数抽离”的思想在整个Coze工作流设计里非常通用。不只是天气API任何需要用户输入条件才能查询的外部接口都建议走这个模式。后面我会把从“写死参数”改造成“动态参数”的具体步骤完整演示一遍。2. 开工前准备创建工作流、拿到密钥、理解节点结构2.1 新建Coze工作流登录Coze平台后进入自己的工作空间点击“新建工作流”。新版的Coze工作流编辑器是一块画布左侧是节点库中间是编排区域右上角可以设置模型和系统提示词。第一次进来可能会觉得节点连线有点眼花其实只需要关注几个基础节点就行开始节点、结束节点以及今天的主角——HTTP请求节点。开始节点是整条工作流的入口所有外部传入的参数都要先在这里定义好。结束节点是输出口决定最终返回给智能体的内容格式。这两个节点默认就有不需要额外拖拽。HTTP请求节点一般在“节点库”的“工具”或“网络请求”分类下面不同版本的位置可能略有出入但名称一定叫“HTTP请求”或“HTTP Request”。我个人建议新建工作流后先把节点布局理顺了再动手配置开始节点放最左边HTTP请求节点放中间靠左结束节点放最右边后面如果还要加代码节点或大模型节点就往右侧继续接。把基础拓扑先摆好后续调试会清爽很多。2.2 注册天气API服务并获取密钥API密钥是访问天气服务用的身份凭证相当于一把钥匙。去心知天气官网注册账号后进入“控制台”创建一个新产品产品类型选“天气数据”创建成功后就能看到一串API密钥通常是一段字母数字混合的字符串。建议先把这个密钥复制到记事本里备用因为后面配置节点时要反复用到。这里有个容易踩的坑创建产品后密钥默认可能没有启用对应的服务权限需要确认一下产品状态是不是“运行中”。我第一次做的时候密钥复制出来却没检查产品状态结果在Coze里反复报401错误排查半天才发现是服务没启用。所以拿到密钥后先别急着进Coze就在浏览器里手动请求一次确认能返回数据再往下走。2.3 先手动验证一次接口写任何API对接之前先手动把接口打通这是做开发的基本习惯。不用写代码直接在浏览器地址栏输入下面这个URL就行https://api.seniverse.com/v3/weather/now.json?key换成你的密钥locationbeijinglanguagezh-Hansunitc如果一切正常浏览器会返回一段JSON数据最核心的结构大概是这样的{ results: [ { location: { id: WX4FBXXFKE4F, name: 北京, country: CN, path: 北京,北京,中国, timezone: Asia/Shanghai }, now: { text: 多云, code: 4, temperature: 16, feels_like: 15 }, last_update: 2024-01-15T10:20:0008:00 } ] }这一步的意义非常大。一方面验证了密钥和接口可用另一方面在浏览器里看清了返回的JSON结构。知道results[0].now.temperature是当前温度、results[0].now.text是天气描述待会儿在Coze里解析响应时心里就有底了。我自己做接口对接从来不会跳过这步直接在节点里排错真的会浪费很多时间。3. 核心实操配置HTTP请求节点并让参数“活”起来3.1 配置开始节点的输入参数打开开始节点在“输入参数”区域点击“新增参数”。参数类型选择“文本”Text参数名填city显示名称可以填“城市”默认值填北京。这个默认值很有用调试的时候就算用户什么都不传工作流也不会报错会直接查北京的天气。这里顺便说一个命名习惯参数名建议统一用英文小写加下划线比如city_name、api_key不要用中文。中文虽然有些场景支持但在跨节点引用时偶尔会出现编码问题尤其是后面要传给HTTP请求节点拼URL的时候英文参数名稳妥得多。开始节点配好后它就成了整条工作流的“变量入口”。后面HTTP请求节点里引用的city最终的值就是从用户对话中提取或者由上游调用方传入的。3.2 配置HTTP请求节点拖一个HTTP请求节点到画布上连接在开始节点后面然后双击打开配置面板。首先是请求方法天气查询是读取数据选GET。然后是请求地址填https://api.seniverse.com/v3/weather/now.json注意URL里先不要拼任何参数。所有参数都在下面的“查询参数”区域里配这样维护起来清晰也方便后面做动态参数替换。点开“查询参数”区域逐个添加以下参数参数名参数值说明key你的API密钥认证凭证固定值location引用开始节点的city参数动态参数城市名languagezh-Hans返回简体中文unitc温度单位c为摄氏度关键点来了location这一行不要在参数值里直接填“北京”而是点击参数值输入框右侧的“插入引用”按钮在弹出的节点列表里选择“开始节点”再选择city字段。Coze会自动生成类似{{开始.city}}或{{startParams.city}}的引用语法。这里必须强调一下千万不要手打这个引用语法。不同版本的Coze模板语法可能有差异手打容易漏掉大括号或者字段名写错而且报错信息往往不够直观。用编辑器自带的“插入引用”功能它生成的语法一定跟当前版本匹配这是最省心的做法。3.3 解析返回的JSONHTTP请求节点只是帮你把请求发出去了返回的是一整坨JSON数据。要让这些数据变成能用的字段还得做一步解析。Coze里解析JSON有两种主流方式。第一种是直接在后面的节点里引用JSON路径。比如在结束节点或大模型节点的输入里插入引用HTTP请求节点的输出然后手动在该字段后面拼接路径像这样{{http请求节点.output.results[0].now.temperature}}这种方式的优点是省事不用额外加节点。缺点是不够直观一旦返回结构变化排查起来比较费劲而且如果返回体经过了一层字符串包装路径可能取不到值。第二种方式更推荐在HTTP请求节点后面加一个“代码节点”写一段JavaScript把关键字段提取成干净的对象。代码逻辑很简单const body typeof params.body string ? JSON.parse(params.body) : params.body; const result body.results[0]; return { city: result.location.name, temperature: result.now.temperature, feelsLike: result.now.feels_like, text: result.now.text };这段代码做了三件事把响应体解析成对象、从results[0]取出关键字段、包装成一个新对象返回。后面的节点再引用时直接{{代码节点.output.temperature}}就能拿到温度既直观又不容易出错。需要注意不同Coze版本里代码节点的输入字段名可能叫params也可能叫input以编辑器提示为准我第一次用旧版本时就被这个字段名坑过。3.4 构建输出节点最后一步是把结果整理成智能体能直接用的文本。打开结束节点在输出内容里可以写一段带有变量占位符的文本然后把对应的变量引用拖进去。比如{{代码节点.output.city}}当前天气{{代码节点.output.text}}温度{{代码节点.output.temperature}}度体感{{代码节点.output.feelsLike}}度。配置到这里一条最简工作流就跑通了。点击右上角的“试运行”按钮模拟输入一个城市名比如“上海”观察各节点的运行日志。如果一切顺利结束节点的输出就是一句顺畅的天气播报。第一版跑通之后再回头看整个链路开始节点定义参数HTTP节点发请求代码节点解析响应结束节点拼结果环环相扣这就是Coze工作流的基本节奏。4. 动态参数进阶从写死参数到任意城市随心查4.1 参数引用语法与手动输入的区别很多教程会直接告诉你“在URL里用双大括号包变量名”但实际在Coze里更推荐用编辑器提供的引用功能。因为引用功能生成的语法是标准且经过校验的手动输入则经常出幺蛾子。我自己遇过最典型的问题手动写参数引用时把节点编号写错了。比如HTTP请求节点实际是第3个节点我却引用了第2个节点的输出结果取到的是一个完全无关的字段。用“插入引用”功能就不会有这个问题它会自动列出当前可用的上游节点选中的字段一定存在于该节点的输出中。编辑器的自动补全本质上也是在降低这类低级错误。4.2 写死改动态的对照改造为了让你更直观地理解动态参数的价值我做个对照。写死的做法是在查询参数里直接把location的值填成“北京”。动态的做法是location的值引用开始节点的city参数。维度写死参数动态参数URL形态location北京location{{开始.city}}可复用性只查北京任意城市用户输入不支持支持可配合大模型提取城市维护成本每城一个节点一个节点搞定改造成动态参数的操作其实非常简单选中HTTP请求节点在查询参数location对应的“参数值”输入框里删除原来的“北京”点击“插入引用”选择开始节点的city字段即可。改完之后立刻再试运行一次输入“广州”或“成都”看返回结果是否跟着城市名变化。确实跟着变了说明这个工作流已经具备通用查询能力了。4.3 多参数动态与上游节点联动动态参数不止可以是城市名天气查询里还可以把语言、单位都做成动态。比如开始节点增加一个unit参数可选值“c”和“f”HTTP请求节点的unit查询参数引用它。这样同一个工作流既能服务用摄氏度的用户也能服务习惯华氏度的用户只是多配置一个参数的事。更复杂的场景是用户直接在智能体对话框里说“帮我查一下上海周六的天气”这时开始节点拿到的不是干净的“上海”字段而是一整句自然语言。怎么从这句话里提取城市名答案是让另一个大模型节点来干活。在HTTP请求节点前面接一个大模型节点把用户原话传给它让它在输出里返回城市名然后HTTP节点引用这个大模型节点的输出。这个链路其实就是在Coze里实现“语义理解加外部查询”的标配范式大模型负责把口语转成结构化参数HTTP节点负责拿着参数去真实世界取数代码节点负责整理数据最后再让大模型生成语气自然的口语化回答。我第一次把这条链路跑通时觉得非常爽因为这基本上就是很多所谓AI应用的底层骨架了。5. 踩过的坑和高频问题排查5.1 鉴权失败或者一直提示参数错误HTTP请求节点报401或者返回“invalid key”时不用慌一般就是密钥问题。先检查密钥是否复制完整心知的密钥是一整串字符复制的时候容易漏掉最后一个字符。再检查控制台里对应的产品是否已经启用这是最容易被忽略的。还有一个必须注意的细节查询参数名一定得是key不能改叫apikey或api_key接口只认这个参数名参数写错了就会鉴权失败。5.2 城市名识别不出来甚至乱码如果你输入的location值是中文“北京”某些情况下接口可能返回“定位失败”之类的提示。心知天气虽然支持中文但更稳妥的输入方式是城市拼音比如beijing、shanghai。拼音拼写要规范别拼错。如果想直接支持用户输入中文城市名可以在前面的代码节点里加一个简单的城市名到拼音的映射表或者让大模型节点先把中文城市名转成拼音再传给HTTP节点。中文乱码的问题在Coze里一般不太常见因为平台在发送HTTP请求时通常会做URL编码。如果你担心乱码可以在调试时查看HTTP节点的详细请求日志看实际发出的URL里中文是不是被编码成了%E5%8C%97%E4%BA%AC这种形式这属于URL编码的标准行为接口能正常识别。5.3 节点超时或者请求频率受限免费版天气API都有一定的速率限制如果你的工作流在一个循环里被反复触发很可能触发429限流报错。我在做批量测试时遇到过这个情况几个城市连续跑下来接口开始拒绝服务。解决办法有两个一是工作流里加一个前置的判断逻辑比如同一个城市短时间内查询过就直接复用上一次结果别再发请求二是在代码节点里做简单的5到10秒睡眠后再请求但这种方式在Coze工作流里不太优雅我更推荐用“缓存最近一次结果”的思路来降低请求频率。另外HTTP请求节点本身也有超时设置默认通常比较短。如果天气预报接口偶尔响应慢适当调大超时时间可以减少失败率但也不能无脑调到很大否则工作流整体响应会变得很慢用户等待体验会变差。5.4 返回字段取出来是空的这是新手最容易困惑的问题。明明接口手动访问有数据为什么在Coze里解析出来是空的九成原因是JSON路径写错了。比如实际返回是results[0].now.temperature你写成了result.now.temperature就取不到值。数组索引[0]这种细节非常容易漏。建议先在工作流的代码节点里把整个响应体打印出来看看确认结构再写路径。另一个低频但存在的情况是HTTP请求节点返回的数据可能被包裹了一层字符串直接用JSON路径会失败必须先做一轮解析。这就是我在3.3里推荐用代码节点做解析的原因它天然绕过了这类嵌套字符串问题。5.5 一口气埋好的通用排查套路如果你在调试中遇到说不清的问题我建议按这个顺序排查。先看请求有没有发出打开HTTP节点的运行日志核对实际请求的完整URL重点检查动态参数是否成功替换成了真实值这一步能发现一半以上的问题。再看响应体返回内容是不是标准JSON有没有错误提示字段。最后看下游节点代码节点有没有报错代码里访问的字段名是否跟实际情况一致。这套排查思路不只适用于天气API任何外部接口对接的都通用。这套HTTP请求节点的玩法摸熟之后你会发现它几乎可以套用到所有“从外部拿信息”的场景里。查汇率、查股票、查实时新闻、查物流状态本质上都是换一个URL和几个参数的事。我个人在整个实践过程中最大的体会是动态参数设计一定要在最开始就规划好不要先写死再回改。虽然回改的操作就几秒钟但如果你已经在这个节点后面接了很多下游逻辑每个下游节点的引用都要跟着调项目大了之后非常痛苦。最后一句话送给正在折腾的你做接口对接永远先手动验证、再小范围跑通、最后才考虑封装和扩展这个顺序能帮你少走一大半弯路。