迁移到 Security Command Center API v2

本页介绍了 Security Command Center API 的版本 1 (v1) 和版本 2 (v2) 之间的区别。本文还介绍了如何结合使用 v1 Security Command Center Management API 迁移到 v2 Security Command Center API。

自 2024 年 12 月 9 日起，如果您首次在组织中激活 Security Command Center，则必须在该组织中仅使用 Security Command Center API 的版本 2。早期版本不支持。

如果您在 2024 年 12 月 9 日之前在项目级层激活了 Security Command Center，那么您在同一组织中激活的任何项目都将支持所有可用的 Security Command Center API 版本。

对于与 Security Command Center 的所有集成，我们建议您采用 v2 Security Command Center API 和 v1 Security Command Center Management API。我们建议使用 Cloud 客户端库或 Google Cloud Terraform 提供程序来调用这些 API。详情请参阅以下内容：

Terraform

• Security Command Center API 资源
• Security Command Center Management API 资源

客户端库

• Security Command Center API 客户端库
• Security Command Center Management API 客户端库

v1 和 v2 API 之间的差异

在迁移到 v2 Security Command Center API 时，请注意以下与 v1 API 的区别。

数据驻留

v2 Security Command Center API 支持数据驻留，可让您更好地控制 Security Command Center 数据的位置。

如果为您的组织启用了数据驻留，那么您必须执行以下操作，才能访问受数据驻留控制措施约束的资源：

• 使用区域性服务端点访问资源。
• 在调用资源的方法时指定位置。

如果您的组织未启用数据驻留，建议您调用每种方法的位置感知版本，并指定 global 位置。这样做可让您日后更轻松地采用数据驻留功能。

如需使用每个方法的感知位置信息版本，请执行以下操作：

控制台

Google Cloud 控制台会在必要时使用每个方法的位置感知版本。

gcloud

运行允许您指定位置的 gcloud CLI 命令（例如 gcloud scc findings list）时，请务必提供位置。您可以采用以下几种方法：

• 使用 --location 标志。
• 如果您提供资源名称的完整路径，请使用指定位置的格式，例如 projects/123/sources/456/locations/global/findings/a1b2c3。

Terraform

对于支持 location 实参的资源（例如 google_scc_v2_organization_mute_config），请务必提供该实参。

REST

调用名称中包含 locations 的方法版本。例如，调用 organizations.locations.findings.bulkMute 而不是 organizations.findings.bulkMute。

客户端库

请参阅 Security Command Center 的代码示例或客户端库的 API 参考文档。

如需了解如何在启用数据驻留功能的情况下使用区域端点，请参阅 Security Command Center 区域端点。

通知配置和 BigQuery 导出配置

借助 v1 Security Command Center API，您可以创建和管理以下类型的导出配置：

• 通知配置，用于将发现结果发送到 Pub/Sub
• BigQuery 导出配置，用于将发现结果流式传输到 BigQuery

您还可以使用 v2 Security Command Center API 创建和管理这些导出配置。不过，如果您使用 v1 Security Command Center API 创建导出配置，则该配置不会显示在 v2 Security Command Center API 中。同样，如果您使用 v2 Security Command Center API 创建导出配置，则该配置不会显示在 v1 Security Command Center API 中。

此外，使用 v2 Security Command Center API 创建的导出配置无法使用 source_properties 字段过滤发现结果。您必须改用其他字段。

控制台

在 Google Cloud 控制台中，如果导出配置是使用 v1 Security Command Center API 创建的，则会带有旧版标签。您可以使用Google Cloud 控制台管理这些资源。

如果您在 Google Cloud 控制台中创建新的导出配置，则该配置始终是使用 v2 Security Command Center API 创建的。

gcloud

如需管理使用 v1 Security Command Center API 创建的导出配置，请在运行 gcloud CLI 命令（例如 gcloud scc notifications describe）时不要指定位置：

• 请勿使用 --location 标志。
• 如果您提供配置 ID 的完整路径，请使用不指定位置的格式，例如 organizations/123/notificationConfigs/456。请勿使用 organizations/123/locations/global/notificationConfigs/456 等格式。

同样，如需使用 v2 Security Command Center API 创建或管理导出配置，请在运行 gcloud CLI 命令时指定位置。创建新配置时，我们建议您使用 v2 Security Command Center API。

Terraform

您的 Terraform 配置文件将导出配置定义为 v1 或 v2 资源。例如，请参阅以下有关通知配置的资源：

