跳转到主要内容

​
使用 Ruby SDK 运行

当你想从 Ruby 调用工作流部署时，请使用官方的 fetch_hive gem。SDK 包装了公共的 POST /v1/workflow/invoke 端点，处理身份验证，并同时支持直接响应和回调投递。

​
安装

添加到你的 Gemfile： 
gem "fetch_hive"
然后运行： 
bundle install
或直接安装： 
gem install fetch_hive
该 gem 底层使用 faraday，支持 Ruby 3.0+。

​
身份验证

将 FETCH_HIVE_API_KEY 环境变量设置为你的工作区 API 密钥（客户端会自动读取它）： 
export FETCH_HIVE_API_KEY=fhk_...

require "fetch_hive"

client = FetchHive::Client.new
或显式传入密钥： 
client = FetchHive::Client.new(api_key: "fhk_...")
有关如何创建和轮换密钥，请参阅 API 密钥。

​
基本示例

直接运行工作流部署。该调用会阻塞，直到工作流完成： 
require "fetch_hive"

client = FetchHive::Client.new

run = client.invoke_workflow(
  deployment: "YOUR_DEPLOYMENT_NAME",
  variant: "YOUR_VARIANT_NAME",
  inputs: { topic: "State of enterprise AI in 2026" }
)

puts run["run_status"]
puts run["output"]
请参阅 直接响应结构。

​
方法参考

关键字参数类型必填描述
deploymentString是工作流部署名称
variantString否部署变体名称
inputsHash否Start 步骤定义的变量的键值对
async_modeBoolean否当为 true 时，立即返回，并通过签名回调投递结果
callback_urlString否当 async_mode: true 时必填 - 运行完成时调用的 HTTPS 回调 URL
userString否在 用户跟踪 中显示的不透明调用方标识符
metadataHash否调用方定义的扁平元数据，用于审计和日志过滤。请参阅 调用元数据
invoke_workflow 会为你构建请求体。当你传入 async_mode: true 时，SDK 会发送： 
{
  "async": { "enabled": true, "callback_url": "https://example.com/webhook" }
}

​
处理响应

run = client.invoke_workflow(deployment: "my-workflow", variant: "default")

puts run["run_status"]    # "completed" | "failed" | "running" | "queued"
puts run["output"]        # final workflow output
puts run["request_id"]    # use this to look up the run in Logs

​
回调投递

传入 async_mode: true 以立即返回，并让 Fetch Hive 在运行完成时调用你的回调 URL： 
run = client.invoke_workflow(
  deployment: "YOUR_DEPLOYMENT_NAME",
  variant: "YOUR_VARIANT_NAME",
  inputs: { topic: "State of enterprise AI in 2026" },
  async_mode: true,
  callback_url: "https://example.com/callback"
)

puts "Queued: #{run['run_status']}"
puts "Webhook secret: #{run['webhook_secret']}"
请保存 webhook_secret，以便你能验证传入回调的签名。请参阅 回调投递与 Webhook 触发 了解验证流程和签名负载结构。

​
配置

选项默认值描述
api_keyENV["FETCH_HIVE_API_KEY"]来自仪表板的 Bearer 令牌
base_urlhttps://api.fetchhive.com/v1覆盖 API 基础 URL
timeout120请求超时（秒）- 对于长时间运行的直接工作流请求请增大该值
client = FetchHive::Client.new(
  api_key: "fhk_...",
  base_url: "https://api.fetchhive.com/v1",
  timeout: 600
)

​
错误

非 2xx 响应会引发 RuntimeError，其中包含状态码和响应体。如需处理失败，请捕获异常： 
begin
  run = client.invoke_workflow(deployment: "my-workflow", variant: "default")
rescue => e
  warn "Fetch Hive error: #{e.message}"
end
有关工作流特有的失败案例，请参阅 错误处理；有关 HTTP 状态码含义，请参阅 错误与速率限制。

​
链接

​
后续步骤