将元数据导出到 BigQuery

注意：Document AI Warehouse 已弃用，2025 年 1 月 16 日之后将不再在 Google Cloud上提供。为确保数据安全，请将当前保存在 Document AI Warehouse 中的所有文档迁移到 Cloud Storage 等替代方案。 请在中止日期之前验证数据迁移是否已完成，以免丢失任何数据。如需了解详情，请参阅弃用。

预览版

此功能 受服务专用条款的约束。 非正式版功能“按原样”提供，且可能仅提供有限支持。 如需了解详情，请参阅发布阶段说明。

BigQuery 连接器简介

借助 BigQuery 连接器，您可以将存储在 Document AI Warehouse 中的文档元数据（包括属性）导出到 BigQuery 表中。将数据存储在 BigQuery 中后，您可以运行分析、创建报告和信息中心，从而做出业务决策。

如需启用 BigQuery 连接器，您需要设置一个已授予必要权限的 BigQuery 表，并通过 API 配置异步任务。BigQuery 连接器会将 Document AI Warehouse 中的数据导出到您的 BigQuery 表中。

前期准备

设置 Document AI Warehouse，并注入文档。如需了解详情，请参阅快速入门。

您必须确保托管 BigQuery 表的项目与 Document AI Warehouse 用于存储文档的项目相同。换句话说，数据必须始终从 Document AI Warehouse 导出到同一项目中的 BigQuery 表。

在项目中，您必须拥有 Owner (roles/owner) 角色，或者必须同时拥有 resourcemanager.projects.getIamPolicy 和 resourcemanager.projects.setIamPolicy

。

注意： 您目前无法使用此功能。填写 BigQuery 连接器和 DocAI 流水线计划表单即可获得访问权限。

设置 BigQuery 访问权限

绑定服务账号 [e-mail]

向 BigQuery Admin 角色添加：

gcloud projects add-iam-policy-binding <var>PROJECT_ID</var> --member serviceAccount:[e-mail] --role=roles/bigquery.admin

设置 BigQuery 数据集和表

设置 BigQuery 数据集和表，以便 Document AI Warehouse 导出数据。如果您没有 BigQuery 数据集，请按照创建数据集中的说明创建一个。

在 BigQuery 数据集中创建 BigQuery 表。按照 BigQuery 说明，使用 DDL 示例语句创建表：

CREATE TABLE `PROJECT_ID.DATASET_NAME.TABLE_NAME`
(
  project_number INT64,
  location STRING,
  mod_type STRING,
  document_id STRING,
  document_json JSON,
  create_time TIMESTAMP,
  creator STRING,
  update_time TIMESTAMP,
  updater STRING,
  document_state STRING,
  export_time TIMESTAMP
)
PARTITION BY TIMESTAMP_TRUNC(export_time, HOUR)
OPTIONS(
  partition_expiration_days=150,
  description="table partitioned by export_time on hour with expiry"
);

该 DDL 会为您创建一个新的 BigQuery 表。该表按小时进行时间分区，分区将在 150 天后删除。

注意： 每个分区表最多可以有 4,000 个分区。也就是说，对于每日同步的表，最多可以有 4,000 天（约 10.95 年）的数据；对于每小时同步的表，最多可以有 4,000 小时（约 166 天）的数据。如需详细了解分区表的限制，请参阅 BigQuery 限制。

注意 ：请勿将同一 BigQuery 数据库表重复用于不同的数据导出作业。这会导致重复记录导出到表格中。每个数据导出作业都应对应于自己的 BigQuery 表。

配置 BigQuery 连接器

创建数据导出配置

以下说明会创建一个新的数据导出作业，该作业会设置异步作业来导出数据。建议您为每个新的数据导出作业使用空表。如需了解配置详情，请参阅 API 参考文档。

您有以下跑步选项。可以使用 FREQUENCY 配置这些参数。 请参阅 API 参考文档。

