Skip to main content
当某个系统需要主动向 Living Security 发送记录,而不是由目录连接器轮询时,请使用自定义推送源。发送方可以将 JSON 数组或 CSV 文件提交至区域性 HTTPS 端点。

开始之前

您需要具备:
  • 在 Living Security 中管理集成和访问密钥的权限
  • 能够发起 HTTPS POST 请求的服务器端发送方
  • 贵组织所在的 Living Security 区域
  • 一个稳定的数据源名称和至少一个数据流名称
数据源名称和数据流名称是永久性的路由键。数据源名称必须为 1–64 个小写字母、数字或连字符。数据流名称还允许使用下划线。两者都必须以字母或数字开头。
请将 API 访问密钥视为机密信息。不要将其放入浏览器代码,不要提交到源代码管理系统,也不要通过支持工单发送。

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 访问密钥

创建、轮换和吊销限定范围的凭据。

信号数据源

了解经解析的集成活动如何支持信号。