使用查询模板

BigQuery 数据净室查询模板可缩短获取数据洞见的时间，并提供额外的安全和控制层，以最大限度地减少数据渗漏问题。通过预先定义和限制可在数据净室中执行的查询，您可以执行以下操作：

  • 帮助防止敏感数据泄露。当在净室中运行查询的订阅者可以更灵活地探索数据时，数据所有者会认为敏感信息意外或有意暴露的风险更高。

  • 为不太懂技术的用户简化新手入门和采用流程。许多数据提供商认为，数据净室的订阅者在技术方面不太熟练，尤其是在编写以隐私保护为中心的 SQL 查询和了解如何合理分配隐私预算方面。

  • 保证数据订阅者获得一致的分析结果。如果无法控制在数据净室中执行的查询，那么就更难强制执行特定的数据分析规则并验证隐私权法规的合规性。

借助查询模板，数据所有者和贡献者可以创建预定义且经过批准的查询，这些查询专门针对数据净室的使用情形量身定制，并且可以发布这些查询以供订阅者使用。 预定义查询使用 BigQuery 中的表值函数 (TVF)，以允许将整个表或特定字段作为输入参数传递，并返回一个表作为输出。

限制

  • 查询模板最多仅支持两个数据引用，即用于定义 TVF 的查询的数据和 TVF 接受的数据参数输入。
    • TVF 的查询定义中可以引用多个表或视图，但它们必须都属于同一数据所有者或方。
  • 查询模板 TVF 仅支持 TABLE 和 VIEW 固定类型。
  • 查询模板定义受与 TVF 相同的限制约束。

准备工作

按照以下步骤为您的 Google Cloud 项目启用 Analytics Hub API：

控制台

  1. 前往 Analytics Hub API 页面。

    前往 Analytics Hub API

  2. 在 Google Cloud 控制台工具栏中，选择您的项目。

  3. 如果该 API 尚未启用，请点击启用。

bq

运行 gcloud services enable 命令：

gcloud services enable analyticshub.googleapis.com

所需的角色

如需获得执行本文档中的任务所需的权限，请让您的管理员为您授予以下 IAM 角色：

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

这些预定义角色可提供执行本文档中的任务所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

如需执行本文档中的任务，您需要拥有以下权限：

  • 在数据净室中创建或删除 TVF：
    • 针对项目的 bigquery.routines.create 权限
    • 针对项目的 bigquery.routines.update 权限
    • 针对项目的 bigquery.routines.delete 权限
  • 授权 TVF： 对例程访问的数据集具有 bigquery.datasets.update
  • 创建查询模板：
    • 针对项目的 analyticshub.listings.subscribe 权限
    • 针对项目的 analyticshub.queryTemplates.create 权限
  • 批准查询模板：
    • 针对项目的 bigquery.routines.create 权限
    • 例程所访问的数据集的 bigquery.datasets.update 权限
    • 针对项目的 analyticshub.listings.create 权限
    • 针对项目的 analyticshub.queryTemplates.approve 权限

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

将现有 TVF 添加到数据净室

您可以使用 Analytics Hub API 将现有 TVF 添加到数据净室。

使用 projects.locations.dataExchanges.listings.create 方法。

以下示例展示了如何使用 curl 命令调用 projects.locations.dataExchanges.listings.create 方法：

    curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -H 'x-goog-user-project:DCR_PROJECT_ID' -X POST https://analyticshub.googleapis.com/v1/projects/DCR_PROJECT_ID/locations/LOCATION/dataExchanges/CLEAN_ROOM_ID/listings?listingId=LISTING_ID -d
    '{"bigqueryDataset":{"dataset":"projects/PROJECT_ID/datasets/DATASET_ID","selectedResources":[{"routine":"projects/PROJECT_ID/datasets/DATASET_ID/tables/ROUTINE_ID"}],},"displayName":LISTING_NAME"}'

替换以下内容：

  • DCR_PROJECT_ID：在其中创建数据净室的项目的 ID。
  • PROJECT_ID：源数据集所在项目的 ID。
  • DATASET_ID：源数据集 ID。
  • LOCATION：数据净室的位置。
  • CLEAN_ROOM_ID：数据净室 ID。
  • LISTING_ID：清单 ID。
  • LISTING_NAME：商品详情名称。
  • ROUTINE_ID：例程 ID。