• ADHOC：作业仅运行一次。所有数据都会导出到您的 BigQuery 表中。
• DAILY：作业每天运行一次。在首次运行中，所有数据都会导出到您的 BigQuery 表。初始导出完成后，系统只会将前一天的数据更改（或上次成功同步后的增量）导出到您的 BigQuery 表中。
• HO网址Y：作业每小时运行一次。在首次运行中，所有数据都会导出到您的 BigQuery 表。初始导出完成后，系统只会将前一小时的数据更改（或上次成功同步后的增量）导出到您的 BigQuery 表中。

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

• PROJECT_NUMBER：您的 Google Cloud 项目编号
• LOCATION：您的 Document AI Warehouse 位置（例如“us”）
• DATASET_LOCATION：您的数据集位置
• DATASET_NAME：数据集名称
• TABLE_NAME：您的表格名称
• FREQUENCY：ADHOC、DAILY 或 HOURLY 之一。

请求 JSON 正文：

{
  "projectNumber": PROJECT_NUMBER,
  "location": "DATASET_LOCATION",
  "dataset": "DATASET_NAME",
  "table": "TABLE_NAME",
  "frequency": "FREQUENCY",
  "state": "ACTIVE"
}

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

curl（Linux、macOS 或 Cloud Shell）

注意：请确保已将 GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为服务账号私钥文件的路径。

将请求正文保存在名为 request.json 的文件中。在终端中运行以下命令，在当前目录中创建或覆盖此文件：

cat > request.json << 'EOF'
{
  "projectNumber": PROJECT_NUMBER,
  "location": "DATASET_LOCATION",
  "dataset": "DATASET_NAME",
  "table": "TABLE_NAME",
  "frequency": "FREQUENCY",
  "state": "ACTIVE"
}
EOF

然后，执行以下命令以发送 REST 请求：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/dataExportJobs"

PowerShell (Windows)

注意：请确保已将 GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为服务账号私钥文件的路径。

将请求正文保存在名为 request.json 的文件中。在终端中运行以下命令，在当前目录中创建或覆盖此文件：

@'
{
  "projectNumber": PROJECT_NUMBER,
  "location": "DATASET_LOCATION",
  "dataset": "DATASET_NAME",
  "table": "TABLE_NAME",
  "frequency": "FREQUENCY",
  "state": "ACTIVE"
}
'@  | Out-File -FilePath request.json -Encoding utf8

然后，执行以下命令以发送 REST 请求：

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

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/dataExportJobs" | Select-Object -Expand Content

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

响应

{
  "projectNumber": "1234567890",
  "location": "us",
  "dataset": "datasetX",
  "table": "tableA",
  "frequency": "DAILY",
  "id": "fd3f3576-c42c-4f7e-8a1a-ae69189da6e4",
  "createTime": "2023-03-21T17:57:01.556230Z",
  "updateTime": "2023-03-21T17:57:01.556230Z"
}

重要提示：请记录作业 ID（即 id 字段），删除作业时需要用到该 ID。

注意：目前，Document AI Warehouse 不支持修改现有作业。如果您想修改现有作业，需要先将其删除，然后再创建新作业。

作业执行

成功创建作业后，作业会根据您的配置运行。请注意，作业是异步运行的，因为执行需要时间。首次运行可能需要一些时间才能完成，具体取决于要导出的数据量。对于每日作业，结果需要 24 小时才能显示在 BigQuery 表中。

删除数据导出配置

以下命令会删除（通过归档）您创建的作业。

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

• PROJECT_NUMBER：您的 Google Cloud 项目编号
• LOCATION：您的 Document AI Warehouse 位置（例如“us”）
• JOB_ID：您创建作业时收到的响应中的作业 ID

请求 JSON 正文：

{}

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

curl（Linux、macOS 或 Cloud Shell）

注意：请确保已将 GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为服务账号私钥文件的路径。

将请求正文保存在名为 request.json 的文件中。在终端中运行以下命令，在当前目录中创建或覆盖此文件：

