PostHog 端点在客户端代码中的消费指南:鉴权、变量载荷、类型化客户端与限流处理

原创2026-09-15 17:10:331,967 阅读
文章标签:数据分析数据可视化实时分析后端前端可观测性大数据数据仓库企业应用屏幕录制AI 应用

PostHog 端点在客户端代码中的消费指南:鉴权、变量载荷、类型化客户端与限流处理

导读

本文是 PostHog 端点(Endpoint)的“调用方(caller-side)”集成指南:PostHog 将保存好的 HogQL 或 Insight 查询暴露为可调用的 API 路由,本文讲解如何从移动端、服务端、客户看板或下游管道中安全、正确地调用这些端点。读完本文,你将掌握端点 URL 与请求载荷的完整形态、个人 API Key 的正确使用姿势、materialised(物化)端点对变量的强制要求、基于 OpenAPI 规范生成类型化客户端的流程,以及限流与错误响应的处理策略。本文源自仓库中的 consuming-endpoints-from-client-code/SKILL.md,并辅以 products/endpoints 后端的源码实现进行印证。

适用场景:什么时候使用这套指南

本文面向的是已有端点、需要从外部代码库接入的调用方,常见诉求包括:

  • “我该怎么调用我的端点?一次请求长什么样?”
  • “为这个端点生成类型化的 TypeScript / Python / Go 客户端”
  • “调用端点时收到 401”的鉴权问题
  • “省略了 user_id 时端点拒绝我的调用”——这通常涉及物化端点的变量强制要求
  • “如何处理限流(rate limit)?”

注意:如果需求是创建端点,请先参考创建侧的指南 creating-an-endpoint/SKILL.md。本文全程不修改任何 PostHog 代码,只做外部接入。

可用工具:端点相关的 MCP 工具

PostHog 通过 MCP 工具暴露端点相关能力,其定义见 products/endpoints/mcp/tools.yaml,与端点消费直接相关的有三个:

工具 用途
endpoint-get 获取指定端点的完整配置,包括查询形态(query shape)与必需的变量
endpoint-openapi-spec 获取单个端点的 OpenAPI 3.0 规范,可直接喂给代码生成器
endpoint-run 对端点做一次实时调用,用于在分享给用户应用之前确认载荷可用

所有端点相关工具都要求 endpoint:read scope(写入类工具如 endpoint-create、endpoint-update、endpoint-delete 则要求 endpoint:write),这与下文“鉴权”一节的要求一致。

端点 URL 的完整形态

/api/projects/{team_id}/endpoints/{name}/run
  • team_id:项目 ID(数字)。可在 PostHog 的项目设置中查看,若用户不知道,可通过 projects-get 获取。
  • name:端点名称,不确定时可用 endpoints-get-all 列出全部端点。
  • 结尾的 /run 是必需的。