查询模板角色

使用数据净室查询模板需要具备三个主要角色。每个角色都有特定的工作流，本文档后面会对此进行介绍。

模板创建者工作流

作为查询模板创建者，您可以执行以下操作：

向数据净室添加清单

在创建查询模板之前，您必须先将数据添加到数据净室。如需在数据净室中创建清单，请按以下步骤操作：

  1. 前往 Sharing (Analytics Hub) 页面。

    前往 Sharing (Analytics Hub)

  2. 点击您要在其中创建查询模板的数据净室的显示名称。

  3. 点击添加数据，然后按照相应步骤创建配置了分析规则的视图。如需查看详细说明，请参阅创建房源信息（添加数据）。

    1. 如需添加来自其他方的数据，请与另一位可信贡献者共享净室。 此数据贡献者还必须向净室添加数据，才能在查询模板中使用。

  4. 为清单设置数据出站流量控制。

  5. 为商品详情设置元数据控制。如果您只想分享上一步中添加的数据的架构和说明（而不是共享数据本身），请选择禁止访问关联数据集中的商品详情。

  6. 查看商品详情。

  7. 点击添加数据。 为您的数据创建的视图的元数据现已添加到净室。

创建查询模板

从下列选项中选择一项：

控制台

  1. 前往 Sharing (Analytics Hub) 页面。

    前往 Sharing (Analytics Hub)

  2. 点击您要在其中创建查询模板的数据净室的显示名称。

  3. 在净室中，前往模板标签页。

  4. 点击创建模板。

  5. 输入模板名称和说明。

  6. 点击下一步。

  7. 您可以查看添加到净室的视图的架构，并提出查询定义。

    1. 请务必使用受支持的 CREATE TABLE FUNCTION 语法定义查询。

    2. 传递具有固定定义的整个表或视图。您必须定义完整的数据表路径引用，包括项目 ID 和数据集 ID（来自添加到净室的数据）。例如：

      query_template1(t1 TABLE<year INT64>) AS (SELECT * FROM `project_id.dataset_id.table_id` WHERE year = table_id.year)

    3. 如果您已将隐私分析规则应用于数据，请确保此 TVF 包含特定于隐私的 SQL 语法，例如 SELECT WITH AGGREGATION_THRESHOLD。

  8. 查看模板详情。

  9. 如需保存模板但不提交审核，请点击保存。 查询模板现在处于草稿状态。

您可以更新查询模板，也可以提交查询模板以供审核。

API

以下示例展示了如何使用 CURL 命令创建查询模板：

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -H 'x-goog-user-project:DCR_PROJECT_ID' -X POST https://analyticshub.googleapis.com/v1/projects/DCR_PROJECT_ID/locations/LOCATION/dataExchanges/CLEAN_ROOM_ID/queryTemplates?queryTemplateId=QUERY_TEMPLATE_ID -d
  'query_template {
  name: "query_template1",
  display_name: "query_template1",
  routine {
    definition_body: "QUERY_TEMPLATE_ID(TVF arguments) AS (TVF_DEFINITION)"
  }
}'

替换以下内容：

  • DCR_PROJECT_ID：在其中创建数据净室的项目的 ID。
  • LOCATION：数据净室的位置。
  • CLEAN_ROOM_ID：数据净室 ID。
  • QUERY_TEMPLATE_ID：查询模板 ID。
  • TVF_DEFINITION：TVF 定义。

以下代码示例展示了 API 调用的 definition_body 示例。 您必须从添加到净室的数据中定义完整的表路径引用，包括项目 ID 和数据集 ID。

  query_template1(t1 TABLE<year INT64>) AS (SELECT * FROM `project_id.dataset_id.table_id` WHERE year = table_id.year)

definition_body 类似于例程的定义。上述 definition_body 会转换为以下例程：

  CREATE OR REPLACE TABLE FUNCTION <approvers_dataset>.query_template1(t1 TABLE, y INT64)
  AS (SELECT * FROM t1 WHERE year > y)

您可以更新查询模板，也可以提交查询模板以供审核。

更新查询模板

只有当查询模板处于草稿状态时，您才能更新该模板。如果查询模板已提交审核，您将无法再对其进行修改。

如需更新查询模板，请选择以下选项之一：

