使用 Knowledge Catalog 管理 AlloyDB 资源

所有新的 AlloyDB 集群默认启用 Knowledge Catalog 集成，让您可以使用 Knowledge Catalog 搜索和管理 AlloyDB for PostgreSQL 资源。Knowledge Catalog 是一个可用于存储、管理和访问元数据的平台。此集成可帮助您发现和了解 AlloyDB 元数据，支持以下使用情形：

• 分析：了解依赖关系并评估针对各种应用场景的适用性。
• 变更管理：有效跟踪和管理元数据变更。
• 架构演变：监控和规划架构修改。

Knowledge Catalog 会自动从 AlloyDB 集群、实例、数据库、表、列和视图中检索以下元数据：

• 名称
• 位置（区域）
• 标签（适用于集群和实例）
• 已启用 Dataplex 集成（针对集群）
• 数据库版本
• 机器 CPU 数量（针对实例）
• 可用性类型（适用于实例）
• 字符集（适用于数据库）
• 排序规则（适用于数据库）
• 所有者
• 说明（适用于表、视图、列和外键）
• 类型（适用于集群、实例和机器）
• 列
  • 数据类型
  • 模式
• 主键
• 外键
  • 引用的表
  • 列映射
• 创建时间
• 上次修改时间

如需了解详情，请参阅 Knowledge Catalog 中的元数据管理简介。

元数据发现类型

Knowledge Catalog 元数据发现是一个自动化流程，用于扫描已连接的数据源（例如 AlloyDB），以识别表、视图和数据库等数据资产。然后，Knowledge Catalog 会将资产中的技术元数据（例如架构、说明和位置）提取到 Knowledge Catalog 中。

此进程会近乎实时地同步元数据，从而使目录与源系统保持同步。对于 AlloyDB，系统默认会发现集群和实例元数据。在新集群上，系统默认会启用数据库、架构、表和视图元数据发现功能。对于在实现此默认设置（2026 年 2 月 26 日）之前创建的集群，请手动启用集成。

关键字搜索和自然语言搜索

Knowledge Catalog 支持关键字搜索和自然语言搜索。

• 借助关键字搜索，您可以使用特定关键字、过滤条件和定义的语法来查找资源。例如，如需查看所有 AlloyDB 数据库，请输入 system=AlloyDB AND type=Database。
• 自然语言搜索使用 AI 来理解语义查询。借助它，您可以使用日常语言查找资源，无需使用复杂的语法。例如，输入 List all AlloyDB tables related to sales 等查询内容。

如需了解详情，请参阅 Knowledge Catalog 的搜索语法。

示例：发现 AlloyDB 数据库架构

为了解元数据发现过程，不妨考虑一个名为 user-data-cluster 且已启用 Knowledge Catalog 集成的 AlloyDB 集群示例。在此集群的主实例中，有一个名为 profiles 的数据库，其中包含一个表 customers（id、email、signup_date）和一个视图 active_users（id、email）。

由于 AlloyDB 会近乎实时地与 Knowledge Catalog 同步，因此以下资源可供使用：

• 集群
• 列
• 数据库
• 实例
• 表格
• 视图

发现完成后，您可以在 Google Cloud 控制台的 Knowledge Catalog 页面中或使用 API 搜索这些资产（customers 表和 active_users）。然后，查看其架构，并使用其他业务或运营元数据丰富这些资产。

使用切面丰富元数据

切面类型是可重复使用的资源，可用作切面的模板。切面类型有助于避免重复性工作和创建不完整的切面。 使用 Knowledge Catalog 创建必要的切面类型。

创建自定义切面类型后，将切面关联到 AlloyDB 资产。通过将切面关联到 AlloyDB 资产，您可以执行以下操作：

• 将资产元数据添加到资产。
• 按业务元数据和其他自定义元数据搜索资产。

如需详细了解如何创建切面类型并将切面附加到 AlloyDB，请参阅管理切面并丰富元数据。

元数据发现工作流

默认情况下，集群和实例资源会被注入并可供发现。如需注入和发现数据库、架构、表和视图资源，请按以下步骤操作：

1. 使用 AlloyDB API 为 AlloyDB 集群启用 Knowledge Catalog 集成（如果尚未启用）。对于 2026 年 2 月 26 日之前创建的集群，这是必需的。

2. 使用 Google Cloud 控制台中的 Knowledge Catalog 搜索页面搜索 AlloyDB 资产。如需了解详情，请参阅在 Knowledge Catalog 中搜索资源。

3. 如需为 AlloyDB 资产添加更多上下文，请将切面附加到资产。切面是自定义元数据条目，有助于进行数据治理和分析。例如，您可以使用切面来标记包含个人身份信息 (PII) 的列。如需了解详情，请参阅管理切面并丰富元数据。

4. 您可以按照以下层次结构浏览 AlloyDB 资源：集群 > 数据库 > 架构 > 表或视图 > 列。此层次结构可让您详细了解自己的数据格局。如需了解详情，请参阅在 Knowledge Catalog 中搜索资源。

准备工作

登录您的 Google Cloud 账号。如果您是 Google Cloud新手，请 创建一个账号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金，用于运行、测试和部署工作负载。

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. 为项目启用 Dataplex API。

   启用 Dataplex API

