导出元数据

您可以运行元数据导出作业，将元数据从 Dataplex Universal Catalog 中导出，以便在外部系统中使用。

在以下情况下，您可能需要导出元数据：

使用 BigQuery 或其他数据分析工具查询和分析元数据
以程序化方式处理大量元数据，之后您可以将这些元数据重新导入 Dataplex Universal Catalog 中
将元数据集成到自定义应用或第三方工具中

元数据导出作业会导出 Dataplex Universal Catalog 元数据的快照。Dataplex Universal Catalog 元数据由条目及其切面组成。本页面上的步骤假设您熟悉 Dataplex Universal Catalog 元数据概念，包括条目组、条目类型和切面类型。

作业范围

作业范围用于定义要导出的元数据。您必须为每个元数据导出作业提供以下作业范围之一：

组织：导出属于您的组织的元数据。
项目：导出属于指定项目的元数据。
条目组：导出属于指定条目组的元数据。

您可以通过指定要包含在作业中的条目类型或切面类型来进一步限制范围。作业仅会导出属于这些条目类型和切面类型的条目和切面。

VPC Service Controls

Dataplex Universal Catalog 使用 VPC Service Controls 为元数据导出作业提供额外的安全保护。作业所属的项目决定了 VPC Service Controls 边界，如下所示：

如果您将作业范围设置为组织级层，则会发生以下情况：
- 导出范围是作业所属的组织。
- 系统只会导出位于 VPC Service Controls 边界内的条目。
- 系统会排除作业所属组织内但位于 VPC Service Controls 边界外的所有项目。
如果您将作业范围设置为项目或条目组，则项目或条目组必须与作业位于同一 VPC Service Controls 边界中。如果任何项目或条目组违反了 VPC Service Controls 规则，则作业会失败。

准备工作

在导出元数据之前，请先完成本部分中的任务。

最终用户所需的角色

如需获得管理元数据导出作业所需的权限，请让您的管理员为您授予以下 IAM 角色：

创建元数据导出作业：
- 针对要导出的组织、项目或条目组的 Dataplex Entry Group Exporter (roles/dataplex.entryGroupExporter)
- 针对您在其中运行元数据作业的项目的 Dataplex Metadata Job Owner (roles/dataplex.metadataJobOwner)
访问导出的结果：针对项目或存储桶的 Storage Object Viewer (roles/storage.objectViewer)
查看元数据作业：针对项目的 Dataplex Metadata Job Viewer (roles/dataplex.metadataJobViewer)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

这些预定义角色可提供管理元数据导出作业所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

管理元数据导出作业需要以下权限：

导出元数据：
- dataplex.metadataJobs.create
- dataplex.entryGroups.export
- dataplex.entryGroups.get
- resourcemanager.projects.get
- resourcemanager.projects.list
访问导出的结果： storage.objects.get

您也可以使用自定义角色或其他预定义角色来获取这些权限。

Dataplex Universal Catalog 服务账号所需的角色

如需确保 Dataplex Universal Catalog 服务账号拥有访问 Cloud Storage 存储桶所需的权限，请让您的管理员为 Dataplex Universal Catalog 服务账号授予该存储桶的以下权限：storage.buckets.get、storage.objects.get 和 storage.objects.create。

配置 Google Cloud 资源

安装 Google Cloud CLI。安装完成后，运行以下命令来初始化 Google Cloud CLI：
```
gcloud init
```
如果您使用的是外部身份提供方 (IdP)，则必须先使用联合身份登录 gcloud CLI。
创建一个 Cloud Storage 存储桶以存储导出的结果。

该存储桶必须与元数据作业位于同一位置和同一 VPC Service Controls 边界内。

运行元数据导出作业

以下部分展示了如何导出具有不同作业范围的元数据。

从组织中导出元数据

如需从组织中导出元数据，请使用 metadataJobs.create 方法并将 organizationLevel 布尔值设置为 true。

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

JOB_PROJECT：您在其中运行元数据作业的 Google Cloud项目。提供项目编号或项目 ID。
LOCATION_ID： Google Cloud 位置，例如 us-central1。
METADATA_JOB_ID：可选。元数据作业 ID。
BUCKET：要将元数据导出到的 Cloud Storage 存储桶。

