将原始日志导出到自行管理的 Google Cloud 存储桶

支持的平台：

Google SecOps SIEM

注意： 此功能受《Google 安全运营服务专用条款》的正式发布前产品条款约束。我们对正式发布前功能的支持可能有限，并且对正式发布前功能的更改与其他正式发布前版本可能不兼容。如需了解详情，请参阅 Google SecOps 技术支持服务准则和 Google SecOps 服务专用条款。

注意 ：抢先体验 - 如需启用数据导出 API 的增强功能，请与您的 Google SecOps 租户的支持团队联系。启用此功能后，您将可以访问新的 API 方法和增强型属性。

借助 Data Export API，您可以将 Google Security Operations 中的安全数据批量导出到您控制的 Google Cloud Storage 存储桶中。此功能支持关键的长期数据保留、历史取证分析和严格的合规性要求（例如 SOX、HIPAA、GDPR）。

重要提示：启用新的增强型 API 后，您将无法使用该 API 访问旧的现有作业。

如需详细了解 Data Export API，请参阅 Data Export API（增强版）

Data Export API 提供了一种可伸缩且可靠的解决方案，用于导出时间点数据，并可处理高达 100 TB 的请求。

作为一种托管式流水线，它提供重要的企业级功能，包括：

• 针对暂时性错误的自动重试
• 全面的作业状态监控
• 每个导出作业的完整审核跟踪记录

该 API 会在您的 Google Cloud Storage 存储桶中按日期和时间对导出的数据进行逻辑分区。

借助此功能，您可以构建大规模数据分流工作流。Google SecOps 会管理导出流程的复杂性，以提供稳定性和性能。

主要优势

Data Export API 提供了一种可弹性扩展且可审核的解决方案，用于管理安全数据的生命周期。

• 可靠性：该服务可处理大规模数据转移。系统使用指数退避算法策略自动重试遇到暂时性问题（例如临时网络问题）的导出作业，从而提高弹性。如果导出作业因暂时性错误而失败，系统会自动重试多次。如果作业在所有重试尝试后仍永久失败，系统会将其状态更新为 FINISHED_FAILURE，并且该作业的 API 响应会包含详细的错误消息，说明失败原因。

• 全面的可审核性：为满足严格的合规性和安全标准，系统会在不可变的审核跟踪中捕获与导出作业相关的每项操作。此轨迹包含每个作业的创建、启动、成功或失败情况，以及发起操作的用户、时间戳和作业参数。

  注意： 当前版本的 API 没有内置的调度程序来设置每日导出以实现合规性。如需设置每日周期性导出，您必须自行创建自动化流程。

• 针对性能和规模进行了优化：该 API 使用了强大的作业管理系统。该系统包含排队和优先级划分功能，可提供平台稳定性并防止任何单个租户垄断资源。

• 增强了数据完整性和可访问性：系统会自动将数据整理到 Google Cloud Storage 存储桶中的逻辑目录结构中，这有助于您查找和查询特定时间段的数据以进行历史分析。

关键术语和概念

• 导出作业：一项异步操作，用于将特定时间范围内的日志数据导出到 Google Cloud Storage 存储桶。系统会使用唯一的 dataExportId 跟踪每个作业。
• 作业状态：导出作业在其生命周期中的当前状态（例如 IN_QUEUE、PROCESSING、FINISHED_SUCCESS）。
• Google Cloud Storage 存储桶：用户拥有的 Google Cloud Storage 存储桶，用作导出数据的目标位置。
• 日志类型：您可以导出的特定日志类别（例如 NIX_SYSTEM、WINDOWS_DNS、CB_EDR）。如需了解详情，请参阅所有受支持的日志类型列表。

了解导出的数据结构

作业成功完成后，系统会将数据写入您的 Google Cloud Storage 存储桶。它使用特定的分区目录结构来简化数据访问和查询。

目录路径结构： gs://<gcs-bucket-name>/<export-job-name>/<logtype>/<event-time-bucket>/<epoch_execution_time>/<file-shard-name>.csv

• gcs-bucket-name：您的 Google Cloud Storage 存储桶的名称。
• export-job-name：导出作业的唯一名称。
• logtype：导出数据的日志类型名称。

• event-time-bucket：导出日志的事件时间戳的小时范围。

  格式为 UTC 时间戳：year/month/day/UTC-timestamp（其中 UTC-timestamp 为 hour/minute/second）。
  例如，2025/08/25/01/00/00 表示 UTC 01:00:00 AM, August 25, 2025。

• epoch-execution-time：Unix 纪元时间值，表示导出作业的开始时间。

• file-shard-name：包含原始日志的分片文件的名称。每个文件分片的上限为 100 MB。

性能和限制

该服务具有特定限制，以确保平台稳定性和公平的资源分配。

• 每个作业的最大数据量：每个导出作业最多可请求 100 TB 的数据。对于较大的数据集，我们建议将导出操作拆分为多个时间范围较小的作业。
• 并发作业：每个客户租户最多可同时运行或排队 3 个导出作业。如果任何新的作业创建请求超出此限制，系统都会拒绝。
• 作业完成时间：导出的数据量决定了作业完成时间。单个作业最多可能需要 18 小时。
• 导出格式和数据范围：此 API 支持批量导出特定时间点的数据，但具有以下限制和功能：
  • 仅限原始日志：您只能导出原始日志（不能导出 UDM 日志、UDM 事件或检测结果）。如需导出 UDM 数据，请参阅在自行管理的 Google Cloud项目中配置数据导出到 BigQuery。
  • 数据压缩：API 会以未压缩的文本格式导出数据。

前提条件和架构

