Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

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

支持范围：

Google SecOps SIEM

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

如需详细了解 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 存储桶中的逻辑目录结构中，这有助于您查找和查询特定时间范围的数据，以进行历史分析。
安全性：该 API 旨在完全符合客户管理的加密密钥 (CMEK)（零信任安全性）和数据 RBAC（最小权限访问）的要求。导出作业会沿用触发请求的用户的数据公开范围，以防止未经授权的数据提取。导出流水线还与 Google Cloud Key Management Service 完全集成，数据在 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 的数据。对于较大的数据集，Google 建议将导出作业拆分为多个时间范围较小的作业。
并发作业：每个客户租户最多可以同时运行或将三个导出作业加入队列。系统会拒绝任何超出此限制的新作业创建请求。
作业完成时间：导出的数据量决定了作业完成时间。单项作业最长可能需要 18 小时。
导出格式和数据范围：该 API 支持批量、时间点导出，具有以下限制和功能：
- 仅限原始日志：您只能导出原始日志（不能导出 UDM 日志、UDM 事件或检测结果）。如需了解如何导出 UDM 数据，请参阅导出到自行管理的 BigQuery 项目。
- 数据压缩：API 会将数据导出为未压缩的文本。

前提条件和架构

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

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

向用户授予权限。如需使用 Data Export API，您需要在与 Google SecOps 租户关联的 BYOP Google Cloud 项目中拥有以下权限：
这些权限属于以下预定义 IAM 角色：
- Chronicle API Admin：授予使用 API 创建、更新、取消和查看导出作业的完整权限。此角色可授予全局访问权限。
- Chronicle API Viewer：授予只读权限，以便使用 API 查看作业配置和历史记录。如果没有 restrictedDataAccess 角色，拥有此角色的用户可以查看所有数据（请参阅+ 添加其他角色步骤和添加条件）。
向用户应用数据 RBAC 范围。如需将用户限制为特定数据访问权限范围，请执行以下操作：
1. 确保您要应用的数据 RBAC 范围已在 Google SecOps 界面中的设置 > SIEM 设置 > 数据访问 > 范围下创建。记下您要分配给用户的每个范围的全名。
2. 创建用于数据导出管理的 Identity and Access Management (IAM) 自定义角色。由于预定义角色可能会授予过多访问权限，或者不具备特定的权限组合，因此请执行以下操作，创建专为在限定范围内管理数据导出而定制的自定义角色：
  1. 在 Google Cloud 控制台中，前往 IAM 和管理 > 角色。
  2. 点击 + 创建角色。
  3. 输入标题（例如 SecOps Scoped Data Export User）。
  4. 输入 ID（例如 secopsScopedDataExportUser）。
  5. 点击 + 添加权限。
  6. 过滤 Chronicle 权限，并添加第一步（向 API 用户授予权限）中列出的相关权限。
  7. 点击创建。
向用户授予 IAM 角色。在 IAM 页面上，执行以下操作，为您的用户分配必要的角色：
1. 前往 IAM 和管理 > IAM。
2. 点击 + 授予访问权限。
3. 在新的主账号中，输入用户的邮箱。
4. 请执行以下操作来分配角色：
  1. 添加您创建的自定义角色（例如 SecOps Scoped Data Export User）。
  2. 点击 + 添加其他角色，然后添加 Chronicle API Restricted Data Access (restrictedDataAccess) 角色。此角色对于将用户标记为受数据范围约束至关重要。