cat > request.json << 'EOF'
{}
EOF

然后，执行以下命令以发送 REST 请求：

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/dataExportJobs/JOB_ID"

PowerShell (Windows)

注意：请确保已将 GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为服务账号私钥文件的路径。

将请求正文保存在名为 request.json 的文件中。在终端中运行以下命令，在当前目录中创建或覆盖此文件：

@'
{}
'@  | Out-File -FilePath request.json -Encoding utf8

然后，执行以下命令以发送 REST 请求：

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

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/dataExportJobs/JOB_ID" | Select-Object -Expand Content

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

响应

{
  "projectNumber": "216122811947",
  "location": "us",
  "dataset": "datasetX",
  "table": "tableA",
  "frequency": "DAILY",
  "state": "ARCHIVED",
  "id": "fd3f3576-c42c-4f7e-8a1a-ae69189da6e4",
  "createTime": "2023-03-21T17:57:01.556230Z",
  "updateTime": "2023-03-21T20:59:44.820355Z"
}

之后，您的导出作业会被删除（归档），Document AI Warehouse 不再运行该作业。

探索注入到 BigQuery 中的数据

如需将文档元数据和属性提取到 BigQuery 中的不同表字段中以满足分析需求，您可以使用以下示例 DDL 查询。提取的这些字段还可用于 Looker Studio 或任何 BI 信息中心工具，以直观呈现数据中的关系。

从 document_json 中提取关键字段

此查询从数据导出中选择相关字段，包括文档元数据（存储在 document_json 字段中）中的关键字段。

DROP VIEW IF EXISTS
 `DATASET_NAME.VIEW_NAME_1`;
CREATE VIEW
 `DATASET_NAME.VIEW_NAME_1` AS
SELECT
 project_number,
 document_id,
 mod_type,
 create_time,
 update_time,
 location,
 creator,
 updater,
 document_state,
 SPLIT(JSON_EXTRACT_SCALAR(document_json,'$.documentSchemaName' ), '/')[SAFE_OFFSET(ARRAY_LENGTH(SPLIT(JSON_EXTRACT_SCALAR(document_json,'$.documentSchemaName' ), '/')) - 1)] AS document_schema_name,
 JSON_EXTRACT_SCALAR(document_json,'$.name') AS document_name,
 JSON_EXTRACT_SCALAR(document_json,'$.rawDocumentFileType')
AS raw_document_file_type,
 JSON_EXTRACT(document_json,'$.properties') AS properties
FROM
 `DATASET_NAME.SYSTEM_METADATA_AND_DOC_PROPERTIES_TABLE_EXPORT_NAME`;

从 document_json 中取消嵌套属性

此查询会从文档元数据 (document_json) 中取消嵌套属性，以创建键值对（属性名称、值）。这些键值对将在下一个查询中转换为各个表字段，以便进行房源级数据探索和信息中心可视化。

DROP VIEW IF EXISTS
 `DATASET_NAME.VIEW_NAME_2`;
CREATE VIEW
 `DATASET_NAME.VIEW_NAME_2` AS
SELECT

    *   EXCEPT(key_value_pair,
   properties,raw_document_file_type)
FROM (
SELECT
 *,
 REPLACE(JSON_VALUE(key_value_pair,'$.name'),'/','-') property_name,
 -- Note: values are either text OR float values
 CASE
   WHEN JSON_VALUE(key_value_pair,'$.textValues.values[0]') IS NULL THEN JSON_VALUE(key_value_pair,'$.floatValues.values[0]')
 ELSE
 JSON_VALUE(key_value_pair,'$.textValues.values[0]')
END
 AS value,
 CASE
   WHEN raw_document_file_type IS NULL THEN "RAW_DOCUMENT_FILE_TYPE_UNSPECIFIED"
 ELSE
 raw_document_file_type
END
 AS document_file_type
FROM
 `DATASET_NAME.VIEW_NAME_1`,
 UNNEST(JSON_EXTRACT_ARRAY(properties)) AS key_value_pair);

