此页面由 Cloud Translation API 翻译。

将 Cloud Audit Logs 与 Cloud Storage 结合使用

本页面提供有关将 Cloud Audit Logs 与 Cloud Storage 搭配使用的补充信息。使用 Cloud Audit Logs 为 Cloud Storage 中执行的 API 操作生成日志。

概览

Google Cloud 服务会写入审核日志，便于您了解在您的 Google Cloud 资源中“谁在何时何地执行了什么操作”。您还可以将自定义信息附加到审核日志，以获取有关资源访问方式的更精细信息。

Google Cloud 项目只包含直接属于 Google Cloud 项目的资源的审核日志。其他 Google Cloud 资源（例如文件夹、组织和结算账号）包含实体本身的审核日志。

如需大致了解 Cloud Audit Logs，请参阅 Cloud Audit Logs 概览。如需深入了解审核日志格式，请参阅了解审核日志。

可用的审核日志

Cloud Storage 提供以下类型的审核日志：

管理员活动审核日志：与修改 Cloud Storage 资源访问权限的操作对应的条目，以及与恢复存储分区或创建、删除或修改存储分区、托管式文件夹或资产清单报告配置的操作对应的条目。
数据访问审核日志：与管理员活动审核日志中未跟踪的操作对应的条目。数据访问审核日志具有以下几种子类型：
- ADMIN_READ：与读取访问配置、读取存储桶元数据或列出项目中的存储桶的操作对应的条目。
- DATA_READ：与读取或列出存储桶以外的 Cloud Storage 资源的操作对应的条目。
- DATA_WRITE：与创建、修改、删除或恢复对象的操作、创建、修改或删除 XML API 分段上传的操作，或创建、删除或重命名文件夹的操作对应的条目。
如需接收数据访问审核日志，您必须明确启用这些日志。

除了 Cloud Storage 的审核日志之外，Cloud Audit Logs 还可以为存储空间分析创建审核日志。每当创建、更新和提取资产清单报告配置以及提取资产清单报告时，系统都会生成存储空间分析审核日志。

如需查看审核日志类型的更完整说明，请参阅审核日志类型。

审核的操作

下表汇总了与每种审核日志类型相对应的 Cloud Storage 操作：

审核日志类型	子类型	Cloud Storage 操作
管理员活动	`ADMIN_WRITE`	设置/更改 IAM 政策更改对象 ACL¹ 创建存储桶删除存储桶更新存储桶元数据创建托管文件夹删除托管文件夹创建资产清单报告配置更新资产清单报告配置删除资产清单报告配置恢复已软删除的存储分区
数据访问	`ADMIN_READ`	获取 IAM 政策获取对象 ACL 获取存储桶元数据列出存储分区
数据访问	`DATA_READ`	获取对象数据获取对象元数据列出对象获取文件夹元数据列出文件夹获取托管文件夹元数据列出托管文件夹复制对象² 组合对象² 列出正在进行的 XML API 分段上传列出 XML API 分段上传部分获取资产清单报告配置列出资产清单报告配置获取资产清单报告列出资产清单报告
数据访问	`DATA_WRITE`	创建对象删除对象恢复软删除的对象更新非 ACL 对象元数据复制对象¹ 编排对象¹ 启动 XML API 分段上传在 XML API 分段上传中创建部分取消 XML API 分段上传完成 XML API 分段上传创建文件夹删除文件夹重命名文件夹

¹ 如果最初在创建对象时设置了 ACL，则系统不会生成管理员活动审核日志。此外，如果对象 ACL 设置为“公开”，则系统不会为针对该对象或其 ACL 的读取或写入生成审核日志。

² 这些操作涉及读取和写入数据。因此，这些操作都会生成两个日志条目。

限制

将 Cloud Audit Logs 与 Cloud Storage 结合使用要受以下限制的约束：