2. 请检查权限。

   您必须拥有特定的 Identity and Access Management (IAM) 角色和权限才能搜索条目并将其关联到 AlloyDB 资产。如需了解详情，请参阅 Knowledge Catalog 所需的 IAM 角色和权限。

所需 IAM 角色

本部分介绍搜索资源和访问搜索结果所需的角色和权限。

访问搜索结果所需的角色

如需在 Knowledge Catalog 中搜索和查看 AlloyDB 元数据，正文必须拥有查看 AlloyDB 资源的权限，包括 dataplex.projects.search 权限。

如需向主账号（例如用户、组或服务账号）授予这些权限，请向其分配包含 AlloyDB 资源的项目的 AlloyDB Viewer (roles/alloydb.viewer) IAM 角色。

如果您不想使用预定义的 AlloyDB Viewer 角色，请分配包含 alloydb.clusters.get、alloydb.instances.get 和 alloydb.databases.get 权限的自定义角色。

如需详细了解如何授予角色，请参阅管理访问权限。 如需详细了解 AlloyDB IAM 角色，请参阅 AlloyDB 的 IAM 角色和权限。

搜索条目所需的角色

您必须在用于搜索的项目中至少拥有下列一个 IAM 角色：

• Dataplex Catalog Admin (roles/dataplex.catalogAdmin)
• Dataplex Catalog Editor (roles/dataplex.catalogEditor)
• Dataplex Catalog Viewer (roles/dataplex.catalogViewer)

搜索结果的权限检查独立于所选项目。如需了解详情，请参阅使用 Knowledge Catalog 搜索数据资产。

Knowledge Catalog 集成数据新鲜度

默认情况下，Knowledge Catalog 会注入并发现集群和实例资源，并且其元数据新鲜度近乎实时。

创建新的 AlloyDB 集群时，系统会默认启用针对数据库、架构、表和视图资源的 Knowledge Catalog 集成。如需阻止同步此元数据，请停用集成。

启用集成后，系统会启用 AlloyDB 元数据（例如数据库、架构和表）导出到 Cloud Storage 存储分区以进行定期同步或导出到 Pub/Sub 主题以进行近乎实时的同步，从而使 Knowledge Catalog 可以使用这些元数据。此功能仅适用于主集群。用于跨区域复制的辅助集群不支持将数据库、架构、表和视图元数据与 Knowledge Catalog 集成。

这些资源的元数据新鲜度取决于集群的创建或恢复时间：

• 近乎实时：在 2026 年 4 月 3 日当天或之后创建或恢复的集群会近乎实时地将元数据同步到 Knowledge Catalog。更新最多可能需要 5 分钟才会显示在 Knowledge Catalog 中。提取过程通常需要几秒钟。

• 每隔几个小时：在 2026 年 2 月 26 日至 2026 年 4 月 3 日期间创建或恢复的集群每隔几个小时会在 Knowledge Catalog 中刷新元数据。Knowledge Catalog 中的更新最多可能需要 48 小时才能生效。提取过程通常需要几分钟，但完成时间取决于 CPU 大小和表数量。

创建已停用 Knowledge Catalog 集成的 AlloyDB

您可以在使用 Google Cloud CLI 或 AlloyDB API 创建或更新集群时控制此集成：

gcloud alloydb clusters create CLUSTER_ID \
    --password=PASSWORD \
    --region=REGION \
    --no-enable-dataplex-integration

{
  "databaseVersion": "DATABASE_VERSION",
  "initialUser": {
    "user": "INITIAL_USERNAME",
    "password": "INITIAL_USER_PASSWORD"
  },
  "labels": {
    "test": "alloydb-cluster-full"
  },
  "dataplexConfig" : {
    "enabled" : false
  }
}

POST https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/clusters?cluster_id=CLUSTER_ID

    curl -X POST \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json; charset=utf-8" \
         -d @request.json \
        "https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/clusters?cluster_id=CLUSTER_ID"
      

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/clusters?cluster_id=CLUSTER_ID"| Select-Object -Expand Content

{
  "kind": "alloydb#operation",
  "targetLink": "https://alloydb.googleapis.com/v1/projects/PROJECT_ID/clusters/CLUSTER_ID",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2024-09-25T22:19:33.735Z",
  "operationType": "CREATE",
  "name": "OPERATION_ID",
  "targetId": "CLUSTER_ID",
  "selfLink": "https://alloydb.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

为 AlloyDB 集群启用 Knowledge Catalog 集成

如需在现有集群上启用 Knowledge Catalog 集成，请按照以下过程之一操作：

gcloud alloydb clusters update CLUSTER_ID \
    --region=REGION \
    --enable-dataplex-integration

PATCH https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/clusters/CLUSTER_ID?updateMask=dataplexConfig.enabled

{
  "dataplexConfig": {
    "enabled": true
  }
}

    curl -X PATCH \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json; charset=utf-8" \
         -d @request.json \
        "https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/clusters/CLUSTER_ID?updateMask=dataplexConfig.enabled"
      

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/clusters/CLUSTER_ID?updateMask=dataplexConfig.enabled"| Select-Object -Expand Content

{
  "kind": "alloydb#operation",
  "targetLink": "https://alloydb.googleapis.com/v1/projects/PROJECT_ID/clusters/CLUSTER_ID",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2024-09-25T22:19:33.735Z",
  "operationType":