Saltar al contenido principal

​
Ejecutar con el SDK de Ruby

Usa la gema oficial fetch_hive cuando quieras invocar un deployment de flujo de trabajo desde Ruby. El SDK envuelve el endpoint público POST /v1/workflow/invoke, maneja la autenticación y admite tanto respuestas directas como entrega por callback.

​
Instalación

Agrega a tu Gemfile: 
gem "fetch_hive"
Luego ejecuta: 
bundle install
O instálala directamente: 
gem install fetch_hive
La gema usa faraday por debajo y admite Ruby 3.0+.

​
Autenticación

Configura la variable de entorno FETCH_HIVE_API_KEY con tu clave de API del workspace (el cliente la lee automáticamente): 
export FETCH_HIVE_API_KEY=fhk_...

require "fetch_hive"

client = FetchHive::Client.new
O pasa la clave explícitamente: 
client = FetchHive::Client.new(api_key: "fhk_...")
Consulta API Keys para saber cómo crear y rotar claves.

​
Ejemplo básico

Ejecuta un deployment de flujo de trabajo directamente. La llamada se bloquea hasta que el flujo de trabajo termina: 
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"]
Consulta la forma de respuesta directa.

​
Referencia del método

Palabra claveTipoRequeridoDescripción
deploymentStringSíEl nombre del deployment del flujo de trabajo
variantStringNoEl nombre de la variante del deployment
inputsHashNoPares clave-valor para las variables definidas en el paso Start
async_modeBooleanNoCuando es true, devuelve respuesta inmediatamente y entrega el resultado mediante callback firmado
callback_urlStringNoRequerido cuando async_mode: true - la URL HTTPS de callback a la que llamar cuando la ejecución termine
userStringNoIdentificador opaco de quien llama, expuesto en User Tracking
metadataHashNoMetadata plana definida por quien llama, para auditoría y filtrado de registros. Consulta Metadata de invoke
invoke_workflow construye el cuerpo de la solicitud por ti. Cuando pasas async_mode: true, el SDK envía: 
{
  "async": { "enabled": true, "callback_url": "https://example.com/webhook" }
}

​
Manejo de la respuesta

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

​
Entrega por callback

Pasa async_mode: true para devolver respuesta inmediatamente y hacer que Fetch Hive llame a tu URL de callback cuando la ejecución termine: 
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']}"
Almacena el webhook_secret para que puedas verificar la firma en el callback entrante. Consulta Entrega por callback y disparadores de webhook para el flujo de verificación y la forma del payload firmado.

​
Configuración

OpciónPredeterminadoDescripción
api_keyENV["FETCH_HIVE_API_KEY"]Token bearer del dashboard
base_urlhttps://api.fetchhive.com/v1Sobrescribe la URL base de la API
timeout120Timeout de la solicitud en segundos - aumenta para solicitudes directas de flujos de trabajo de larga duración
client = FetchHive::Client.new(
  api_key: "fhk_...",
  base_url: "https://api.fetchhive.com/v1",
  timeout: 600
)

​
Errores

Las respuestas distintas a 2xx lanzan un RuntimeError con el código de estado y el cuerpo. Rescátalas si necesitas manejar fallos: 
begin
  run = client.invoke_workflow(deployment: "my-workflow", variant: "default")
rescue => e
  warn "Fetch Hive error: #{e.message}"
end
Consulta Manejo de errores para los casos de fallo específicos del flujo de trabajo y Errors and Rate Limits para el significado de los códigos de estado HTTP.

​
Enlaces

​
Siguientes pasos