使用 Dataplex Catalog 管理 Cloud SQL 资源

本页面介绍了如何使用 Dataplex Catalog 搜索和管理 Cloud SQL 资源。

Dataplex Catalog 是一个用于存储、管理和访问元数据的平台。在 Cloud SQL 实例上启用 Dataplex Catalog 集成后，Dataplex Catalog 会自动从 Cloud SQL 实例、数据库、表、列和视图中检索以下元数据：

  • 名称
  • 位置（区域）
  • 创建日期和上次修改日期
  • 架构（适用于表和视图）
  • 说明

Dataplex Catalog 只会从 Cloud SQL 主实例中检索元数据，而不会从读取副本中检索元数据。

您可以使用 Dataplex Catalog 来发现和了解 Cloud SQL 元数据。使用 Data Catalog 可帮助完成以下活动：

  • 分析，包括依赖关系和针对应用场景的适用性
  • 变更管理
  • 数据移动（流水线）
  • 架构演变

借助 Dataplex Catalog，您可以通过将切面附加到 Cloud SQL 元数据条目来挑选元数据。每个切面可以有多个元数据字段，并且可以基于预定义或自定义切面类型。

例如，您可以将以下切面附加到包含社会保障号的列，即个人身份信息 (PII)：

  pii:true
  pii_type:SSN

如需详细了解 Dataplex Catalog，请参阅 Dataplex Catalog 概览。

准备工作

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

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

    Go to project selector

  5. Make sure that billing is enabled for your Google Cloud project.

  6. 为项目启用 Dataplex API。

    启用 Dataplex API

  7. 请检查权限。

    您需要特定的 Identity and Access Management (IAM) 角色和权限才能搜索条目并将其附加到 Cloud SQL 资产。如需了解详情，请参阅 Dataplex Catalog 所需的 IAM 角色和权限。

Dataplex Catalog 所需的 IAM 角色和权限

Cloud SQL 使用 cloudsql.schemas.view 权限提供对 Dataplex 上的元数据的访问权限。

如需提供此权限，请创建可提供此权限的自定义角色，或使用具有此权限的预定义角色之一。

如需了解详情，请参阅预定义的 Cloud SQL IAM 角色。

在 Cloud SQL 实例上启用 Dataplex Catalog 集成

如需在 Cloud SQL 实例上启用 Dataplex Catalog 集成，请按照以下过程之一操作。

gcloud

创建实例

如需创建 Cloud SQL 实例，请使用 gcloud sql instances create 命令。

gcloud sql instances create INSTANCE_NAME \
  --database-version=DATABASE_VERSION \
  --tier=MACHINE_TYPE \
  --region=REGION_NAME \
  --enable-dataplex-integration

进行以下替换：

  • INSTANCE_NAME：实例的名称
  • DATABASE_VERSION：实例的数据库版本（例如 POSTGRES_13）；如需查看可用字符串的完整列表，请参阅 SqlDatabaseVersion
  • MACHINE_TYPE：实例的机器类型
  • REGION_NAME：实例的区域名称

更新实例

如需为现有实例启用集成，请使用 gcloud sql instances patch 命令。

gcloud sql instances patch INSTANCE_NAME \
  --enable-dataplex-integration

如果您需要启用和更新项目中的所有 Cloud SQL 实例，则可以运行如下所示的脚本：

gcloud sql instances list --format="(NAME)" \
| tail -n +2 | xargs -t -I %
gcloud sql instances patch % --enable-dataplex-integration

此示例基于 Linux。

REST v1

创建实例

使用此示例创建启用了集成的实例。如需查看此调用的可用参数的完整列表，请参阅 instances.insert 页面。

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：包含实例的 Google Cloud 项目的 ID 或项目编号
  • INSTANCE_NAME：实例的名称
  • REGION_NAME：实例的区域名称
  • DATABASE_VERSION：数据库版本的枚举字符串（例如 POSTGRES_13）。如需查看可用字符串的完整列表，请参阅 SqlDatabaseVersion。
  • PASSWORD：root 用户的密码
  • MACHINE_TYPE：机器（层级）类型的枚举字符串，例如：db-custom-[CPUS]-[MEMORY_MBS]
  • EDITION_TYPE：您的 Cloud SQL 版本

HTTP 方法和网址：

POST https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances

请求 JSON 正文：