（可选）您可以在存储桶名称后面添加自定义前缀，格式为 gs://BUCKET/PREFIX/。自定义前缀的长度上限为 128 个字符。

HTTP 方法和网址：

POST https://dataplex.googleapis.com/v1/projects/JOB_PROJECT/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID

请求 JSON 正文：

{
  "type": EXPORT,
  "export_spec": {
    "output_path": "gs://BUCKET/",
    "scope": {
      "organizationLevel": true,
    },
  }
}

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

curl（Linux、macOS 或 Cloud Shell）

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

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

PowerShell (Windows)

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$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://dataplex.googleapis.com/v1/projects/JOB_PROJECT/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID" | Select-Object -Expand Content

该响应用于标识长时间运行的操作。导出的元数据会保存到 Cloud Storage 存储桶。

从特定项目中导出元数据

如需从一个或多个项目中导出元数据，请使用 metadataJobs.create 方法并提供项目列表。

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

JOB_PROJECT：您在其中运行元数据作业的 Google Cloud项目。提供项目编号或项目 ID。
LOCATION_ID： Google Cloud 位置，例如 us-central1。
METADATA_JOB_ID：可选。元数据作业 ID。
BUCKET：要将元数据导出到的 Cloud Storage 存储桶。

（可选）您可以在存储桶名称后面添加自定义前缀，格式为 gs://BUCKET/PREFIX/。自定义前缀的长度上限为 128 个字符。
METADATA_SOURCE_PROJECT：您要导出其元数据的项目。提供项目编号或项目 ID。该项目必须与元数据作业位于同一组织和 VPC Service Controls 边界中。

HTTP 方法和网址：

POST https://dataplex.googleapis.com/v1/projects/JOB_PROJECT/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID

请求 JSON 正文：

{
  "type": EXPORT,
  "export_spec": {
    "output_path": "gs://BUCKET/",
    "scope": {
      "projects": [
        "projects/METADATA_SOURCE_PROJECT",
        # Additional projects
      ],
    },
  }
}

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

curl（Linux、macOS 或 Cloud Shell）

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

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

PowerShell (Windows)

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$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://dataplex.googleapis.com/v1/projects/JOB_PROJECT/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID" | Select-Object -Expand Content

该响应用于标识长时间运行的操作。导出的元数据会保存到 Cloud Storage 存储桶。

从特定条目组中导出元数据

如需从特定条目组中导出元数据，请使用 metadataJobs.create 方法并提供条目组列表。

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

JOB_PROJECT：您在其中运行元数据作业的 Google Cloud项目。提供项目编号或项目 ID。
LOCATION_ID： Google Cloud 位置，例如 us-central1。
METADATA_JOB_ID：可选。元数据作业 ID。
BUCKET：要将元数据导出到的 Cloud Storage 存储桶。

（可选）您可以在存储桶名称后面添加自定义前缀，格式为 gs://BUCKET/PREFIX/。自定义前缀的长度上限为 128 个字符。
ENTRY_GROUP：作业范围内的条目组的相对资源名称，格式为 projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryGroups/ENTRY_GROUP_ID。条目组必须与元数据作业位于同一项目中。

HTTP 方法和网址：

POST https://dataplex.googleapis.com/v1/projects/JOB_PROJECT/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID

请求 JSON 正文：

{
  "type": EXPORT,
  "export_spec": {
    "output_path": "gs://BUCKET/",
    "scope": {
      "entryGroups": [
        "ENTRY_GROUP",
        # Additional entry groups
      ],
    },
  }
}

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

curl（Linux、macOS 或 Cloud Shell）

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

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

PowerShell (Windows)

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$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://dataplex.googleapis.com/v1/projects/JOB_PROJECT/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID" | Select-Object -Expand Content

该响应用于标识长时间运行的操作。导出的元数据会保存到 Cloud Storage 存储桶。

从特定条目类型或切面类型导出元数据

如需从特定条目类型或切面类型导出元数据，请设置主要作业范围（例如在组织级），如以下示例所示。然后，提供条目类型和/或切面类型的列表。

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

ENTRY_TYPE：可选。作业范围内的条目类型的相对资源名称，格式为 projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryTypes/ENTRY_TYPE_ID。
ASPECT_TYPE：可选。作业范围内的切面类型的相对资源名称，格式为 projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/aspectTypes/ASPECT_TYPE_ID。

