多提供商使用者分析

使用者可以在一次请求中，对同一提供商或多个提供商所拥有的多个 Clean Room 执行分析，并查看合并结果。该结果是每个 Clean Room 的分析结果的并集，而不是使用者数据与多个 Clean Room 中提供商数据的并集进行分析后的结果。

在批准请求之前，提供商可以查看请求的所有细节，包括正在查询的其他 Clean Room 以及模板。但提供商无法查看其他 Clean Room 中的数据，甚至无法知道其他 Clean Room 中查询的是哪些提供商的表。每个 Clean Room 中的数据都会在安全和符合其联接策略、列策略及其他策略的前提下进行访问和处理。

如果所有 Clean Room 都启用了激活功能，则可以激活多提供商分析结果。

要求

  • 模板： 多提供商分析可以在任何 Snowflake 提供的或自定义的模板上运行。

  • 环境： 多提供商分析只能通过使用 Clean Room API 来实现。它无法在 Clean Room 的 UI 中运行。

  • 计费： 由使用者为多提供商查询付费。

  • 其他要求： 多提供商分析中的所有 Clean Room 必须具有提供商联接策略。如果某个 Clean Room 中的分析失败，则整个请求将失败。

多提供商分析概述

以下是多提供商分析工作原理的概述。有关可运行的示例代码，请参阅代码示例。

  1. 使用者以标准方式安装所有用于多提供商流程的 Clean Room。在多提供商分析中，Clean Room 是标准 Clean Room。

  2. 使用者以标准方式关联数据集并设置联接策略。无论模板是否检查策略，提供商和使用者的 Clean Room 都必须定义联接策略。

  3. 请求的是单一模板，所有 Clean Room 都必须安装该模板。如果使用者想要使用自定义模板，则必须通过 标准的使用者模板请求流程：

    1. 使用者在每个 Clean Room 上调用 consumer.create_template_request，并传入自定义模板。

    2. 提供商调用 provider.list_pending_template_requests 查看待处理的模板请求，然后调用 provider.approve_template_request 以批准将模板添加至其 Clean Room。

    3. 使用者调用 consumer.list_template_requests 以查看请求是否已获批准。

  4. 提供商和使用者以标准方式为模板设置列策略。

  5. 提供商在每个 Clean Room 上调用 provider.enable_multiprovider_computation，以接收来自使用者的请求。（在此调用之前发送的请求会排入队列，但在调用此过程之前，提供商无法看到这些请求。）

  6. 使用者请求批准以运行模板。申请和批准流程有一些变体，但以下为默认流程：

    1. 使用者通过调用 consumer.prepare_multiprovider_flow 向所有 Clean Room 发送多提供商请求。该请求指定了 Clean Room 列表、使用的模板以及所有模板参数，包括提供商和使用者表。该调用只需执行一次，就会广播到请求中的所有 Clean Room。每个 Clean Room 都可看到完整请求详情，但提供商表列表会被筛选为当前 Clean Room 中的提供商表。它会返回一个请求 ID。

    2. 每个提供商调用 provider.view_multiprovider_requests 查看使用者发送的多提供商请求，然后调用 provider.process_multiprovider_request 以批准该请求。

  7. 当所有 Clean Room 均已批准该请求后，使用者调用 consumer.execute_multiprovider_flow 以运行该请求。模板将按照最近一次的 consumer.prepare_multiprovider_flow 请求提供的信息在每个 Clean Room 中运行，并将合并后的结果发送给使用者。除非提供商撤销了查询权限，或使用者用完了差分隐私预算（若启用了差分隐私），使用者可以再次调用 execute_multiprovider_flow 而无需重新获得批准。

请求与批准细节

以下是有关请求和批准流程的详细信息。该过程有多个变体。

请求和批准流程的变体

运行多提供商分析时，可能有三种流程：

按请求批准（默认行为）：

  1. 使用者 调用 consumer.prepare_multiprovider_flow 并提供查询详情。

  2. 提供商 查看查询 (provider.view_multiprovider_requests) 并批准它 (provider.process_multiprovider_request)。如果提供商 此前已批准该查询，则可省略此步骤。

  3. 使用者 运行查询 (consumer.execute_multiprovider_flow)。

按使用者和 Clean Room 批准：

  1. 使用者 调用 consumer.prepare_multiprovider_flow 并提供查询详情。

  2. 提供者 查看查询 (provider.view_multiprovider_requests) 并批准它 (provider.process_multiprovider_request)，传入 -1 作为查询 ID，而不是实际查询 ID。因此，使用者仍需为后续请求调用 consumer.prepare_multiprovider_flow，但无需提供商额外批准，系统会自动批准。

  3. 使用者 运行查询 (consumer.execute_multiprovider_flow)。

自动批准：

  1. 提供商 在 Clean Room 上调用 provider.resume_multiprovider_tasks。该 Clean Room 中所有来自使用者的多提供商请求都将自动获得批准。

  2. 使用者 调用 consumer.prepare_multiprovider_flow 并提供查询详情。该请求会自动获得批准。

  3. 使用者 运行查询 (consumer.execute_multiprovider_flow)。

在所有流程中，您可以 撤消之前已授予的任何查询批准。

查询批准的标准