{
  "name": "INSTANCE_NAME",
  "region": "REGION_NAME",
  "databaseVersion": "DATABASE_VERSION",
  "rootPassword": "PASSWORD",
  "settings": {
    "tier": "MACHINE_TYPE",
    "edition": "EDITION_TYPE",
    "enableDataplexIntegration": true
  }
}

如需发送您的请求，请展开以下选项之一：

您应该收到类似以下内容的 JSON 响应：

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

更新实例

使用此示例更新现有实例。如需查看此调用的可用参数的完整列表，请参阅 instances.patch 页面。

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：包含实例的 Google Cloud 项目的 ID 或项目编号
  • INSTANCE_NAME：实例的名称

HTTP 方法和网址：

PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

请求 JSON 正文：

{
  "settings":
  {
    "enableDataplexIntegration": true
  }
}

如需发送您的请求，请展开以下选项之一：

您应该收到类似以下内容的 JSON 响应：

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2024-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_NAME",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

REST v1beta4

创建实例

使用此示例创建启用了集成的实例。如需查看此调用的可用参数的完整列表，请参阅 instances.insert 页面。

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：包含实例的 Google Cloud 项目的 ID 或项目编号
  • INSTANCE_NAME：实例的名称
  • REGION_NAME：实例的区域名称
  • DATABASE_VERSION：数据库版本的枚举字符串（例如 POSTGRES_13）。如需查看可用字符串的完整列表，请参阅 SqlDatabaseVersion。
  • PASSWORD：root 用户的密码
  • MACHINE_TYPE：机器（层级）类型的枚举字符串，例如：db-custom-[CPUS]-[MEMORY_MBS]
  • EDITION_TYPE：您的 Cloud SQL 版本

HTTP 方法和网址：

POST https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances

请求 JSON 正文：

{
  "name": "INSTANCE_NAME",
  "region": "REGION_NAME",
  "databaseVersion": "DATABASE_VERSION",
  "rootPassword": "PASSWORD",
  "settings": {
    "tier": "MACHINE_TYPE",
    "edition": "EDITION_TYPE",
    "enableDataplexIntegration": true
  }
}

如需发送您的请求，请展开以下选项之一：

您应该收到类似以下内容的 JSON 响应：

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

更新实例

使用此示例更新现有实例。如需查看此调用的可用参数的完整列表，请参阅 instances.patch 页面。

使用此示例更新现有实例。如需查看此调用的可用参数的完整列表，请参阅 instances.patch 页面。

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：包含实例的 Google Cloud 项目的 ID 或项目编号
  • INSTANCE_NAME：实例的名称

HTTP 方法和网址：

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME

请求 JSON 正文：

{
  "settings":
  {
    "enableDataplexIntegration": true
  }
}

如需发送您的请求，请展开以下选项之一：

您应该收到类似以下内容的 JSON 响应：

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2024-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_NAME",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

在 Cloud SQL 实例上验证 Dataplex Catalog 集成

如需验证实例上是否已启用 Dataplex Catalog 集成，请按照以下过程之一操作。

gcloud

如需验证现有实例上是否已启用 Dataplex Catalog 集成，请使用 gcloud sql instances describe 命令。

gcloud sql instances describe INSTANCE_NAME

将 INSTANCE_NAME 替换为实例名称。 在输出中，查找设为 true 的配置设置 enableDataplexIntegration。

REST v1

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：项目 ID
  • INSTANCE_ID<：实例 ID

HTTP 方法和网址：

GET https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID

如需发送您的请求，请展开以下选项之一：

您应该收到类似以下内容的 JSON 响应：

{
"settings":
  {
  "enableDataplexIntegration": true
  }
}

REST v1beta4

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：项目 ID
  • INSTANCE_ID<：实例 ID

HTTP 方法和网址：

GET https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID

如需发送您的请求，请展开以下选项之一：

您应该收到类似以下内容的 JSON 响应：

{
"settings":
  {
  "enableDataplexIntegration": true
  }
}

在 Cloud SQL 实例上停用 Dataplex Catalog 集成

如需在 Cloud SQL 实例上停用 Dataplex Catalog 集成，请按照以下过程之一操作。

gcloud

如需为现有实例停用集成，请使用 gcloud sql instances patch 命令。

gcloud sql instances patch INSTANCE_NAME \
  --no-enable-dataplex-integration

如果您需要停用集成并更新项目中的所有 Cloud SQL 实例，则可以运行如下所示的脚本：