向 Chronicle API Restricted Data Access 角色绑定添加 IAM 条件。请执行以下操作，将用户关联到特定数据范围：
1. 点击添加 IAM 条件。
2. 使用条件构建器或条件编辑器定义允许的范围，并将第一步中创建的范围名称用作资源名称。例如，如需使用名为 scope_test 的范围，请设置条件 resource.name.endsWith("/dataAccessScopes/scope_test")。
如需详细了解如何为 Data Export API 实现数据 RBAC，请参阅数据 RBAC 如何应用于 Data Export API。
创建 Google Cloud Storage 存储桶。在 Google Cloud项目中，在 Google SecOps 租户所在的区域中创建一个新的 Google Cloud Storage 存储桶（导出数据的目标位置）。请将其设为私密，以防止未经授权的访问。如需了解详情，请参阅创建存储桶。
向服务账号授予权限。请执行以下操作，向与 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": "service-1234@gcp-sa-chronicle.iam.gserviceaccount.com"
}
```
2. 向 Google SecOps 服务账号主账号授予目标 Google Cloud Storage 存储桶的以下 IAM 角色，以便 Google SecOps 服务将导出的数据文件写入 Google Cloud Storage 存储桶：
  - Storage object administrator (roles/storage.objectAdmin)
  - Legacy bucket reader (roles/storage.legacyBucketReader)
  如需了解详情，请参阅向 Google SecOps 服务账号授予访问权限。
完成身份验证。Data Export API 会对您的调用进行身份验证。如需设置此身份验证，请按照以下部分中的说明操作：
1. Google Cloud 服务的身份验证方法
2. 应用默认凭证

主要应用场景和核心工作流程

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

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

创建新的数据导出作业

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

如需了解如何识别 Google SecOps 实例的唯一服务账号，请参阅 FetchServiceAccountForDataExports。
如需开始新的导出，请向 dataExports.create 端点发送 POST 请求。如需了解详情，请参阅 CreateDataExport 端点。

监控数据导出作业状态

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

如需了解如何查看特定导出作业，请参阅 GetDataExport。
如需了解如何使用过滤条件列出特定类型的数据导出作业，请参阅 ListDataExport。

取消已加入队列的作业

当作业状态为 IN_QUEUE 时，您可以取消该作业。

如需了解如何取消已加入队列的作业，请参阅 CancelDataExport。

数据 RBAC 如何应用于 Data Export API

导出作业会继承创建导出作业的用户的 RBAC 范围，从而防止未经授权的数据提取。

如果您尝试导出的数据超出了数据访问权限范围，API 会在执行导出作业时自动排除此类数据。已完成作业（即状态为 FINISHED_SUCCESS 的作业）的元数据中 dataRbacFiltered 字段的值表示是否排除了数据。如果 dataRbacFiltered 为 true，则为导出作业选择的部分或全部数据已被排除，因为这些数据超出了适用于作业创建者的数据 RBAC 范围。如果 dataRbacFiltered 为 false，则导出作业未受到数据 RBAC 范围限制的影响，并且作业中包含的所有数据均已成功导出。

API 会应用在作业创建时适用于创建者的数据 RBAC 范围。数据 RBAC 范围的任何更改都不会追溯应用于已创建的作业。

如需详细了解数据 RBAC，请参阅数据 RBAC 概览。

排查常见问题

该 API 会提供详细的出错提示，以帮助诊断问题。

规范代码	出错提示
`INVALID_ARGUMENT`	`INVALID_REQUEST: Invalid request parameter PARAMETER_1, PARAMETER_2, ... PARAMETER_N. Please fix the request parameters and try again.`
`PERMISSION_DENIED`	`INSUFFICIENT_PERMISSIONS: Unable to validate request with the current CMEK key. Please fix the CMEK key and try again`
`NOT_FOUND`	`BUCKET_NOT_FOUND: The destination Google Cloud Storage bucket BUCKET_NAME does not exist. Please create the destination Google Cloud Storage bucket and try again.`
`NOT_FOUND`	`REQUEST_NOT_FOUND: The dataExportId:DATA_EXPORT_ID does not exist. Please add a valid dataExportId and try again.`
`FAILED_PRECONDITION`	`BUCKET_INVALID_REGION: The Google Cloud Storage bucket BUCKET_ID's region:REGION_1 is not the same region as the SecOps tenant region:REGION_2. Please create the Google Cloud Storage bucket in the same region as SecOps tenant and try again.`
`FAILED_PRECONDITION`	`INSUFFICIENT_PERMISSIONS: The Service Account P4SA does not have storage.objects.create, storage.objects.get and storage.buckets.get permissions on the destination Google Cloud Storage bucket BUCKET_NAME. Please provide the required access to the Service Account and try again.`
`FAILED_PRECONDITION`	`INVALID_CANCELLATION: The request status is in the STATUS stage and can't be cancelled. You can only cancel the request if the status is in the IN_QUEUE stage.`
`RESOURCE_EXHAUSTED`	`CONCURRENT_REQUEST_LIMIT_EXCEEDED: Maximum concurrent requests limit LIMIT reached for the request size SIZE_LIMIT. Please wait for the existing requests to complete and try again.`
`RESOURCE_EXHAUSTED`	`REQUEST_SIZE_LIMIT_EXCEEDED: The estimated export volume: ESTIMATED_VOLUME for the request is greater than maximum allowed export volume: ALLOWED_VOLUME per request. Please try again with a request within the allowed export volume limit.`
`INTERNAL`	`INTERNAL_ERROR: An Internal error occurred. Please try again.`