consumer.execute_multiprovider_flow 会评估最近一次发送到 consumer.prepare_multiprovider_flow 的查询，以查看其是否已获得批准。如果找到匹配的已批准请求，则查询将继续进行。如果未找到之前的匹配请求，则 consumer.execute_multiprovider_flow 将失败。（如果已为该使用者或所有使用者授予了 全面批准，则会跳过批准检查步骤。）先前的审批将根据以下值进行匹配：

  • 查询涉及的 Clean Room 列表。

  • 发送到 Clean Room 的实参名称。在已批准的请求中存在的所有实参名称都必须存在于新请求中。不检查实参值，只检查实参名称。

  • 运行的模板的名称。

此外，无论是否获得全面批准，该模板都必须符合所有 Clean Room 策略，包括行策略、列策略和差分隐私（如果启用）。

批准历史记录

consumer.execute_multiprovider_flow 尝试运行最近一次发送到 consumer.prepare_multiprovider_flow 的查询。如果所有安全检查都通过并且之前有匹配的查询已获得批准，则该查询可以运行。因此，您会看到以下流程：

  1. 使用者准备查询 A。

  2. 提供商批准 A。

  3. 使用者运行 A。

  4. 使用者准备查询 B。

  5. 提供商批准 B。

  6. 使用者运行 B。

  7. 使用者使用所有相同的参数再次准备查询 A。

  8. 使用者可以在未经提供商批准的情况下再次运行 A，因为它已经获得批准。请参阅下一节，了解 Clean Room 如何确定查询是否已获得批准。

启用或禁用自动查询批准

您可以在 Clean Room 中为某个使用者或所有使用者启用查询自动批准功能。

要在 Clean Room 中为 某个给定使用者 启用自动批准所有多提供商查询，提供商可调用 provider.process_multiprovider_request，并使用 -1 作为查询 ID。然后，该使用者在 Clean Room 中提出的所有多提供商请求都将获得批准。（使用者在更改查询时仍必须调用 consumer.prepare_multiprovider_flow，并且提供商仍将在 provider.view_multiprovider_requests 请求历史记录中看到所有 consumer.prepare_multiprovider_flow 调用。）要禁用授予给定用户的自动批准，必须 更新批准日志。

若要为 所有使用者 启用自动批准所有多提供商查询，提供商可在 Clean Room 中调用 provider.resume_multiprovider_tasks。然后，来自所有使用者的所有多提供商请求都将自动获得批准。（使用者在更改查询时仍必须调用 consumer.prepare_multiprovider_flow，并且提供商仍将在 consumer.prepare_multiprovider_flow 请求历史记录中看到所有 provider.view_multiprovider_requests 调用。）要禁用以这种方式授予的自动批准，请调用 provider.suspend_multiprovider_tasks。

设计模板

多提供商流程的测试非常耗时，并且有许多可以掩盖模板错误的步骤，因此，在使用模板之前，请在提供商创建的、使用者运行的基本流程中测试模板，然后在多提供商流程中使用模板，确保模板正确无误。

每个 Clean Room 运行完全相同的模板，但是传入每个 Clean Room 的 source_table 列表的长度和表名可能会有所不同，因为该列表经过筛选后仅显示该 Clean Room 中的提供商表。因此，根据您的查询，您可能需要使用 Jinja 循环和条件语句来处理不同的列表长度或表名。

管理自动批准并更改批准状态

请求历史记录日志

当提供商调用 provider.enable_multiprovider_computation 时，这将创建一个名为 samooha_cleanroom_cleanroom_ID.admin.request_log_multiprovider 的日志表。每当提供商批准 Clean Room 中的多提供商分析时，该请求都会记录在此处。这是当使用者请求执行多提供商查询时，Clean Room 会检查的表。该表包含一个 approved 列，用于指示是否允许执行请求。由于查询必须获得批准才能添加到表中，因此初始 approved 状态为 true，但如果您决定撤消批准，可以 稍后更改它。

该日志表保存来自 provider.process_multiprovider_request 的使用者查询请求，而不是使用者的查询执行情况。不会记录使用者的查询执行情况。

拒绝先前已批准的请求

要拒绝先前已批准的请求，必须将多提供商请求日志表中的 approved 列更新为 FALSE。

由于使用者可以多次提交相同的查询，并且对给定查询的任何批准都允许运行该查询，因此为禁用多提供商查询，最安全的做法是将给定使用者的所有查询都设为 approved=false，然后告诉使用者通过调用 consumer.prepare_multiprovider_flow 重新提交他们想要运行的任何查询。

-- Revoke access to a query you had previously approved
UPDATE samooha_cleanroom_Samooha_Cleanroom_Multiprovider_Clean_Room_1.admin.request_log_multiprovider
  SET APPROVED=FALSE
  WHERE PARTY_ACCOUNT='<CONSUMER_LOCATOR>';
Copy

启用先前被拒绝的请求

如果您之前批准了请求，然后又拒绝了该请求，并想重新批准该请求，那么通常最安全的做法是要求使用者重新提交其流程请求，然后在标准流程中批准该请求，而不是更新请求日志表。

撤销自动批准

  • 如果您在 Clean Room 中通过调用 provider.resume_multiprovider_tasks 为 所有使用者 启用了自动批准，则可通过调用 provider.suspend_multiprovider_tasks 撤销对所有用户的全面批准。

  • 若您通过将 -1 指定为 provider.process_multiprovider_request 中的 ID，从而在 Clean Room 中启用了 针对特定使用者 的自动批准，请参阅 拒绝先前已批准的请求。

代码示例

下载以下工作簿来尝试多提供商分析流程。您需要两个安装了 Clean Room API 的 Snowflake 账户：一个用作提供商，另一个用作使用者。提供商账户需创建两个 Clean Room，其行为类似于让多个提供商各拥有一个 Clean Room。

语言: 中文