segment-manager

细分管理器

用途

全面管理细分的生命周期——列出、获取、创建、更新、删除、验证 FilterQL，并估算细分规模。

环境

需要经过身份验证的 API 访问权限。凭据解析方式请参阅 ../references/auth.md。

API 端点

列出细分

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment?table=user&kind=segment&sizes=true" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

查询参数：table、kind、valid、sizes

获取细分

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment/${SEGMENT_ID}?sizes=true&inline=true" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

查询参数：sizes（包含规模数据）、inline（内联显示包含的细分）

获取细分的祖先

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment/${SEGMENT_ID}/ancestors" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

创建细分

curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Segment Name",
    "slug_name": "segment_slug",
    "description": "What this segment represents",
    "segment_ql": "FILTER condition FROM user ALIAS segment_slug",
    "kind": "segment",
    "table": "user",
    "is_public": true,
    "tags": [],
    "save_hist": true
  }'

更新细分

curl -s -X PUT "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment/${SEGMENT_ID}" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ ... updated fields ... }'

删除细分

curl -s -X DELETE "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment/${SEGMENT_ID}" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

验证 FilterQL

curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/validate" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: text/plain" \
  -d 'FILTER AND (country = "US", visitct > 5) FROM user ALIAS test'

有效时返回 200，无效时返回错误消息。

估算细分规模（临时 FilterQL）

curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/size" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: text/plain" \
  -d 'FILTER condition FROM user'

请求正文为原始 FilterQL 文本，而非 JSON。

获取现有细分的规模

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/${SEGMENT_ID}/size" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

细分字段信息——受众快照

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/${SEGMENT_ID}/fieldinfo?limit=20&table=user" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

返回细分中各字段的分析数据：值分布、覆盖率、数值统计和直方图。 查询参数：fields（逗号分隔）、limit（默认值为 20，最大值为 1000）、table、cached。 如需详细分析，请使用 audience-snapshot skill。

重新评估细分

curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment/reevaluate" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"id": "segment_id"}'

细分负载

创建时的必填字段：

{
  "name": "Display Name",
  "slug_name": "url_friendly_slug",
  "description": "Human-readable description",
  "segment_ql": "FILTER ... FROM user ALIAS slug",
  "kind": "segment",
  "table": "user",
  "is_public": true,
  "save_hist": true
}

可选字段：

{
  "tags": ["tag1", "tag2"],
  "groups": ["group_id"],
  "expires_at": "2025-12-31T00:00:00Z",
  "emit_trigger": false,
  "schedule_exit": false
}

细分类型

类型	说明	用例
segment	标准受众细分	面向一般受众的定向
aspect	构建块细分	可复用的筛选器组件
goal	业务目标	转化跟踪
list	临时导出列表	一次性或定期导出
conversion	活动跟踪	归因衡量
metric	指标细分	分析/报告
managed	系统管理	平台内部使用
candidate	决策排除项	从决策中排除

行为

读取操作（list、get、size）

立即执行并显示结果。

写入操作（create、update、delete）

使用确认门模式：

1. 构建完整负载
2. 显示易读的摘要
3. 显示原始 API 负载
4. 等待用户确认
5. 获得批准后执行

验证流程

创建或更新细分前：

1. 使用 POST /api/segment/validate 验证 FilterQL
2. 如果无效，解析错误并尝试修复（最多重试 3 次）
3. 验证通过后，使用 POST /api/segment/size 估算规模
4. 继续操作前，展示验证结果和规模结果

错误处理

• FilterQL 无效：解析验证错误，找出问题并建议修复方法
• Slug 冲突（409）：建议使用其他 slug 名称
• 细分为空（规模为 0）：提醒用户，并建议放宽条件
• 细分规模过大：说明规模，并请用户确认操作意图

依赖项

• 使用：../references/auth.md、../references/api-client.md、../references/confirmation-gate.md
• 参考：../references/filterql-grammar.md