控制台

  1. 前往 Sharing (Analytics Hub) 页面。

    前往 Sharing (Analytics Hub)

  2. 点击包含查询模板的数据净室的显示名称。

  3. 在净室中，前往模板标签页。

  4. 在要更新的模板所在的行中，依次点击操作 > 修改模板。

  5. 根据需要更新模板详细信息和查询定义。

  6. 点击下一步。

  7. 查看查询模板，然后点击保存以保存更改，而无需提交模板以供审核。

API

以下示例展示了如何使用 CURL 命令更新查询模板：

  curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -H 'x-goog-user-project:DCR_PROJECT_ID' -X PATCH https://analyticshub.googleapis.com/v1/projects/DCR_PROJECT_ID/locations/LOCATION/dataExchanges/CLEAN_ROOM_ID/queryTemplates/QUERY_TEMPLATE_ID?updateMask=display_name -d
    'query_template {
    display_name: "query_template1"
  }'

替换以下内容：

  • DCR_PROJECT_ID：在其中创建数据净室的项目的 ID。
  • LOCATION：数据净室的位置。
  • CLEAN_ROOM_ID：数据净室 ID。
  • QUERY_TEMPLATE_ID：查询模板 ID。

提交查询模板以供审核

从下列选项中选择一项：

控制台

  1. 前往 Sharing (Analytics Hub) 页面。

    前往 Sharing (Analytics Hub)

  2. 点击包含查询模板的数据净室的显示名称。

  3. 在净室中，前往模板标签页。

  4. 在您要提交审核的模板所在的行中，依次点击操作 > 提交审核。相应模板现在的状态为需要审核。

API

以下示例展示了如何使用 CURL 命令提交查询模板以供审核：

  curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -H 'x-goog-user-project:DCR_PROJECT_ID' -X POST https://analyticshub.googleapis.com/v1/projects/DCR_PROJECT_ID/locations/LOCATION/dataExchanges/CLEAN_ROOM_ID/queryTemplates/QUERY_TEMPLATE_ID:submit

替换以下内容：

  • DCR_PROJECT_ID：在其中创建数据净室的项目的 ID。
  • LOCATION：数据净室的位置。
  • CLEAN_ROOM_ID：数据净室 ID。
  • QUERY_TEMPLATE_ID：查询模板 ID。

删除查询模板

您只能删除处于 DRAFT 状态的查询模板。如果查询模板已提交审核，您将无法再将其删除。

从下列选项中选择一项：

控制台

  1. 前往 Sharing (Analytics Hub) 页面。

    前往 Sharing (Analytics Hub)

  2. 点击包含查询模板的数据净室的显示名称。

  3. 在净室中，前往模板标签页。

  4. 在要删除的模板所在的行中，依次点击操作 > 删除模板。

API

以下示例展示了如何使用 CURL 命令删除查询模板：

  curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -H 'x-goog-user-project:DCR_PROJECT_ID' -X DELETE https://analyticshub.googleapis.com/v1/projects/DCR_PROJECT_ID/locations/LOCATION/dataExchanges/CLEAN_ROOM_ID/queryTemplates?queryTemplateId=QUERY_TEMPLATE_ID

替换以下内容：

  • DCR_PROJECT_ID：在其中创建数据净室的项目的 ID。
  • LOCATION：数据净室的位置。
  • CLEAN_ROOM_ID：数据净室 ID。
  • QUERY_TEMPLATE_ID：查询模板 ID。

模板审批者工作流

作为查询模板审批人，您可以批准查询模板。

如果 TVF 引用了您不拥有的数据（例如，其他贡献者的数据），则查询模板只能由相应数据的所有者批准。如果您创建的 TVF 仅引用您的数据（用于单向共享），则可以自行批准查询模板。

批准查询模板

从下列选项中选择一项：

控制台

  1. 前往 Sharing (Analytics Hub) 页面。

    前往 Sharing (Analytics Hub)

  2. 点击包含查询模板的数据净室的显示名称。

  3. 在净室中，前往模板标签页。

  4. 在需要您审核的模板所在的行中，依次点击审批状态 > 需要审核。

  5. 点击批准。

  6. 选择模板位置。此位置是创建 TVF 以进行分享的位置。

  7. 查看建议的查询模板。

  8. 如果查询模板获批可在净室中使用，请点击批准。

