跳转到主要内容

​
使用 PHP SDK 运行

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

​
安装

composer require fetch-hive/sdk
该 SDK 需要 PHP 8.1+，并使用 Guzzle 作为其 HTTP 客户端。

​
身份验证

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

<?php
require_once 'vendor/autoload.php';

use FetchHive\Sdk\FetchHive;

$client = new FetchHive();
或显式传入密钥： 
$client = new FetchHive(['api_key' => 'fhk_...']);
有关如何创建和轮换密钥，请参阅 API 密钥。

​
基本示例

直接运行工作流部署。该调用会阻塞，直到工作流完成： 
<?php
require_once 'vendor/autoload.php';

use FetchHive\Sdk\FetchHive;

$client = new FetchHive();

$run = $client->invokeWorkflow([
    'deployment' => 'YOUR_DEPLOYMENT_NAME',
    'variant'    => 'YOUR_VARIANT_NAME',
    'inputs'     => ['topic' => 'State of enterprise AI in 2026'],
]);

echo $run['run_status'] . PHP_EOL;
echo $run['output'];
请参阅 直接响应结构。

​
方法参考

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

​
处理响应

$run = $client->invokeWorkflow([
    'deployment' => 'my-workflow',
    'variant'    => 'default',
]);

echo $run['run_status'];      // "completed" | "failed" | "running" | "queued"
echo $run['output'];          // final workflow output
echo $run['request_id'];      // use this to look up the run in Logs

​
回调投递

传入 async_mode: true 以立即返回，并让 Fetch Hive 在运行完成时调用你的回调 URL： 
$run = $client->invokeWorkflow([
    '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',
]);

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

​
配置

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

​
错误

非 2xx 响应会抛出 FetchHive\Sdk\Exception\ApiException，其中包含状态码和响应体： 
use FetchHive\Sdk\Exception\ApiException;

try {
    $run = $client->invokeWorkflow([
        'deployment' => 'my-workflow',
        'variant'    => 'default',
    ]);
} catch (ApiException $e) {
    error_log('Fetch Hive error: ' . $e->getMessage());
}
有关工作流特有的失败案例，请参阅 错误处理；有关 HTTP 状态码含义，请参阅 错误与速率限制。

​
链接

​
后续步骤