Cloud Audit Logs 不跟踪对公开对象执行的访问。
Cloud Audit Logs 不跟踪对象生命周期管理或 Autoclass 功能做出的更改。
当下载发生在 Google Cloud 控制台之外时，系统会隐去通过经过身份验证的浏览器下载生成的数据访问日志的 principalEmail 和 callerIp 字段。

如果您需要在上述任一情况下使用日志记录功能，请考虑使用 Cloud Storage 使用情况日志。

审核日志格式

审核日志条目包含以下组件：

日志条目本身，即 LogEntry 对象。以下是一些实用的字段：
- logName 包含资源 ID 和审核日志类型。
- resource 包含所审核操作的目标。
- timestamp 包含所审核操作的时间。
- protoPayload 包含审核的信息。
审核日志记录数据，即保存在日志条目的 protoPayload 字段中的 AuditLog 对象。
特定于 Cloud Storage 的可选审核信息，包括详细的请求和响应信息；如需了解详情，请参阅详细的审核日志记录模式。请注意，您无需强制执行详细的审核日志记录，即可将自定义信息附加到审核日志。

如需了解上述对象中的其他字段以及如何解读这些字段，请参阅了解审核日志。

日志名称

Cloud Audit Logs 日志名称包含资源标识符，指明了审核日志所属的 Google Cloud 项目或其他 Google Cloud 实体，以及日志是包含管理员活动还是数据访问审核日志记录数据。

以下是审核日志名称，包括资源标识符的变量：

   projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Factivity
   projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Fdata_access

   folders/FOLDER_ID/logs/cloudaudit.googleapis.com%2Factivity
   folders/FOLDER_ID/logs/cloudaudit.googleapis.com%2Fdata_access

   billingAccounts/BILLING_ACCOUNT_ID/logs/cloudaudit.googleapis.com%2Factivity
   billingAccounts/BILLING_ACCOUNT_ID/logs/cloudaudit.googleapis.com%2Fdata_access

   organizations/ORGANIZATION_ID/logs/cloudaudit.googleapis.com%2Factivity
   organizations/ORGANIZATION_ID/logs/cloudaudit.googleapis.com%2Fdata_access

服务名称

Cloud Storage 审核日志使用服务名称 storage.googleapis.com。

存储空间分析审核日志使用服务名称 storageinsights.googleapis.com。

如需查看所有 Cloud Logging API 服务名称及其相应受监控资源类型的列表，请参阅将服务映射到资源。

资源类型

Cloud Storage 审核日志使用 gcs_bucket 资源类型。

如需查看所有 Cloud Logging 受监控资源类型和说明信息的列表，请参阅受监控的资源类型。

启用审核日志记录

系统在任何情况下都会启用管理员活动审核日志，无法停用。

数据访问审核日志默认处于停用状态，除非明确启用，否则无法向其中写入数据。

如需了解如何启用部分或全部数据访问审核日志，请参阅配置数据访问审核日志。

权限和角色

IAM 权限和角色决定了您能否访问 Google Cloud 资源中的审核日志数据。

在决定哪些特定于 Logging 的权限和角色适用于您的使用场景时，请考虑以下因素：