透视 document_json 中的属性，以在 BigQuery 中创建表字段

以下过程会创建一个表，其中包含通过透视属性和关联值转换而来的所有文档属性（作为单独的表字段）。您可以利用此表的结果，通过 Looker Studio 和其他 BI 可视化工具中的后续查询来获得更深入的数据洞见。

DECLARE
 property_field STRING;
-- Extracting distinct property_names from the previous view and storing it in property_field, declared above

EXECUTE IMMEDIATE
 """SELECT string_agg(CONCAT("'",property_name,"'")) from (select distinct property_name from DATASET.VIEW_NAME_2)""" INTO property_field;

DROP TABLE IF EXISTS `DATASET_NAME.ANALYTICS_TABLE_NAME`;
-- Creating pivot table with the aid of extracted distinct property_names
-- Casting numerical values to float/int
-- Pivot on property_name and value (ie. create a new column for each of the property_name, substitute the value)

EXECUTE IMMEDIATE
 FORMAT ("""
CREATE TABLE `DATASET_NAME.ANALYTICS_TABLE_NAME` AS
SELECT * FROM `DATASET_NAME.VIEW_NAME_2`
PIVOT(min(value) FOR property_name IN (%s))""", property_field);

数据清理和转换程序（具体到业务用例）

根据提取到 BigQuery 中的数据，您可能需要执行额外的数据清理和转换程序，才能进行进一步分析。此类程序因具体情况（数据集）而异，应根据具体情况执行。

数据清理程序的一些示例可能包括（但不限于）：

• 统一日期格式。
• 正在整合房产价值。
• 例如，将数据类型转换为字符串、浮点数和整数。

在 Looker Studio 中直观呈现数据

在 BigQuery 中提取、清理和转换数据后，您可以将最终数据集导出到 Looker Studio 以进行直观的分析。

Looker 信息中心

下面列出的示例信息中心展示了可根据您的数据集创建的可视化图表。在此场景中，从 Document AI Warehouse 导出的示例数据包含 W2 和发票（两种架构）。

面向公众的 Looker 信息中心

视图示例：Document AI Warehouse 分析概览

以下信息中心可让您大致了解已提取到 Document AI Warehouse 实例中的各种文档。

您可以查看文档级详细信息，包括：

• 文档总数。
• 文档架构的总数。
• 按文档架构统计的记录数。
• 文档文件类型（例如 PDF、文本、未指定类型）。

您还可以使用从文档元数据 (document_json) 中提取的属性，为提取到 BigQuery 中的发票和 W2 表单构建关键细分。

视图示例：特定于企业的分析洞见信息中心（账单）

以下信息中心可让用户详细了解单个文档架构（发票），以便深入分析已提取到 Document AI Warehouse 中的所有发票。

您可以在账单上查看方案专属的详细信息，例如：

• 按账单金额排名的顶级供应商。
• 按地理位置细分的供应商。
• 账单日期及其对应的截止日期。
• 按金额和记录数显示的账单环比趋势。

将数据源连接到信息中心

如需使用这些信息中心示例作为直观呈现数据集的起点，您可以连接来自 BigQuery 的数据源。

注意： 提供的示例信息中心特定于所用示例数据集中的可用属性，包括账单和 W2。如果您选择制作副本并关联数据集，则示例信息中心 widget 中引用的属性会更新，以反映您提取的属性，供您在业务场景中使用。

在将示例信息中心连接到 BigQuery 数据源之前，请确保您已登录与 Google Cloud环境相关联的账号。

选择突出显示的按钮以显示下拉选项。

选择制作副本。

在“新数据源”子部分下，选择创建数据源。

选择 BigQuery。

选择存储数据集的项目，然后按照提示选择数据集和表。点击连接。

点击添加到报告。

点击复制报告。

如果您选择修改和更新信息中心内的微件，则可以进行修改，因为您拥有包含提取的属性的信息中心副本。