API

  1. 使用 jobserver.query 调用根据查询模板创建例程：

    curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -L -X POST https://bigquery.googleapis.com/bigquery/v2/projects/ROUTINE_PROJECT_ID/queries --data '{"query":"ROUTINE_CREATION_QUERY","useLegacySql":false}'

    替换以下内容：

    • ROUTINE_PROJECT_ID：创建例程的项目的 ID。
    • ROUTINE_CREATION_QUERY：用于创建例程的查询。

  2. 将您创建的例程添加到数据净室：

    curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -H 'x-goog-user-project:DCR_PROJECT_ID' -X POST https://analyticshub.googleapis.com/v1/projects/DCR_PROJECT_ID/locations/LOCATION/dataExchanges/CLEAN_ROOM_ID/listings?listingId=LISTING_ID -d
'{"bigqueryDataset":{"dataset":"projects/PROJECT_ID/datasets/DATASET_ID","selectedResources":[{"routine":"projects/PROJECT_ID/datasets/DATASET_ID/tables/ROUTINE_ID"}],},"displayName":"LISTING_NAME"}'

    替换以下内容：

    • DCR_PROJECT_ID：在其中创建数据净室的项目的 ID。
    • LOCATION：数据净室的位置。
    • CLEAN_ROOM_ID：数据净室 ID。
    • LISTING_ID：清单 ID。
    • PROJECT_ID：源数据集所在项目的 ID。
    • DATASET_ID：源数据集 ID。
    • ROUTINE_ID：例程 ID。
    • LISTING_NAME：商品详情名称。

  3. 将查询模板状态更新为 APPROVED：

    curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -L -X POST https://analyticshub.googleapis.com/v1/projects/DCR_PROJECT_ID/locations/LOCATION/dataExchanges/CLEAN_ROOM_ID/queryTemplates/QUERY_TEMPLATE_ID:approve  --data '{}'

    替换以下内容：

    • DCR_PROJECT_ID：在其中创建数据净室的项目的 ID。
    • LOCATION：数据净室的位置。
    • CLEAN_ROOM_ID：数据净室 ID。
    • QUERY_TEMPLATE_ID：查询模板 ID。

拒绝查询模板

在 Google Cloud 控制台中，您可以通过以下方式拒绝查询模板：

  • 不批准提交的查询模板审核。
  • 删除查询模板，以将其从数据净室中移除。

模板订阅方工作流

查询模板订阅者可以查看和订阅数据净室。如果仅将查询模板添加到数据净室，则订阅该净室只会授予对相应 TVF 的访问权限，而不会授予对底层共享数据的访问权限。

订阅查询模板

从下列选项中选择一项：

控制台

您可以通过订阅数据净室来订阅查询模板。系统会向所有已停用“禁止从关联的数据集访问商品详情”设置的商品详情授予访问权限。

如需订阅查询模板，请按以下步骤操作：

  1. 转到 BigQuery 页面。

    转到 BigQuery

  2. 前往您在订阅净室时创建的关联数据集。

  3. 打开关联数据集中共享的例程或 TVF。

  4. 点击调用表函数。

  5. 将该形参替换为接受的输入内容，即表名称或字段。

  6. 点击运行。

如果您无法在探索器面板中查看嵌套为关联数据集子元素的 TVF，可以直接在关联的数据集上查询 TVF：

SELECT * FROM `myproject.dcr_linked_dataset.mytvf`(TABLE myTable);

API

使用 projects.locations.dataExchanges.subscribe 方法。

以下示例展示了如何使用 curl 命令调用 projects.locations.dataExchanges.subscribe 方法：

  curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -L -X POST https://analyticshub.googleapis.com/v1/projects/DCR_PROJECT_ID/locations/LOCATION/dataExchanges/CLEAN_ROOM_ID:subscribe  --data '{"destination":"projects/SUBSCRIBER_PROJECT_ID/locations/LOCATION","subscription":"SUBSCRIPTION"}'

替换以下内容：

  • DCR_PROJECT_ID：在其中创建数据净室的项目的 ID。
  • LOCATION：数据净室的位置。
  • CLEAN_ROOM_ID：数据净室 ID。
  • SUBSCRIBER_PROJECT_ID：订阅方项目的 ID。
  • SUBSCRIPTION：订阅的名称。

订阅查询模板后，您可以直接在关联的数据集上查询 TVF：

