开发者文档 2 分钟阅读

开发者 API、Webhook 和连接器 SDK — OpsIQ

本文由机器自动翻译。

开发者 API、Webhook 和连接器 SDK — OpsIQ

使用 OpsIQ 开发者 API 构建 AI 感知的集成，该 API 包括签名的 REST 端点、HMAC Webhook、操作合同以及 PHP、Node 和 Python 的 SDK。免费获取一个密钥，使您的平台具备 AI 操作能力。

概述

OpsIQ 提供了一个干净的 REST API、HMAC 签名的 Webhook、操作合同注册表和现成的 SDK。您可以定义从系统触发的事件、AI 被允许执行的操作以及可以安全读取的数据。OpsIQ 为您处理签名、重试、审计日志和确认流程。

入门

获取 API 密钥：注册并在开发者设置中生成一个范围限定的公钥/私钥对。仅为每个集成提供所需的表面。
触发和订阅：向 events/fire 端点 POST 一个签名事件（或使用 SDK），然后将任何 URL 指向任何事件 — 签名、带有交付 ID 和退避重试。
注册操作：声明一个签名的操作合同，以便 AI 可以安全地执行操作，包括角色检查、确认政策和完整的审计跟踪。

事件处理

通过从您的平台或您自己的自定义事件名称触发通用事件，告诉 OpsIQ 刚刚发生了什么。每个订阅者实时响应，按优先级顺序。

事件参考

通用事件：invoice.paid、ticket.created、subscription.cancelled、customer.signed_up，或您自己的自定义事件。

操作合同

告诉 OpsIQ AI 可以执行的操作。操作合同是一个签名的 JSON 声明，指定操作的功能、可以运行它的角色、接受的参数、是否需要确认以及要调用的端点。

操作模式示例

{
    "key": "saas.refund_invoice",
    "label": "退款已支付的发票",
    "surface": ["admin"],
    "roles": ["owner", "billing_admin"],
    "requires_confirmation": true,
    "params": {
        "invoice_id": {
            "type": "int",
            "required": true
        },
        "reason": {
            "type": "string",
            "max": 500
        }
    },
    "endpoint": "https://api.you.com/refund",
    "audit": true
}

Webhooks

通过加密证明将事件推送到您的堆栈。将任何 URL 订阅到任何事件。OpsIQ 将带有 HMAC-SHA256 签名的 JSON 有效负载通过原始主体进行 POST，您可以用几行代码进行验证。

Webhook 参考

$raw = file_get_contents('php://input');
$sig = $_SERVER['HTTP_X_OPSIQ_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $raw, $secret);
if (!hash_equals($expected, $sig)) http_response_code(401);
$event = json_decode($raw, true);

SDKs

三个官方 SDK 处理身份验证、签名、重试、幂等性密钥和类型化响应。或者，您可以保持无框架，因为每个 SDK 都是围绕相同 REST 接口的薄包装。

客户端示例

import { OpsIQ } from "@opsiq/sdk";
const ops = new OpsIQ({ publicKey, secretKey });
await ops.events.fire("order.shipped", { customer_id: 421, order_ref: "NB-9182", carrier: "DHL" });
const result = await ops.actions.run("saas.send_kb_link", { ticket_id: 5519, article: "how-to-reset-password" });

连接器模式

连接器是一个包含一个 PHP 类的文件夹。OpsIQ 会发现它，注册表会连接事件，而您的平台特定代码将与核心保持清晰分离。

连接器指南

搭建一个包含 connector.php 的文件夹，扩展 AbstractConnector。
声明 actions.json 和 settings.json 清单。
实现身份、上下文和 webhook 提供者。
订阅您关心的事件。
签名，放入并在管理界面启用。

测试

每个工作区都提供一个沙箱，具有自己的密钥对，可以访问相同的 API 接口而不触及生产数据。使用 POST /v1/webhooks/test 在您的端点发送一个签名的示例交付，并在上线之前确认您的签名验证。

常见问题

身份验证是如何工作的？

每个请求都携带您的公钥以及一个 X-OpsIQ-Signature 头，该头是使用您的私钥对原始主体进行 HMAC-SHA256 计算的结果，还有一个用于重放保护的 X-OpsIQ-Timestamp。OpsIQ 在任何操作执行之前会验证签名、时间戳窗口、您的密钥范围和操作员的角色。

AI 能否运行我未批准的操作？

不能。AI 只能提议在您的操作合同注册表中存在的操作。它不能创造调用。

我如何验证 webhook 确实来自 OpsIQ？

重新计算 sha256=hash_hmac('sha256', $rawBody, $secret) 并将其与 X-OpsIQ-Signature 头进行常量时间检查 (hash_equals)。

有哪些可用的 SDK？

官方 SDK 支持 PHP 8.4+、Node.js 18+ 和 Python 3.10+，处理签名、重试、幂等性密钥和类型化响应。

我可以在不接触生产环境的情况下进行测试吗？

可以。每个工作区都提供一个沙箱，具有自己的密钥对，可以访问相同的 API 接口，而不接触生产数据。

自托管版本的行为与云端相同吗？

是的。自托管安装运行相同的代码路径，因此云端和本地之间没有行为差异。

连接器到底是什么？

连接器是一个自包含的文件夹，包含一个扩展 AbstractConnector 的 PHP 类，以及 actions.json 和 settings.json 清单。您需要实现 identityProviders()、contextProviders()、registerActions()、subscribers() 和 handleWebhook。

OpsIQ 开发者文档

这篇文章对您有帮助吗？

仍然需要帮助？联系我们

概述

入门