本部分概述了使用 Data Export API 所需的系统架构和必要要求，并详细介绍了系统架构。您可以使用此信息来验证环境是否已正确配置。

准备工作

在使用 Data Export API 之前，请完成以下前提步骤，以设置您的 Google Cloud Storage 目标位置并授予必要的权限。

1. 向 API 用户授予权限：如需使用数据导出 API，您需要具备以下 IAM 角色。

   • Chronicle administrator (creating/managing jobs)：授予使用 API 创建、更新、取消和查看导出作业的完整权限。
   • Chronicle Viewer：授予只读访问权限，以便使用 API 查看作业配置和历史记录。

2. 创建 Google Cloud Storage 存储桶：在您的 Google Cloud项目中，在与 Google SecOps 租户相同的区域中创建一个新的 Google Cloud Storage 存储桶（导出数据的目标位置）。将其设为私密，以防止未经授权的访问。如需了解详情，请参阅创建存储桶。

3. 向服务账号授予权限：向与您的 Google SecOps 租户相关联的 Google SecOps 服务账号授予将数据写入存储桶所需的 IAM 角色。

   1. 调用 FetchServiceAccountForDataExport API 端点，以标识 Google SecOps 实例的唯一服务账号。该 API 会返回服务账号电子邮件地址。

      示例请求：

      {
        "parent": "projects/myproject/locations/us/instances/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
      }
      

      示例回答：

      {
        "service_account_email": "[e-mail]"
      }
      

   2. 向目标 Google Cloud Storage 存储桶的 Google SecOps 服务账号主账号授予以下 IAM 角色：此角色可让 Google SecOps 服务将导出的数据文件写入您的 Google Cloud Storage 存储桶。

      • Storage object administrator (roles/storage.objectAdmin)
      • Legacy bucket reader (roles/storage.legacyBucketReader)

      如需了解详情，请参阅授予对 Google SecOps 服务账号的访问权限。

4. 完成身份验证：Data Export API 会对您的调用进行身份验证。 如需设置此身份验证，请按照以下部分中的说明操作：

   1. Google Cloud 服务的身份验证方法
   2. 应用默认凭据

关键使用场景

数据导出 API 提供了一组端点，用于创建数据导出作业并管理批量数据导出的整个生命周期。您可以使用 API 调用执行所有互动。

以下用例介绍了如何创建、监控和管理数据导出作业。

核心工作流程

本部分介绍如何管理导出作业的生命周期。

创建新的数据导出作业

系统会将数据导出作业规范存储在父资源 Google SecOps 实例中。此实例是导出作业的日志数据源。

• 确定 Google SecOps 实例的唯一服务账号。 如需了解详情，请参阅 FetchServiceAccountForDataExports。

• 如需开始新的导出，请向 dataExports.create 端点发送 POST 请求。
  如需了解详情，请参阅 CreateDataExport 端点。

监控数据导出作业状态

查看特定导出作业的数据导出作业详细信息和状态，或设置过滤条件以查看特定类型的作业。

• 如需查看特定导出作业，请参阅 GetDataExport。

• 如需使用过滤条件列出特定类型的数据导出作业，请参阅 ListDataExport。

管理已加入队列的作业

当作业处于 IN_QUEUE 状态时，您可以修改或取消该作业。

• 如需更改参数（例如时间范围、日志类型列表或目标存储桶），请参阅 UpdateDataExport。

• 如需取消已排队的作业，请参阅 CancelDataExport。

排查常见问题

该 API 提供详细的错误消息，可帮助您诊断问题。

规范代码	错误消息
INVALID_ARGUMENT	INVALID_REQUEST：请求参数 <Parameter1, Parameter2,..> 无效。请修正请求参数，然后重试。
NOT_FOUND	BUCKET_NOT_FOUND：目标 Google Cloud Storage 存储桶 <bucketName> 不存在。请创建目标 Google Cloud Storage 存储桶，然后重试。
NOT_FOUND	REQUEST_NOT_FOUND：dataExportId:<dataExportId> 不存在。请添加有效的 dataExportId，然后重试。
FAILED_PRECONDITION	BUCKET_INVALID_REGION：Google Cloud Storage 存储桶 <bucketId> 的区域 <region1> 与 SecOps 租户区域 <region2> 不同。请在 SecOps 租户所在的区域中创建 Google Cloud Storage 存储桶，然后重试。
FAILED_PRECONDITION	INSUFFICIENT_PERMISSIONS：服务账号 <P4SA> 对目标 Google Cloud Storage 存储桶 <bucketName> 没有 storage.objects.create、storage.objects.get 和 storage.buckets.get 权限。请向该服务账号授予所需访问权限，然后重试。
FAILED_PRECONDITION	INVALID_UPDATE：请求状态处于 <status> 阶段，无法更新。只有当请求处于 IN_QUEUE 阶段时，您才能更新该请求。
FAILED_PRECONDITION	INVALID_CANCELLATION：相应请求的状态处于 <status> 阶段，无法取消。只有当状态为“排队中”时，您才能取消请求。
RESOURCE_EXHAUSTED	CONCURRENT_REQUEST_LIMIT_EXCEEDED：请求大小 <sizelimit> 已达到并发请求数量上限 <limit>。请等待现有请求完成，然后重试。
RESOURCE_EXHAUSTED	REQUEST_SIZE_LIMIT_EXCEEDED：相应请求的估计导出量 <estimatedVolume> 大于每个请求允许的最大导出量 <allowedVolume>。请重新尝试，确保请求的导出量在允许的上限范围内。
INTERNAL	INTERNAL_ERROR：发生了内部错误。请重试。

需要更多帮助？获得社区成员和 Google SecOps 专业人士的解答。