job-manager

作业管理器

用途

完整的作业／工作生命周期管理——列出、创建、更新和控制作业状态（暂停、恢复、重启、终止）。作业代表数据集成任务，例如导入、导出和同步。

环境

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

API 端点

列出作业

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

默认只显示非终态作业（可运行、休眠、已暂停、故障）。

查询参数	默认值	描述
workflow	-	按工作流 slug 筛选
auth_ids	-	按 auth ID 筛选
show_completed	false	包含已完成的作业
show_deleted	false	包含已删除的作业
show_hidden	false	包含隐藏的作业
show_all	false	显示所有内容（将 completed、deleted、hidden 设为 true）
show_state	false	在响应中包含 WorkState 详情

获取作业

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

按工作流获取作业

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/job/${WORKFLOW}/${JOB_ID}" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

创建作业

curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/job" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Job Name",
    "description": "What this job does",
    "workflow": "workflow_name",
    "config": { ... workflow-specific config ... },
    "auth_ids": ["auth_id"],
    "tag": "optional-tag"
  }'

使用工作流创建作业

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

更新作业

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

作业生命周期命令

# Pause
curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/job/${JOB_ID}/pause" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

# Resume
curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/job/${JOB_ID}/resume" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

# Bounce (restart)
curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/job/${JOB_ID}/bounce" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

# Kill (stop permanently)
curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/job/${JOB_ID}/kill" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

# Release
curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/job/${JOB_ID}/release" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

作业日志

有两个端点：所有账户的日志（最近 24 小时，不包括已终止的作业），或特定作业的日志（自作业创建以来）。

# All account job logs (last 24 hours, non-killed jobs)
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/job/logs" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

# Logs for a specific job (by ID)
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/job/${JOB_ID}/logs" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

# Logs for a specific job (by workflow + ID)
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/job/${WORKFLOW}/${JOB_ID}/logs" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

# Include additional error details
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/job/${JOB_ID}/logs?include_errors=true" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

查询参数： include_errors=true 会返回默认日志条目之外的其他错误详情。调试作业故障时，请始终使用此参数。

响应：按时间戳排序的 JobLog 条目数组。

每个日志条目包含：

{
  "job_id": "abc123",
  "context": {
    "added": 145,
    "omitted": 3,
    "removed": 12,
    "user_email": "[email protected]"
  },
  "code": "JOB-FAULT-022",
  "message": "Human-readable description of what happened",
  "level": "info",
  "timestamp": "2026-03-19T14:30:00Z"
}

日志条目字段：

字段	描述
job_id	此日志所属的作业
message	易于理解的描述（例如，“由用户 [email protected] 启动”、“超出速率限制”）
level	日志级别——事件为 info，问题为 error／warn
timestamp	事件发生的时间
code	错误级别条目的错误代码（例如，JOB-FAULT-022、UNAUTHORIZED-017）
context	其他元数据映射，因事件类型而异

导出作业的常见 context 字段：

Context 键	描述
added	本次运行中新增／导出的用户数量
omitted	跳过的用户数量（例如，已导出或被筛选掉）
removed	从目标位置移除的用户数量
user_email	触发操作的人员（用于手动启动／暂停／终止）

日志来源：

• 作业 WorkState 中的 API 错误（执行错误、身份验证失败、速率限制）
• 系统事件（作业已创建、已启动、已暂停、已终止、已更新——info 级别）

调试时解读日志：

• 首先查看 level: "error" 条目，查找故障
• 检查 added／omitted／removed 数量，确认导出是否正在进行
• 将最新日志的 timestamp 与当前时间比较，检测作业是否过时
• code 字段有助于判断错误类型（身份验证、速率限制、请求错误等）

作业负载

{
  "name": "My Export Job",
  "description": "Export high-value users to Facebook",
  "workflow": "facebook_custom_audiences",
  "config": {
    "segment_id": "segment_id_here",
    "...": "workflow-specific configuration"
  },
  "auth_ids": ["auth_provider_id"],
  "tag": "optional-client-tag",
  "hidden": false,
  "verbose_logging": false,
  "quiet_time_of_day": "02:00",
  "quiet_timezone": "America/Los_Angeles",
  "quiet_period": 4
}

行为

读取操作（list、get、logs）

立即执行并以表格形式显示结果，包括：

• 作业 ID、名称、工作流、状态、最后更新时间

写入操作（create、update）

使用确认门模式。

生命周期命令（pause、resume、bounce、kill）

• pause/resume：执行并简短确认
• bounce：说明这会重启作业，并请求确认
• kill：警告此操作会永久停止作业，并要求明确确认

错误处理

• 找不到作业（404）：检查作业 ID，列出可用作业
• 工作流无效：列出可用工作流
• 缺少身份验证信息：建议先通过 connection-manager 创建 auth provider

依赖项

• 使用：../references/auth.md、../references/api-client.md、../references/confirmation-gate.md