Logs Viewer 角色 (roles/logging.viewer) 为您提供对管理员活动、政策拒绝和系统事件审核日志的只读权限。如果您只具有此角色，则无法查看 _Required 和 _Default 存储桶中的数据访问审核日志。
Private Logs Viewer 角色 ((roles/logging.privateLogViewer) 包含 roles/logging.viewer 具有的权限，以及读取 _Required 和 _Default 存储桶中的数据访问审核日志的权限。

请注意，如果这些私密日志存储在用户定义的存储桶中，则有权读取这些存储桶中的日志的任何用户都可以读取这些私密日志。如需详细了解日志存储桶，请参阅路由和存储概览。

如需详细了解适用于审核日志数据的 IAM 权限和角色，请参阅使用 IAM 进行访问权限控制。

查看日志

您可以查询所有审核日志，也可以按其审核日志名称来查询日志。审核日志名称包含您要查看其审核日志记录信息的 Google Cloud 项目、文件夹、结算账号或组织的资源标识符。您的查询可以指定已编入索引的 LogEntry 字段。如需详细了解如何查询日志，请参阅在日志浏览器中构建查询

您可以使用日志浏览器查看和过滤各个日志条目。如果您想使用 SQL 分析一组日志条目，请使用 Log Analytics 页面。如需了解详情，请参阅以下主题：

您可以使用 Google Cloud 控制台、Google Cloud CLI 或 Logging API 在 Cloud Logging 中查看大多数审核日志。不过，对于与结算相关的审核日志，您只能使用 Google Cloud CLI 或 Logging API。

控制台

在 Google Cloud 控制台中，您可以使用 Logs Explorer 来检索 Google Cloud 项目、文件夹或组织的审核日志条目：

在 Google Cloud 控制台中，转到 Logs Explorer 页面。
前往 Logs Explorer

如果您使用搜索栏查找此页面，请选择子标题为 Logging 的结果。
选择现有的 Google Cloud 项目、文件夹或组织。
如需显示所有审核日志，请在查询编辑器字段中输入以下任一查询，然后点击运行查询：
```
logName:"cloudaudit.googleapis.com"
```
```
protoPayload."@type"="type.googleapis.com/google.cloud.audit.AuditLog"
```
如需显示特定资源和审核日志类型的审核日志，请在查询构建器窗格中执行以下操作：
- 在资源类型中，选择要查看其审核日志的 Google Cloud 资源。
- 在日志名称中，选择要查看的审核日志类型：
  - 对于管理员活动审核日志，选择 activity。
  - 对于数据访问审核日志，选择 data_access。
  - 对于系统事件审核日志，选择 system_event。
  - 对于政策拒绝审核日志，选择 policy。
- 点击运行查询。
如果您没有看到这些选项，则表示 Google Cloud 项目、文件夹或组织中没有该类型的任何审核日志。

如果您在尝试从日志浏览器中查看日志时遇到问题，请参阅问题排查信息。

如需详细了解如何使用日志浏览器进行查询，请参阅在日志浏览器中构建查询。

gcloud

Google Cloud CLI 为 Logging API 提供了命令行界面。在每个日志名称中提供有效的资源标识符。例如，如果您的查询包含 PROJECT_ID，则您提供的项目标识符必须引用当前选择的 Google Cloud 项目。

如需读取 Google Cloud 项目级层审核日志条目，请运行以下命令：

gcloud logging read "logName : projects/PROJECT_ID/logs/cloudaudit.googleapis.com" \
    --project=PROJECT_ID

如需读取文件夹级审核日志条目，请运行以下命令：

gcloud logging read "logName : folders/FOLDER_ID/logs/cloudaudit.googleapis.com" \
    --folder=FOLDER_ID

如需读取组织级审核日志条目，请运行以下命令：

gcloud logging read "logName : organizations/ORGANIZATION_ID/logs/cloudaudit.googleapis.com" \
    --organization=ORGANIZATION_ID

如需读取 Cloud Billing 账号级层审核日志条目，请运行以下命令：

gcloud logging read "logName : billingAccounts/BILLING_ACCOUNT_ID/logs/cloudaudit.googleapis.com" \
    --billing-account=BILLING_ACCOUNT_ID

在命令中添加 --freshness 标志可读取超过 1 天的日志。

如需详细了解如何使用 gcloud CLI，请参阅 gcloud logging read。

REST

构建查询时，请在每个日志名称中提供有效的资源标识符。例如，如果您的查询包含 PROJECT_ID，则您提供的项目标识符必须引用当前选择的 Google Cloud 项目。

例如，要使用 Logging API 查看项目级的审核日志条目，请执行以下操作：

前往 entries.list 方法文档中的试用此 API 部分。
将以下内容添加到试用此 API 表单的请求正文部分。点击此预填充的表单后，系统会自动填充请求正文，但您需要在每个日志名称中提供一个有效的 PROJECT_ID。
```
{
  "resourceNames": [
    "projects/PROJECT_ID"
  ],
  "pageSize": 5,
  "filter": "logName : projects/PROJECT_ID/logs/cloudaudit.googleapis.com"
}
```
点击执行。

将自定义信息添加到审核日志

您可以在请求中添加 x-goog-custom-audit-KEY: VALUE 标头，将自定义信息附加到审核日志。XML API 请求还支持使用 x-goog-custom-audit-KEY=VALUE 查询参数。自定义信息会添加到审核日志条目的 protoPayload 的 metadata 字段中。

添加自定义审核信息时，请注意以下事项：

每个 KEY 最多可包含 64 个字符，而每个 VALUE 最多可包含 1,200 个字符。
每个请求最多可包含 4 个标头或参数条目组合。

标头条目示例

以下列表展示了您可以在标头条目中添加的键值对示例：

x-goog-custom-audit-job: test-job-id-here
x-goog-custom-audit-user: user ID test 1
x-goog-custom-audit-internal-user-id: MATR2022-11
x-goog-custom-audit-tracking-ticket: TT/1516512851
x-goog-custom-audit-justification: Removed customer identity record at customer request
x-goog-custom-audit-customer-id: USCU12315154

示例请求

命令行

gcloud storage hash gs://example_bucket/example_object.jpeg --additional-headers=x-goog-custom-audit-job="job name",x-goog-custom-audit-user="test user"

客户端库

C++

如需了解如何将自定义标头添加到请求，请参阅添加自定义标头。

C#

如需了解如何将自定义标头添加到请求，请参阅添加自定义标头。

Go

如需了解如何将自定义标头添加到请求，请参阅添加自定义标头。

Java

如需了解如何将自定义标头添加到请求，请参阅添加自定义标头。

Node.js

如需了解如何将自定义标头添加到请求，请参阅添加自定义标头。

PHP

如需了解如何将自定义标头添加到请求，请参阅添加自定义标头。

Python

如需了解如何将自定义标头添加到请求，请参阅添加自定义标头。

Ruby

如需了解如何将自定义标头添加到请求，请参阅添加自定义标头。

REST API

JSON API

curl -X GET "https://storage.googleapis.com/storage/v1/b/example_bucket/o/example_object" \
-H "Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg" \
-H "x-goog-custom-audit-job: job name" \
-H "x-goog-custom-audit-user: test user"

XML API

curl -X GET "https://storage.googleapis.com/example_bucket/example_object" \
-H "Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg" \
-H "x-goog-custom-audit-job: job name" \
-H "x-goog-custom-audit-user: test user"

签名网址请求

curl -X GET 'storage.googleapis.com/example_bucket?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=example%40example-project.iam.gserviceaccount.com%2F20181026%2Fus-central1%2Fstorage%2Fgoog4_request&X-Goog-Date=20181026T181309Z&X-Goog-Expires=900&X-Goog-SignedHeaders=host,x-goog-custom-audit-job,x-goog-custom-audit-user&X-Goog-Signature=247a2aa45f169edf4d187d54e7cc46e4731b1e6273242c4f4c39a1d2507a0e58706e25e3a85a7dbb891d62afa8496def8e260c1db863d9ace85ff0a184b894b117fe46d1225c82f2aa19efd52cf21d3e2022b3b868dcc1aca2741951ed5bf3bb25a34f5e9316a2841e8ff4c530b22ceaa1c5ce09c7cbb5732631510c20580e61723f5594de3aea497f195456a2ff2bdd0d13bad47289d8611b6f9cfeef0c46c91a455b94e90a66924f722292d21e24d31dcfb38ce0c0f353ffa5a9756fc2a9f2b40bc2113206a81e324fc4fd6823a29163fa845c8ae7eca1fcf6e5bb48b3200983c56c5ca81fffb151cca7402beddfc4a76b133447032ea7abedc098d2eb14a7' \
-H "x-goog-custom-audit-job: job name" \
-H "x-goog-custom-audit-user: test user"

请注意，X-Goog-SignedHeaders 中还必须包含自定义审核标头。

如需创建支持添加自定义审核标头的签名网址请求，当您生成签名网址时，还必须包含要在请求中使用的自定义审核标头。例如：

gcloud storage sign-url gs://example_bucket/example_object.jpeg --private-key-file=example-key.json --duration=10m --headers=x-goog-custom-audit-job:"job name",x-goog-custom-audit-user="test user"

您还可以在设置自定义标头时使用客户端库生成签名网址。

除了使用签名标头之外，您还可以使用查询参数来传递自定义审核条目。

curl -X GET 'storage.googleapis.com/example_bucket?X-Goog-Custom-Audit-Key=Value&X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=example%40example-project.iam.gserviceaccount.com%2F20181026%2Fus-central1%2Fstorage%2Fgoog4_request&X-Goog-Date=20181026T181309Z&X-Goog-Expires=900&X-Goog-SignedHeaders=host&X-Goog-Signature=247a2aa45f169edf4d187d54e7cc46e4731b1e6273242c4f4c39a1d2507a0e58706e25e3a85a7dbb891d62afa8496def8e260c1db863d9ace85ff0a184b894b117fe46d1225c82f2aa19efd52cf21d3e2022b3b868dcc1aca2741951ed5bf3bb25a34f5e9316a2841e8ff4c530b22ceaa1c5ce09c7cbb5732631510c20580e61723f5594de3aea497f195456a2ff2bdd0d13bad47289d8611b6f9cfeef0c46c91a455b94e90a66924f722292d21e24d31dcfb38ce0c0f353ffa5a9756fc2a9f2b40bc2113206a81e324fc4fd6823a29163fa845c8ae7eca1fcf6e5bb48b3200983c56c5ca81fffb151cca7402beddfc4a76b133447032ea7abedc098d2eb14a7'

当您生成签名网址时，必须包含这些查询参数。例如：

gcloud storage sign-url gs://example_bucket/example_object.jpeg --private-key-file=example-key.json --duration=10m --query-params=x-goog-custom-audit-job=job_name,x-goog-custom-audit-user=test_user

日志条目示例

protoPayload: {
  @type: "type.googleapis.com/google.cloud.audit.Auditlog",
  ...
  metadata: {
    audit_context: {
      app_context: "EXTERNAL",
      audit_info: {
        x-goog-custom-audit-job: "job name",
        x-goog-custom-audit-user: "test user"
      }
    }
  }
}

如需详细了解类型为 type.googleapis.com/google.cloud.audit.Auditlog 的 protoPayload 对象中包含的字段，请参阅 AuditLog 参考文档。

路由审核日志

您可以将审核日志路由到受支持的目标位置，方式与路由其他类型的日志相同。以下是您可能需要路由审核日志的一些原因：

如需长时间保留审核日志或使用更强大的搜索功能，您可以将审核日志的副本路由到 Cloud Storage、BigQuery 或 Pub/Sub。您可以使用 Pub/Sub 将内容路由到其他应用、其他代码库和第三方工具。
如需管理整个组织范围内与您相关的审核日志，您可以创建一个汇总接收器，以便从组织中的任何或所有 Google Cloud 项目路由日志。
如果启用的数据访问审核日志会导致 Google Cloud 项目超出免费配额，您可以创建接收器，以从 Logging 中排除数据访问审核日志。

如需了解如何路由日志，请参阅配置和管理接收器。

价格

如需了解 Cloud Logging 价格，请参阅 Google Cloud Observability 价格：Cloud Logging。