gcloud sql instances list --format="(NAME)" \
| tail -n +2 | xargs -t -I %
gcloud sql instances patch % --no-enable-dataplex-integration

此示例基于 Linux。

REST v1

使用此示例停用集成。

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：包含实例的 Google Cloud 项目的 ID 或项目编号
  • INSTANCE_NAME：实例的名称

HTTP 方法和网址：

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME

请求 JSON 正文：

{
  "settings":
  {
    "enableDataplexIntegration": false
  }
}

如需发送您的请求，请展开以下选项之一：

您应该收到类似以下内容的 JSON 响应：

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2024-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_NAME",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

REST v1beta4

使用此示例停用集成。

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：包含实例的 Google Cloud 项目的 ID 或项目编号
  • INSTANCE_NAME：实例的名称

HTTP 方法和网址：

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME

请求 JSON 正文：

{
  "settings":
  {
    "enableDataplexIntegration": false
  }
}

如需发送您的请求，请展开以下选项之一：

您应该收到类似以下内容的 JSON 响应：

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2024-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_NAME",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

通过切面丰富 Cloud SQL 资产

切面类型是可重复使用的资源，可用作切面的模板。切面类型可帮助您避免重复性工作和不完整的切面。您可以使用 Dataplex Catalog 创建所需的切面类型。

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

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

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

搜索 Cloud SQL 资产

使用 Google Cloud 控制台中的 Dataplex Catalog 搜索页面搜索 Cloud SQL 资产。

  1. 前往 Dataplex Catalog 搜索页面。

    进入 Dataplex

  2. 在选择搜索平台中，选择 Dataplex Catalog。

  3. 在过滤条件面板中，点击系统，然后选择 Cloud SQL。

  4. 可选。在类型别名中，您可以通过选择以下一个或多个类型别名，将搜索结果过滤为特定类型的 Cloud SQL 资产：

    • 数据库
    • 服务
    • 表格
    • 视图

使用查询执行搜索

您还可以使用 Dataplex Catalog 中的搜索字段执行搜索查询。如需查看所有 Cloud SQL 资产，请输入 system=Cloud_SQL。

然后，您可以输入特定关键字。例如，如需查看所有 Cloud SQL 数据库，请输入以下查询：

system=Cloud_SQL AND type=Database

如需查看所有 Cloud SQL 表，请输入以下查询：

system=Cloud_SQL AND type=Table

您还可以使用复杂的括号和逻辑运算符 AND 和 OR 来表示复杂表达式。如需详细了解可在搜索字段中使用的表达式，请参阅 Dataplex Catalog 的搜索语法。

您可以直接在搜索字段中输入对特定 Cloud SQL 资产的搜索查询。查询字符串的格式如下所示：

type="projects/PROJECT_ID/locations/global/entryTypes/QUERY_STRING"

替换以下内容：

  • PROJECT_ID：您的项目的 ID

  • QUERY_STRING：使用下表根据 Cloud SQL 引擎和您要查询的资产类型标识查询字符串

    Cloud SQL 引擎 查询字符串
    Cloud SQL for MySQL
    • cloudsql-mysql-database
    • cloudsql-mysql-instance
    • cloudsql-mysql-table
    • cloudsql-mysql-view
    Cloud SQL for PostgreSQL
    • cloudsql-postgresql-database
    • cloudsql-postgresql-instance
    • cloudsql-postgresql-table
    • cloudsql-postgresql-schema
    • cloudsql-postgresql-view
    Cloud SQL for SQL Server
    • cloudsql-sqlserver-database
    • cloudsql-sqlserver-instance
    • cloudsql-sqlserver-table
    • cloudsql-sqlserver-schema
    • cloudsql-sqlserver-view

示例查询可能如下所示：

type="projects/1234567890/locations/global/entryTypes/cloudsql-postgresql-instance"

按 Cloud SQL 方言过滤 Cloud SQL 资产

默认情况下，Dataplex Catalog 会显示所有 Cloud SQL 资产。如需仅过滤 Cloud SQL for MySQL、Cloud SQL for PostgreSQL 或 SQL Server 的资产，请执行以下步骤。

  1. 在切面面板中，点击添加更多切面类型菜单。

  2. 选择 SQL Access。

  3. 点击确定。

  4. 点击 playlist_add 修改切面按钮。在 SQL 访问权限页面中，执行以下操作：

    • 在方言字段中，选择 MySQL 以过滤 Cloud SQL for MySQL 资产。
    • 可选。选择版本字段，然后输入 Cloud SQL for MySQL 的特定版本。

  5. 点击应用。Dataplex Catalog 仅显示 Cloud SQL for MySQL 资产。