• v1
  • google_scc_notification_config
  • google_scc_folder_notification_config
  • google_scc_project_notification_config
• v2
  • google_scc_v2_organization_notification_config
  • google_scc_v2_folder_notification_config
  • google_scc_v2_project_notification_config

创建新配置时，建议您创建 v2 资源。

REST

如需管理使用 v1 Security Command Center API 创建的导出配置，您必须使用 v1 Security Command Center API。

创建新配置时，我们建议您使用 v2 Security Command Center API。

客户端库

如需管理使用 v1 Security Command Center API 创建的导出配置，您必须使用 v1 Security Command Center API 的 Cloud 客户端库。

创建新配置时，我们建议您使用 v2 Security Command Center API。

内置服务和自定义模块

借助 v1 Security Command Center API，您可以查看和更新以下资源类型：

• Security Command Center 内置服务及其启用状态
• 以下内置服务的自定义模块：
  • Event Threat Detection
  • Security Health Analytics

如需管理这些资源类型，请使用 Security Command Center Management API 及其客户端库。v2 Security Command Center API 无法管理这些资源类型。

资产管理

如果您的组织在 2023 年 6 月 20 日之前激活了 Security Command Center，则您可以使用 v1 Security Command Center API 查看组织、文件夹或项目中的资产。这些 Security Command Center 资产管理功能已弃用，并且在 v2 Security Command Center API 中不可用。 这些功能将于 2024 年 6 月 20 日或之后从 v1 Security Command Center API 中移除。

不过，您可以使用 Cloud Asset Inventory 查看资产，包括其安全标记。如需了解详情，请参阅列出资源。

您还可以使用 v2 Security Command Center API 更新资产的安全标记。用于更新安全标记的 Security Command Center API 方法并未弃用。

更新了客户端库和 Terraform 提供程序

如需更新代码以使用 v2 Security Command Center API，请执行以下操作：

Terraform

安装适用于 Google Cloud的当前版本的 Terraform 提供程序。 如需了解详情，请参阅提供方文档。

此外，请更新您的 Terraform 配置文件，以创建以 google_scc_v2_ 或 google_scc_management_ 为前缀的资源。请注意，以下资源不会在 v1 和 v2 API 之间共享：

• google_scc_folder_notification_config
• google_scc_folder_scc_big_query_export
• google_scc_notification_config
• google_scc_organization_scc_big_query_export
• google_scc_project_notification_config
• google_scc_project_scc_big_query_export

如果您应用一个 Terraform 执行计划，该计划会将这些资源替换为相应的 v2 版本，那么 Terraform 将删除 v1 配置并创建新的 v2 配置。

C++

更新应用以包含客户端库的 v2 头文件：

#include "google/cloud/securitycenter/v2/security_center_client.h"

此外，请更新您的应用以使用 v2 命名空间中的类：

namespace securitycenter = ::google::cloud::securitycenter_v2;

C#

安装 v2 客户端库，然后更新您的应用以使用该库：

Install-Package Google.Cloud.SecurityCenter.V2

Go

安装 v2 客户端库，然后更新应用以使用该库：

go get cloud.google.com/go/securitycenter/apiv2

Java

安装当前版本的客户端库。如需了解详情，请参阅安装客户端库。

此外，请更新您的应用以使用 com.google.cloud.securitycenter.v2 软件包中的类、接口和枚举。

Node.js

安装当前版本的客户端库。如需了解详情，请参阅安装客户端库。

此外，请更新您的应用以使用 v2.SecurityCenterClient 以及 protos.google.cloud.securitycenter.v2 命名空间中的类、接口和枚举。

PHP

安装当前版本的客户端库。如需了解详情，请参阅安装客户端库。

此外，请更新您的应用以使用 Google \ Cloud \ SecurityCenter \ V2 命名空间中的类和枚举。

Python

安装当前版本的客户端库。如需了解详情，请参阅安装客户端库。

此外，请更新您的应用以使用 google.cloud.securitycenter_v2 软件包中的类。

Ruby

安装当前版本的客户端库。如需了解详情，请参阅安装客户端库。

此外，更新应用以在创建客户端对象时将 version 参数设置为 :v2。

如果您需要以编程方式管理 Security Command Center 的内置服务及其启用状态，或者管理 Event Threat Detection 或 Security Health Analytics 的自定义模块，则还必须安装 Security Command Center Management API 的客户端库，并更新您的应用以使用该客户端库。