SuperAPI AI 工具集

consuming-endpoints-from-client-code

编程与开发

查看项目

更新于 10-16 03:45

技能介绍

用途:本技能是创建 endpoint 的调用侧配套,帮助把已有 endpoint 接入独立代码库(移动应用、服务端后端、客户仪表盘或下游流水线),不修改 PostHog 本身。适用于“如何调用我的 endpoint”、生成 TypeScript/Python/Go 类型化客户端、401/403 鉴权、缺少变量被拒、限流处理等场景;若用户是在创建 endpoint,应先用 creating-another 技能。

主要能力与工具:endpoint-get 查看某个 endpoint 的完整配置(查询结构、必填变量);endpoint-openapi-spec 获取单个 endpoint 的 OpenAPI 3.0 规范,可直接喂给代码生成器;endpoint-run 发起一次实时调用,用于在共享给应用前验证请求体。

调用方式:地址为 /api/projects/{team_id}/endpoints/{name}/run,team_id 是数字项目 ID,name 是 endpoint 名,末尾 /run 必填。规范方法为 POST(简单无请求体场景 GET 也可,优先 POST),变量放在请求体中,字段包括 variables、limit、offset、refresh(cache/force/direct,默认 cache)。鉴权使用个人 API key,请求头为 Authorization: Bearer <key>,需至少 endpoint:read 权限;403 通常是缺 scope,401 是 key 缺失或格式错误。

生成类型化客户端:用 endpoint-openapi-spec 拿到规范后交给生成器。TypeScript 可用 openapi-ts -i spec.json -o ./generated 或 openapi-generator-cli generate -i spec.json -g typescript-fetch -o ./generated;Python 用 openapi-generator-cli generate -i spec.json -g python -o ./generated;Go 用 oapi-codegen -package=client spec.json > client.go。查询变化时需重新生成。

重要限制:所有变量在 materialised endpoint 上均为必填,这是安全边界;开启 materialisation 后若出现 400,应修复调用而非改 endpoint,可选/部分变量目前是已知限制。个人 API key 只能放在服务端,绝不能出现在面向最终用户的客户端代码中,客户应用应经用户自有后端转发。调用时建议用 ?version=N 固定版本,避免后续查询编辑静默改变结果。限流按团队和类别计算,非按 endpoint:非物化 endpoint 与团队其他查询共享约 240/分突发、2400/小时持续额度;物化 endpoint 使用单独的更高共享桶,约 1200/分、12000/小时。当前调用 endpoint 不计费,但未来与管理仓库一起发布后会收费,需提前告知高流量用户。本地测试或 CI 可用 posthog-cli exp endpoints run 及 list/get/pull/push/diff 管理 YAML,鉴权同样使用个人 API key。