开始之前
您需要具备:- 在 Living Security 中管理集成和访问密钥的权限
- 能够发起 HTTPS
POST请求的服务器端发送方 - 贵组织所在的 Living Security 区域
- 一个稳定的数据源名称和至少一个数据流名称
1. 注册数据源和数据流
1
打开自定义推送源
前往 设置 → 集成 → 目录,找到 Custom Push Source,然后选择 添加。
2
为数据源命名
输入数据源路由键和可选的描述。例如,请使用
custom-phishing-sim,而不要使用带空格的显示名称。3
添加数据流
添加发送方将使用的每个数据流。数据源与数据流的组合必须在首次推送之前存在;未知的组合将返回
404 Not Found。4
保存数据源
创建完成后,在 设置 → 集成 → 已连接 下打开该数据源。其 Push via API 视图会显示端点格式和最近的运行记录。
2. 创建推送摄取密钥
前往 设置 → Access Keys,选择 Create Access Key,然后选择 Push Ingest 范围。请立即复制生成的值;该值仅显示一次。 该密钥绑定到一个 Living Security 组织。推送请求无需组织标头。有关轮换和吊销,请参阅 API 访问密钥。3. 选择区域端点
请使用与贵组织的 Living Security 对应的主机名:
在其后附加
/push-ingest/{integrationKey}/{streamName}。路径区分大小写,且必须与已注册的数据源和数据流完全一致。
string
必填
已注册的数据源名称。请使用 1–64 个小写字母、数字或连字符,并以字母或数字开头。
string
必填
已注册的数据流名称。规则相同,另外还允许使用下划线。
string
必填
将推送摄取访问密钥以
Bearer <access-key> 的形式发送。string
JSON 请使用
application/json,CSV 请使用 text/csv。省略此标头时,服务器也可以检测 JSON 数组。string
可选的组织 UUID。访问密钥已确定所属组织。如果发送此标头,它必须与密钥所属的组织一致;它不能用于选择其他组织。
请求正文
发送顶层的非空 JSON 对象数组,或带有标题行的 CSV 文件字节。不存在具名的 JSON 包装字段。每个批次最多可包含 10,000 条记录和 10 MB。4. 发送 JSON 批次
发送元素均为对象的非空 JSON 数组。建议使用Content-Type: application/json,许多发送产品也要求设置该标头,尽管 Living Security 在没有它的情况下也能检测数组正文。
202 Accepted。当 JSON 正文格式错误时,错误选项卡会显示 400 Bad Request:
400 示例,请更正 JSON,或使用 Content-Type: text/csv 发送 CSV,然后重试。
string
必填
此已接受批次的运行 ID。请保留它以检查处理状态。
number
必填
已接受并存储的记录数。
string
必填
本次推送所使用的数据源名称。
string
必填
本次推送所使用的数据流名称。
改为发送 CSV
设置Content-Type: text/csv 并发送文件字节,如上文 CSV file 请求示例所示。第一行提供字段名称。
布尔文本会转换为布尔值,普通数字文本会转换为数字。带前导零的值、不安全的大整数、日期和其他文本仍保留为字符串。空单元格会省略该字段。格式错误的行、引号不匹配以及 UTF-16 文件将被拒绝。
请求限制与重试
请将较大的导出数据拆分为同时满足这两项限制的批次。等待每个响应,并在发送方日志中保留返回的
runId。
正常的已认证组织限制返回
503,而不是 429,因此 webhook 发送方会将其视为可重试。503 在批次存储之前返回;在所述间隔之后重新发送同一批次不会产生重复的已接受运行。
验证数据流
打开自定义推送源并查看 Push History。确认数据流、记录数、密钥归属和处理状态。具有受维护解析器的数据随后可以转化为人员和标准化活动。没有解析器的数据会保持存储状态,但不会产生活动。如果存在特定提供商的指南,请使用其中的确切字段名称和负载结构。成功的
202 仅证明传输成功,并不代表任意架构都能映射到 Living Security 活动。故障排查清单
- 从正确的数据源复制端点,并替换数据流占位符。
- 将访问密钥以
Authorization: Bearer …的形式发送;不接受x-api-key。 - 确认正文是顶层 JSON 数组,而不是单个对象或包裹记录的信封结构。
- 确认数据源和数据流的拼写,包括连字符、下划线和大小写。
- 在重新发送响应丢失的批次之前,请先查看 Push History。
- 联系 Living Security 支持团队 时,请提供组织、数据源、数据流、请求时间、可用时的
runId以及响应状态。请勿包含访问密钥或事件负载。
相关内容
Zscaler ZIA Cloud NSS
使用确切的数据源、数据流、标头和 JSON 结构配置受支持的 Zscaler Web 日志源。
API 访问密钥
创建、轮换和吊销限定范围的凭据。
信号数据源
了解经解析的集成活动如何支持信号。