Dataplex Catalog 包含一些内置切面类型，可用于执行搜索。

  1. 在切面面板中，点击添加更多切面类型菜单。

  2. 可选。选择 SQL 访问权限以按 Cloud SQL 方言过滤结果。如需了解详情，请参阅前面的过程：按 Cloud SQL 方言过滤 Cloud SQL 资产。

  3. 选择以下一个或多个切面类型，将搜索结果限制为该类型。

    • Cloud SQL 数据库
    • Cloud SQL 实例
    • Cloud SQL 视图
    • Cloud SQL 架构
    • Cloud SQL 表

  4. 点击确定。

  5. 在结果表中，点击资产的名称以查看该资产的元数据。

  6. 可选：优化或查看资产。您可以执行以下任一操作：

    • 在概览中，点击添加以添加资产的富文本说明。
    • 在切面中，点击添加以将某个切面附加到资产。
    • 对于实例，如需查看成员数据库，请点击条目列表标签页，然后点击在搜索结果中显示所有子条目。如果未显示条目列表标签页，则表示实例没有数据库。
    • 在条目详情中，查看资产的完整详情。点击条目名称可展开细目至其他条目。

示例工作流 - 从实例展开细目至列

在此示例工作流中，首先搜索 Cloud SQL 实例，查看成员数据库，查看该数据库中的表，然后查看表中的列。

  1. 前往 Dataplex Catalog 搜索页面。

    进入 Dataplex

  2. 对于选择搜索平台选项，选择 Dataplex Catalog。

  3. 在过滤条件面板中，选择系统，然后选择 Cloud SQL。或者，在搜索字段中输入 system=Cloud_SQL。

  4. 选择实例名称。

  5. 在 Cloud SQL 详情页面上，点击条目列表标签页，然后点击在搜索结果中显示所有子条目。Dataplex Catalog 会显示实例中的数据库。

  6. 在 Cloud SQL database details 页面上，点击条目列表标签页，然后点击查看搜索结果中的子条目。Dataplex Catalog 会显示数据库中的表。

  7. 选择表名称，然后在 Cloud SQL table details 页面上，点击架构以查看表列。

  8. 可选：如需向列添加切面类型，请点击添加切面按钮。

此工作流演示了如何从实例展开细目至表。您可以通过在搜索字段中输入 system=Cloud_SQL AND type=Table 直接前往表列表。

价格

在 Dataplex Catalog 中存储 Cloud SQL 技术元数据是免费的。标准 Dataplex 价格适用于 API 调用和其他业务元数据丰富化。如需了解详情，请参阅 Dataplex 价格页面。

资源使用情况

Dataplex Catalog 会定期从实例中提取数据。提取过程需要一定的 CPU 使用量。具有较小机器类型的实例（例如具有共享核心和较大架构 [10,000 个或更多表] 的机器）在提取过程中最多可以利用 40% 的 CPU。

限制

本部分列出了使用 Cloud SQL 和 Dataplex Catalog 的限制。

  • 对于因在 Assured Workloads 中注册资源而限制对资源的访问权限的任何实例，系统都会停用 Dataplex Catalog 与 Cloud SQL 的集成。

  • 在实例上启用 Dataplex Catalog 后，您的 Cloud SQL 资源可能需要 2 到 48 小时才能作为资产显示在 Dataplex Catalog 中，具体取决于机器大小、版本和类型 Cloud SQL 引擎。

  • 如果您删除 Cloud SQL for MySQL 数据库、表或视图，然后使用以前的名称重新创建该数据库、表或视图，则属于原始数据库、表或视图的所有现有 Dataplex Catalog 条目都会保留在 Dataplex Catalog 中。对 Cloud SQL for PostgreSQL 或 SQL Server 数据库执行相同的删除和重新创建操作时，这些条目会从 Dataplex Catalog 中移除，这是预期行为。
  • 当您对 Cloud SQL for MySQL 数据库执行 TRUNCATE 操作时，所有 Dataplex Catalog 条目都会从该数据库中移除。

后续步骤