HTTP 方法和网址：

POST https://dataplex.googleapis.com/v1/projects/JOB_PROJECT/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID

请求 JSON 正文：

{
  "type": EXPORT,
  "export_spec": {
    "output_path": "gs://BUCKET/",
    "scope": {
      "organizationLevel": true,
      "entry_types": [
        "ENTRY_TYPE",
        # Additional entry types
      ],
      "aspect_types": [
        "ASPECT_TYPE",
        # Additional aspect types
      ]
    },
  }
}

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

curl（Linux、macOS 或 Cloud Shell）

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

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

PowerShell (Windows)

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$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://dataplex.googleapis.com/v1/projects/JOB_PROJECT/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID" | Select-Object -Expand Content

该响应用于标识长时间运行的操作。导出的元数据会保存到 Cloud Storage 存储桶。

获取有关元数据作业的详细信息

如需获取有关元数据作业的信息，例如作业的状态和已导出的条目数，请使用 metadataJobs.get 方法。

元数据导出结果

元数据导出作业会导出创建元数据作业时 Dataplex Universal Catalog 元数据的快照。

导出文件内容

输出文件的内容遵循与用于元数据导入作业的元数据导入文件相同的格式。您可以直接将输出文件用作元数据导入作业的输入。

导出文件位置

Dataplex Universal Catalog 会将导出结果文件以对象的形式保存到 Cloud Storage 存储桶。

每个输出文件的对象路径使用您在导出作业中指定的存储桶名称和自定义前缀进行构建，后跟系统生成的路径。系统生成的路径专为与 BigQuery 集成而设计。对象路径采用以下格式：

gs://BUCKET/PREFIX/year=YYYY/month=MM/day=DD/consumer_project=JOB_PROJECT/job=METADATA_JOB_ID/project=METADATA_SOURCE_PROJECT/entry_group=ENTRY_GROUP/FILE_NUMBER.jsonl

请注意以下几点：

系统生成的路径以导出作业创建日期的标准 Hive 分区格式开头。BigQuery 支持此格式。如需了解详情，请参阅加载外部分区数据。
consumer_project 参数是您在其中运行元数据导出作业的项目。project 参数是包含您要导出的元数据的项目。
如果之前的作业已被删除，您可以重复使用元数据作业 ID。但是，删除作业不会删除该作业导出的文件。这意味着，如果您重复使用已删除的作业 ID，则可能会在输出文件路径中看到重复的作业 ID。
每个输出文件都以文件编号命名，该编号是从 1 开始的整数。

如果元数据导出作业包含大量条目，则该作业会将结果拆分为多个文件，以限制每个输出文件的大小。每个输出文件中的条目数上限为 1,000,000。

输出文件示例

以下是包含多个项目的元数据导出作业的输出文件示例：

gs://export-bucket/example-folder/year=2025/month=04/day=13/consumer_project=admin-project/job=example-job/project=metadata-project-1/entrygroup=entry-group-1/1.jsonl
gs://export-bucket/example-folder/year=2025/month=04/day=13/consumer_project=admin-project/job=example-job/project=metadata-project-2/entrygroup=entry-group-1/1.jsonl
gs://export-bucket/example-folder/year=2025/month=04/day=13/consumer_project=admin-project/job=example-job/project=metadata-project-3/entrygroup=entry-group-2/1.jsonl

以下是包含大型条目组的元数据导出作业的输出文件示例。该条目组的结果会拆分为多个文件。

gs://export-bucket/example-folder/year=2025/month=04/day=13/consumer_project=admin-project/job=another-example-job/project=example-metadata-project/entrygroup=big-entry-group/1.jsonl
gs://export-bucket/example-folder/year=2025/month=04/day=13/consumer_project=admin-project/job=another-example-job/project=example-metadata-project/entrygroup=big-entry-group/2.jsonl

在 BigQuery 中分析导出的元数据

如果您要在 BigQuery 中分析导出的元数据，可以为导出的元数据创建外部表。创建外部表后，您无需额外加载或转换数据，即可查询导出的数据。例如，您可以按条目组统计条目数、查找具有特定切面的条目，或在 BigQuery 中执行其他分析。

执行以下操作：

为 Hive 分区数据创建外部表。提供以下信息：

