@ cargo-ai/ 工人- sdk
构建货物托管 劳动者 ——运行在无服务器边缘的 HTTP 处理器 *.worker.getcargo.run ——拥有自动OpenAPI 3.1生成. 霍诺+钱法纳+ Zod被两家有意见的工厂包了起来 所以只要你定义一次路线 就能得到运行时间验证 货物本地清单 免费现场OpenAPI文件.
安装
npm install @cargo-ai/worker-sdk
给工人写信
import { type Context, createWorker, OpenAPIRoute } from "@cargo-ai/worker-sdk";
import { z } from "zod";
const { app, openapi } = createWorker({ title: "my-worker" });
class GetHello extends OpenAPIRoute {
override schema = {
request: {
query: z.object({ name: z.string().default("world") }),
},
responses: {
"200": {
description: "Greeting.",
content: {
"application/json": {
schema: z.object({ message: z.string() }),
},
},
},
},
};
override async handle(c: Context): Promise<Response> {
const { query } = await this.getValidatedData<typeof this.schema>();
return c.json({ message: `Hello, ${query.name}!` });
}
}
openapi.get("/hello", GetHello);
export default app;
createWorker 给你:
GET /openapi.json—— OpenAPI 3.1 spec从每个路线的Zod schema中衍生出来.GET /docs——斯瓦格UI(英语:Swagger UI).- 控制台排水口——
console.info("outbound_http", { status: 200 })存储"outbound_http"作为消息和对象作为结构属性,而不是合并的JSON字符串.
呼叫货物API
在 Cargo 中创建工作空间 API 令牌并将其添加到工人身上 CARGO_API_TOKEN 秘密环境变量. createCargoApi(env) 然后返回完整类型 @cargo-ai/api 客户端, 连接到您的工作空间中 —— 自动允许使用 Cargo API 主机, 不 outboundAllowlist 需要的条目 :
import { createCargoApi } from "@cargo-ai/worker-sdk";
app.get("/workers", async (c) => {
const api = createCargoApi(c.env);
const { workers } = await api.hosting.worker.list();
return c.json(workers);
});
你从这里开始 一直追踪打电话的线索:
货物 托管邮票 引用的运行 和追踪uuid 在外出的货物API
要求,所以一个叫这个工人的剧本 显示它从小创造的运行
而不是无关的痕迹。 没有电线,它适用于
createCargoApi 和一片平地 fetch 同样的API.
克龙触发器
工人们可以按日程安排。 每一个触发器——从货物应用程序上配置的工人, cargo-ai hosting worker create/update --triggers,或 defineWorker 在一个项目中——描述全部要求的"货物"火灾:克龙,路径,方法,JSON尸体和头. 设定 authorization 触发器头并守护路线:
import { bearerAuth } from "hono/bearer-auth";
app.use("/cron/*", bearerAuth({ token: "<something-strong>" }));
app.post("/cron/sync", async (c) => {
// ... scheduled work ...
return c.json({ ok: true });
});
只有在工人有升迁的部署后 才会起火.
写入自定义集成
createCustomIntegration({ info, connector, authenticate, actions, extractors, ... }) 建设一支执行 货物自定义集成HTTP合同 从单一的宣示谱。 同样的Zod计划 GET /manifest (货物内用电线格式)和 GET /openapi.json。见 templates/custom-integration/。 。 。 .
整合领域类型(IntegrationActionExecutePayload, (中文(简体) ), IntegrationExtractorFetchResult,(...) 居住于 @cargo-ai/types 下划线 ConnectionTypes 命名空间 — 您很少需要直接导入, 因为 SDK 的 CustomIntegrationAction 编号 : CustomIntegrationExtractor 类型 连接他们给你.
脚手架一个项目
你几乎从不想要从头接线。 使用 CLI :
# Blank edge handler
npx @cargo-ai/cli hosting worker init my-worker --template blank
# Worker that implements the Cargo Custom Integration HTTP contract
npx @cargo-ai/cli hosting worker init my-integration --template custom-integration
CLI 复制匹配模板 @cargo-ai/worker-sdk/templates/<slug>/ 输入目标目录.
部署
您在 TypeScript 中创建并按 - is 部署源目录 —— 没有本地构建步骤 。 上载源是工程根( 与 src/index.ts, (中文(简体) ), manifest.json, (中文(简体) ), package.json, (中文(简体) ), package-lock.json:
npm install
cargo-ai hosting deployment create --worker-uuid <workerUuid> --source ./
cargo-ai hosting deployment promote --uuid <deploymentUuid>
货物托管建造管道运行 npm ci 接下来 esbuild src/index.ts --bundle --format=esm --platform=neutral --target=es2022 (sbuild transpiles TypeScript 土生土长地)来生产最终的边缘捆绑. 因此,您可以在部署时将多文件类型Script项目 —— Esbuilding tree- sshake everything 传输到一个单一的无害环境管理文件中。 (预建) index.js 根仍然被接受为后向兼容. )
可用模板
blank- 一个即时的Hono应用软件createWorker(),带有一个样本路径和/openapi.json+ 键/docs从盒子里出来。 当工人刚刚响应入境的HTTP时使用这个功能,而不需要整合入"货物连接器"目录.custom-integration——被传递到的即时到外延光谱createCustomIntegration()处理/manifest, (中文(简体) ),/openapi.json, (中文(简体) ),/docs, (中文(简体) ),/authenticate, (中文(简体) ),/actions/<slug>/execute, (中文(简体) ),/extractors/<slug>/{fetch,count}, (中文(简体) ),/autocompletes/<slug>, (中文(简体) ),/dynamicSchemas/<slug>, (中文(简体) ),/completeOauth, (中文(简体) ),/listUsers从单一的宣告。 边际当量getcargohq/dummy-integration在连接器目录中注册defineCustomIntegration在光盘中,或cargo-ai connection custom-integration create --kind worker --worker-uuid <workerUuid>。 。 。 .
查看每个模板自己的 README.md 用于文件布局和如何扩展.