我们已重新整理文档导航结构，使其与您的运营工作流程直接保持一致。如需了解详情，请参阅版本说明和演示视频。

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

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

支持的平台：

Google SecOps SIEM

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

如需详细了解 API 参考文档，请参阅数据导出 API（增强版）。

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

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

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

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

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

主要优势

数据导出 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 目标位置并授予必要的权限：

向用户授予权限。如需使用数据导出 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 Cloud Storage 存储桶（用于存储导出的数据），该存储分区应与您的 Google SecOps 租户位于同一区域。设为私密，以防止未经授权的访问。如需了解详情，请参阅创建存储桶。
向服务账号授予权限。请执行以下操作，向与您的 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."
}
```
2. 向 Google SecOps 服务账号正文授予以下 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.`