从 Cloud Storage 存储桶中选择文件：提供包含导出的元数据文件的 Cloud Storage 文件夹的路径。如需包含存储桶中的所有文件，请使用星号 (*) 通配符。例如 gs://export-bucket/example-folder/*。
文件格式：选择 JSONL（以换行符分隔的 JSON）。
选中源数据分区复选框，然后在选择源 URI 前缀部分，为 BigQuery 表提供 Cloud Storage URI 前缀以定义分区。例如 gs://export-bucket/example-folder/。
分区推断模式：选择自动推断类型选项。
表类型：选择外部表选项。

架构：点击以文本形式修改切换开关，然后输入以下导出文件架构定义：

[
  {
    "name": "entry",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "mode": "NULLABLE",
        "name": "name",
        "type": "STRING"
      },
      {
        "mode": "NULLABLE",
        "name": "entryType",
        "type": "STRING"
      },
      {
        "mode": "NULLABLE",
        "name": "createTime",
        "type": "STRING"
      },
      {
        "mode": "NULLABLE",
        "name": "updateTime",
        "type": "STRING"
      },
      {
        "mode": "NULLABLE",
        "name": "aspects",
        "type": "JSON"
      },
      {
        "mode": "NULLABLE",
        "name": "parentEntry",
        "type": "STRING"
      },
      {
        "mode": "NULLABLE",
        "name": "fullyQualifiedName",
        "type": "STRING"
      },
      {
        "mode": "NULLABLE",
        "name": "entrySource",
        "type": "RECORD",
        "fields": [
          {
            "mode": "NULLABLE",
            "name": "resource",
            "type": "STRING"
          },
          {
            "mode": "NULLABLE",
            "name": "system",
            "type": "STRING"
          },
          {
            "mode": "NULLABLE",
            "name": "platform",
            "type": "STRING"
          },
          {
            "mode": "NULLABLE",
            "name": "displayName",
            "type": "STRING"
          },
          {
            "mode": "NULLABLE",
            "name": "description",
            "type": "STRING"
          },
          {
            "mode": "NULLABLE",
            "name": "labels",
            "type": "JSON"
          },
          {
            "mode": "REPEATED",
            "name": "ancestors",
            "type": "RECORD",
            "fields": [
              {
                "mode": "NULLABLE",
                "name": "name",
                "type": "STRING"
              },
              {
                "mode": "NULLABLE",
                "name": "type",
                "type": "STRING"
              }
            ]
          },
          {
            "mode": "NULLABLE",
            "name": "createTime",
            "type": "STRING"
          },
          {
            "mode": "NULLABLE",
            "name": "updateTime",
            "type": "STRING"
          },
          {
            "mode": "NULLABLE",
            "name": "location",
            "type": "STRING"
          }
        ]
      }
    ]
  }
]

BigQuery 会创建一个包含导出的元数据的外部表。该表的架构包含一个 entry 架构列，其中每行代表一个条目。如需详细了解条目的字段，请参阅 ImportItem。该表的架构还包含导出文件分区，如本文档的导出文件位置部分中所述。

创建外部表后，您可以使用 GoogleSQL 语法查询该表。例如，如需查询导出了哪些条目类型，请使用以下语句：

SELECT entry.entryType FROM `example-project.example-dataset.example-table` LIMIT 1000

后续步骤

了解如何使用 GoogleSQL 语法查询 BigQuery 表。
使用托管式连接流水线将元数据导入 Dataplex Universal Catalog。

导出元数据 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

作业范围

VPC Service Controls

准备工作

最终用户所需的角色

所需权限

Dataplex Universal Catalog 服务账号所需的角色

配置 Google Cloud 资源

运行元数据导出作业

从组织中导出元数据

curl（Linux、macOS 或 Cloud Shell）

PowerShell (Windows)

从特定项目中导出元数据

curl（Linux、macOS 或 Cloud Shell）

PowerShell (Windows)

从特定条目组中导出元数据

curl（Linux、macOS 或 Cloud Shell）

PowerShell (Windows)

从特定条目类型或切面类型导出元数据

curl（Linux、macOS 或 Cloud Shell）

PowerShell (Windows)

获取有关元数据作业的详细信息

元数据导出结果

导出文件内容

导出文件位置

输出文件示例

在 BigQuery 中分析导出的元数据

后续步骤

导出元数据