在源码中,端点路由注册于项目级路由之下(见 routes.py:routers.projects.register(r"endpoints", EndpointViewSet, "project_endpoints", <a href="https://link.gitcode.com/i/56755204b4cf5c9f1259af77f0a7f00c" target="_blank">"team_id"])),而 run 是 EndpointViewSet 上的一个 detail action(见 [api.py 的 @action(methods=["GET", "POST"], detail=True)),因此 URL 形态与上文的 /{name}/run 完全吻合。

方法选择:POST 优先

POST 是规范方法;GET 在无请求体的简单场景下也可用,但优先使用 POST——变量放在请求体中。从源码看,run action 同时声明了 GET 和 POST 两种方法,但 limit、offset、version 等参数既可从 body 读取也可从 query 读取(见 api.py),而 variables 等复杂载荷只存在于 body。

鉴权:个人 API Key 与服务端-only 原则

端点使用**个人 API Key(personal API key)**进行认证,请求头格式为:

Authorization: Bearer <key>

Key 是有作用域(scoped)的——对于端点,Key 至少需要 endpoint:read 权限。错误排查口诀:

  • 收到 403:通常缺少 scope(或端点在另一个项目里);
  • 收到 401:Key 缺失或格式错误。

从源码看,EndpointViewSet 的 scope_object = "endpoint",而 run 在内的读取类 action 全部挂在 scope_object_read_actions 列表中(见 api.py),即 endpoint:read scope 即可覆盖执行(run)与查看类操作。

安全红线:绝不要把个人 API Key 放进面向终端用户的客户端代码(移动 App、浏览器 JS)。个人 API Key 授予的是带作用域的账户级访问权限。面向客户的应用应当经由用户自己的后端转发请求,由后端保管 Key。

补充一点源码层面的细节:run 是公开的执行 API,认证上仍要求登录、endpoint:read scope 与项目成员身份,但会跳过资源级访问控制,仅保留对象级(单个端点)的显式拒绝逻辑(见 api.py)。项目级 Secret API Key(PSAK)只允许用于 run 动作(psak_allowed_actions = ["run"]),且 PSAK 的 scope 是项目级的,会刻意绕过对象级访问控制。

请求载荷(payload)的字段详解

{
  "variables": { "code_name_1": value, "code_name_2": value },
  "limit": 100,
  "offset": 0,
  "refresh": "cache"
}
字段 说明
variables 键为变量的 code_name(HogQL 端点);对于带 breakdown 的 Insight 端点,键为 breakdown 属性名
limit 返回的最大行数
offset 跳过的行数,仅 HogQL 端点支持
refresh "cache"(缓存足够新鲜时直接返回缓存结果)、"force"(总是重新计算)、"direct"(绕过物化直接查原始数据,仅物化端点可用)。默认 "cache"

调用 endpoint-get 可查看确切的变量形态:响应中包含带声明变量的查询定义,每个变量的 code_name 就是客户端应发送的键。这与 MCP 工具 endpoint-run 的参数覆盖说明一致(见 tools.yaml):HogQL 端点按 code_name 传参(如 {"event_name": "$pageview"}),带 breakdown 的 Insight 端点则用 breakdown 属性名作为键。

另外注意请求体中的 version 字段或 ?version=N 查询参数可用于指定调用某个端点版本(body 优先于 query 参数,见 api.py 的 _parse_version_param)。源码对参数还有额外校验:limit 最小为 1,offset 最小为 0,且设置了 offset 就必须同时设置 limit,否则返回 400(见 api.py)。

物化端点:所有变量都必须传

如果 endpoint-get 返回当前版本的 is_materialized: true,则该端点每次调用都必须传入每一个声明的变量。这是一条安全边界——如果没有过滤条件,一次调用就会返回整个预聚合(pre-aggregated)数据集。

典型症状:应用在端点未物化时一切正常,启用物化后开始返回 400;错误消息会列出缺失的变量。这条规则也体现在创建侧的校验逻辑中——源码在启用物化时会校验查询的可物化性(见 validation.py)。

已知限制与反馈渠道:物化端点上“可选/部分变量”是目前已知的限制,PostHog 团队计划解除。如果“每个变量都必须传”阻碍了使用场景,可以通过 agent-feedback 工具反馈——这类需求信号正是团队排定优先级的主要依据。

生成类型化客户端:OpenAPI 规范 + 代码生成器

每个端点通过 endpoint-openapi-spec 暴露自己的 OpenAPI 3.0 规范。在源码中对应 openapi_spec action,路由为 openapi.json,支持 ?version=N 为指定版本生成规范(见 api.py)。拿到 spec 后喂给代码生成器:

语言 工具 命令形态
TypeScript @hey-api/openapi-ts openapi-ts -i spec.json -o ./generated
TypeScript openapi-generator-cli openapi-generator-cli generate -i spec.json -g typescript-fetch -o ./generated
Python openapi-generator-cli openapi-generator-cli generate -i spec.json -g python -o ./generated
Go oapi-codegen oapi-codegen -package=client spec.json > client.go

生成的客户端会为用户提供变量载荷与响应形态的类型。当端点的查询发生变化时需重新生成(每个新版本可能引入或移除变量)。

多个端点的处理:每个端点生成一份 spec,可以合并生成一个客户端,也可以每个端点单独生成一个客户端、并排使用。

响应形态(Response shape)

一个典型的成功响应:

{
  "results": [[...], [...]],
  "columns": ["col_a", "col_b"],
  "types": ["Int64", "String"],
  "hasMore": false,
  "name": "endpoint_name",
  "endpoint_version": 4,
  "endpoint_version_created_at": "2026-01-15T..."
}
  • results 是行数组,每行是按 columns 顺序排列的单元格值数组;
  • endpoint_version 告诉客户端实际运行的是哪个版本——这对日志记录、以及用 ?version=N 固定到已知版本都很有用。

对于 Insight 端点,响应形态取决于查询类型(TrendsQuery、LifecycleQuery、RetentionQuery)——OpenAPI 规范会捕获当前版本的正确形态。无法物化的 Insight 类型(如 FunnelsQuery)仍然返回其内联(inline)结果形态。

从 PostHog CLI 调用端点

本地测试、脚本或 CI 场景下,仓库自带的 posthog-cli 可以直接调用端点,无需手写 HTTP:

  • posthog-cli exp endpoints run —— 执行端点(基于本地 YAML 定义);
  • posthog-cli exp endpoints {list,get,pull,push,diff} —— 查看端点,或将端点作为 YAML 文件纳入版本管理(GitOps 风格)。

CLI 命令的实现见 cli/src/commands.rs(endpoints_list / endpoints_get / endpoints_open / endpoints_run / endpoints_push / endpoints_pull / endpoints_diff),其中 push 还支持 --dry-run 预览变更。

鉴权使用同一个个人 API Key,可通过 posthog-cli login 或环境变量 POSTHOG_CLI_API_KEY / POSTHOG_CLI_PROJECT_ID / POSTHOG_CLI_HOST 配置。注意这些命令位于 exp(experimental)命名空间下,API 可能变化。

需要处理的错误响应

状态码 触发场景 处理方式
400 物化端点缺少必需变量,或变量类型非法 展示错误消息;修正调用
401 个人 API Key 缺失 / 错误 检查 Authorization 头
403 Key 缺少 endpoint:read scope,或端点在另一个项目中 调整 Key 的 scope
404 端点名拼写错误,或端点未激活 确认名称;检查 is_active
429 触发限流——限额按团队而非按端点(见下方说明) 指数退避重试;客户端尽可能缓存响应
5xx 查询执行失败(ClickHouse 错误、超时等) 带退避重试;持续失败则移交 diagnosing-endpoint-performance 处理

从源码看,run 中版本号不存在会返回带 current_version 的 404(api.py),offset 缺 limit 会返回 400,非法数值参数同样返回 400 并记录 rejected run 日志。

完整工作流

  1. 确认端点名称。不知道的话,可用 execute-sql 查询 system.data_modeling_endpoints 表,或使用 endpoints-get-all。
  2. 用 endpoint-get 查看完整形态:变量、物化状态、查询类型。
  3. 确定鉴权姿态:个人 API Key 放在服务端,绝不放在客户端。
  4. 若用户需要生成类型,调用 endpoint-openapi-spec,把 spec 交给用户,并按语言推荐生成器。
  5. 根据变量声明构造一个示例请求载荷,并走一遍测试调用。
  6. 可选:用本技能的 endpoint-run 实时确认载荷可用。
  7. 收尾时交代处理要点:物化变量规则、限流形态、用 ?version=N 固定版本。

实战示例:从 Node.js 后端调用物化端点

用户:"我想从我的 Node.js 后端调用 monthly_active_users,能帮我接线并带上类型吗?"

Agent 步骤:
- endpoint-get monthly_active_users → HogQL,变量:lookback_days
  (int,默认 30)、org_id(string,无默认值)、is_materialized: true
- "先说明两件事:
   1. 这个端点是物化的,所以 lookback_days 和 org_id 每次调用都必须传,
      缺参数会被拒绝。
   2. 你需要一个带 endpoint:read scope 的个人 API Key,放在服务端环境变量
      PH_API_KEY 里——绝不要发布到客户端代码中。"

- endpoint-openapi-spec monthly_active_users → 返回 spec

- "这是 spec。放进你的仓库然后运行:
     pnpm dlx @hey-api/openapi-ts -i spec.json -o ./generated/posthog
   这会生成类型化客户端函数。

   最小调用长这样:
     POST /api/projects/12345/endpoints/monthly_active_users/run
     Authorization: Bearer <PH_API_KEY>
     Content-Type: application/json

     { 'variables': { 'org_id': 'acme', 'lookback_days': 30 } }

   响应包含 columns 和 rows——你的客户端会从生成的类型里自动识别。

   需要我先做一次示例调用来验证载荷可用吗?"

重要注意事项汇总

  • 个人 API Key 只能用于服务端。 绝不放进移动 App 或浏览器 JS。

  • 查询变化时重新生成客户端。 每个新的端点版本都可能增删变量——重新拉取 spec 保持类型同步。

  • 物化端点会拒绝缺变量的调用。 这是有意为之。如果用户在启用物化后报告 400,问题出在调用方,而不是端点。

  • 固定版本,不要依赖 “latest”。 始终用 ?version=N 调用。不带版本参数时会运行最新激活版本,因此未来一次查询编辑(会切出新版本)可能悄然改变调用方的结果。在验证新版本没问题后,再有意地升级固定版本号。

  • 客户端侧缓存是合理的。 端点本身已通过 data_freshness_seconds 缓存,但客户端可以在热点路径上再叠一层缓存。注意总的陈旧度(端点缓存 + 客户端缓存)。

  • 限流按团队、按类别计算,而不是按端点。 调用非物化端点时,与所有其他查询流量共享团队级的 API 查询预算(约 240 次/分钟突发、2400 次/小时持续);物化端点则使用另一个更高、独立的共享桶(约 1200 次/分钟、12000 次/小时)。这里没有“按端点名”的限制,所以猛打一个端点会挤占同团队其他端点的配额。高流量调用方应尽量批量请求,并在 429 时退避。

    以上限流数字在源码中有直接印证:EndpointBurstThrottle 对物化请求使用 1200/minute、EndpointSustainedThrottle 使用 12000/hour,而非物化请求复用 APIQueriesBurstThrottle / APIQueriesSustainedThrottle 的共享桶(见 throttles.py)。物化/非物化的判定通过 is_materialized_request 在请求到达时动态解析(见 throttles.py)。

  • 计费。 目前调用端点不收费,但一旦端点随托管数仓(managed warehouse)正式发布,将会纳入计费。如果用户计划高用量,提前提示这一点,避免未来成本出乎意料。

  • 把缺失的东西反馈给 PostHog。 如果错误、限制或缺失能力阻碍了使用,请使用 agent-feedback 工具——这是团队改进端点和这些工具的主要信号来源。

延伸阅读

登录后查看全文
posthog