SELECT * FROM `myproject.dcr_linked_dataset.mytvf`(TABLE myTable);

场景示例

查询模板可用于促进数据净室内的各种形式的数据协作。以下部分介绍了示例场景。

单向共享场景

数据发布者创建查询模板，以验证订阅合作伙伴是否只能运行发布者定义的查询。查询模板创建者最终会自行批准查询模板，因为没有其他贡献者被添加到数据净室中。

在此方案中，用户 A 是数据净室所有者，他创建了一个名为 campaign_analysis 的数据净室，并添加了一个包含 campaigns 表的名为 my_campaign 的数据集。用户 A 配置了汇总阈值政策和元数据控制措施，以验证只有元数据架构可见，订阅者无法访问源数据。然后，用户 A 通过定义 campaigns 表中的表值函数来创建查询模板，从而限制关联数据集的所有订阅者只能执行 TVF。

以下是 TVF 语法：

campaigns_template(t1 TABLE campaign_ID <STRING> ) AS (
SELECT WITH AGGREGATION_THRESHOLD company_id, company, sum(impressions) FROM myproject.my_campaign.campaigns
group by company_id, company
);

由于用户 A 具有 BigQuery Data Owner 角色，因此对广告系列表拥有适当的权限，可以在提交查询模板以供审核后立即自行批准该模板。

多方协作共享

净室所有者邀请一位可信的贡献者提出要针对彼此的数据运行的查询。双方都可以仅通过查看元数据架构来安全地提出查询，而无需访问底层共享数据。如果查询定义引用了不属于模板提议者的数据，则只有该数据的所有者才能批准相应模板。

在此方案中，用户 A 邀请数据净室贡献者用户 B 加入 campaign_analysis 净室。用户 B 希望通过查看 campaigns 表的元数据架构，提出将自己的数据与该表联接的查询模板。

以下是 TVF 语法：

campaigns_template(t1 TABLE campaign_ID <STRING> ) AS (
SELECT WITH AGGREGATION_THRESHOLD company_id, company, sum(impressions) FROM my_project.my_campaign.campaigns
group by company_id, company
);

由于用户 B 未添加且不拥有 campaigns 表，因此在提交查询模板以供审批后，只有用户 A 可以审批。如需使用查询模板，用户 B 必须订阅净室并调用 TVF。用户 B 传递自己的表（其中包含一个名为 campaign_ID 的字段）作为表形参，并且可以执行查询模板中定义的私有 SQL。值得注意的是，用户 B 无需将自己的数据添加到净室。

用户 B 还向净室添加了一个名为 my_transactions 的数据集，其中包含 transactions 表和 products 表。用户 B 配置了汇总阈值政策和元数据控制，以验证是否仅显示元数据架构，以及订阅者是否无法访问源数据。

用户 A 现在可以通过查看交易表的元数据架构，提出各种查询模板，将其自己的数据与交易表联接起来。以下是 TVF 语法示例：

transactions_template(t1 TABLE user_ID  <STRING> ) AS (
SELECT WITH AGGREGATION_THRESHOLD company_id, company, campaign_id, sku, category, date, sum(amount) FROM my_project.my_transactions.transactions
group by company_id, company, campaign_id, sku, category, date
);

transactions_template_with_join(t1 TABLE user_ID  <STRING> ) AS (
SELECT WITH AGGREGATION_THRESHOLD t.company_id, t.company, t.campaign_id, t.sku, t.date, p.product_name, p.product_category, sum(t.amount) FROM myproject.my_transactions.transactions t
left join my_project.my_transactions.products p
on t.product_id = p.product_id
group by t.company_id, t.company, t.campaign_id, t.sku, t.date, p.product_name, p.product_category
);

由于用户 A 未添加且不拥有 transactions 和 products 表，因此在提交查询模板以供审批后，只有用户 B 可以审批。若要使用查询模板，用户 A 必须订阅清室并调用 TVF。用户 A 传递自己的表（其中包含一个名为 user_ID 的字段）作为表形参，并且可以执行查询模板中定义的隐私 SQL。需要在此处注意的一点是，用户 A 无需将自己的数据添加到净室。

价格

使用查询模板的数据贡献者只需为数据存储付费。

使用查询模板的订阅者在运行查询时只需为计算（分析）付费。

后续步骤