使用开发者 API 添加使用者定义的模板¶

在传统 Snowflake Data Clean Rooms 流中，提供商使用开发者 API 创建自定义模板，然后将其添加到提供商与使用者共享的 Clean Room。然后，使用者使用该模板在 Clean Room 中运行分析。

在某些情况下，使用者希望能够创建自己的自定义模板，控制可在 Clean Room 中执行的分析类型。在此场景中，提供商仍然创建和共享 Clean Room，但使用者在该 Clean Room 内定义模板。因为它是他们的 Clean Room，提供商必须明确允许将此使用者定义的模板添加到 Clean Room。

使用者贡献的 Clean Room 模板包括 JinjaSQL 代码，还可能包括自定义 Python 代码。

在多提供商 Clean Room 中，通常需要能够将使用者定义的模板添加到提供商的 Clean Room，因为在该 Clean Room 中，使用者同时针对多个供应商的数据运行分析。在这种环境中，使用者可能更了解如何从多方数据中提取见解，并可以使用开发者 API 创建自定义模板来做到这一点。在多提供商环境中使用使用者定义的模板时，每个提供商都必须批准模板才能使用。有关如何使用多提供商 Clean Room 的扩展示例，请参阅 Snowflake Data Clean Room：多提供商 Clean Room。

使用者定义的模板的基本工作流程¶

要使用开发者 API 将使用者定义的模板添加到提供商 Clean Room，流程涉及使用者和提供商双方的协调操作。此基本工作流程是：

使用者:

向 Clean Room 的提供商发送请求，要求添加自定义模板。此请求包括模板的定义，模板是用 Jinja 模板语言编写。

提供商:

检查来自希望向 Clean Room 添加模板的使用者的新请求。
审核模板定义后，批准或拒绝请求。

使用者:

检查他们的请求是否获得批准。使用者可以随时检查请求的状态。

请求添加模板¶

使用者执行 consumer.create_template_request 命令，向 Clean Room 的提供商发送请求。此请求包括模板的名称，以及用于定义模板的 Jinja 代码。

例如，假设提供商与使用者共享了 Clean Room dcr_cleanroom。使用者希望将名为 my_overlap_analysis 的模板添加到 Clean Room。要向 Clean Room 的提供商发送请求，使用者执行以下命令：

CALL samooha_by_snowflake_local_db.consumer.create_template_request('dcr_cleanroom',
  'my_analysis',
  $$
  SELECT
      identifier({{ dimensions[0] | column_policy }})
  FROM
      identifier({{ my_table[0] }}) c
    INNER JOIN
      identifier({{ source_table[0] }}) p
        ON
          c.identifier({{ consumer_id  }}) = identifier({{ provider_id | join_policy }})
       {% if where_clause %} where {{ where_clause | sqlsafe | join_and_column_policy }} {% endif %};
  $$);

Copy

第三个实参是用于定义模板的 Jinja 代码。

有关 consumer.create_template_request 命令的参考文档，请参阅 Snowflake Data Clean Room：使用者 API 参考指南中的“使用者定义的模板”部分。

在模板中包含 Python 代码¶

如果您在模板中包含 Python，JinjaSQL 模板可以调用 Python 函数。

要在模板中包含 Python 代码，请执行以下步骤：

编写 Python 代码。
调用 consumer.generate_python_request_template，传递代码以生成一个模板，其中包含 JinjaSQL 代码的占位符。consumer.generate_python_request_template 只能为单个函数创建模板代码。如果您需要在 SQL 模板中支持多个 Python 函数，请为每个自定义 Python 函数调用 generate_python_request_template，并将结果合并到单个模板中。

检查来自使用者的新请求¶

要检查来自使用者的新请求，提供商执行 provider.list_template_requests 命令，然后解析结果以识别状态为 PENDING 的请求。PENDING 状态表示使用者已发送新请求，但提供商尚未对此采取行动。对 provider.list_template_requests 的响应包括模板的 Jinja 代码，以便提供商决定他们是批准还是拒绝请求。

例如，假设提供商的 Clean Room 的名称为 dcr_cleanroom。要检查使用者是否发送了新请求以添加模板，提供商执行以下命令：

CALL samooha_by_snowflake_local_db.provider.list_template_requests('dcr_cleanroom');

SELECT * FROM TABLE(RESULT_SCAN(LAST_QUERY_ID())) WHERE status = 'PENDING';

Copy

对 provider.list_template_requests 命令的响应包括每个模板请求的以下内容：

唯一标识请求的 UUID。
发送请求的使用者账户，采用账户定位器格式。
模板名称，由使用者在发送请求时指定。
用于定义模板的 Jinja 代码。
请求的状态，可以是 PENDING、APPROVED 或 REJECTED 之一。

有关 provider.list_template_requests 命令的参考文档，请参阅 Snowflake Data Clean Room：提供商 API 参考指南中的“使用者定义的模板”部分。

批准或拒绝请求¶

在收到要添加使用者定义模板的请求后，提供商决定是批准还是拒绝请求。

批准请求

提供商执行 provider.approve_template_request 命令以批准要添加模板的请求。提供商以实参的形式传递请求标识符，以指定要批准的模板。

例如，假设提供商的 Clean Room 名称为 dcr_cleanroom，并且为使用者的模版添加请求分配了标识符 01b4d41d-0001-b572。要批准请求并将模板添加到 Clean Room，提供商执行以下命令：

CALL samooha_by_snowflake_local_db.provider.approve_template_request('dcr_cleanroom',
  '01b4d41d-0001-b572');

Copy

拒绝请求

提供商执行 provider.reject_template_request 命令以拒绝模版添加请求。提供商以实参的形式传递请求标识符，以指定要拒绝的模板。

例如，假设提供商的 Clean Room 名称为 dcr_cleanroom，并且为使用者的模版添加请求分配了标识符 01b4d41d-0001-b572。在检查 Jinja 模板之后，提供商确定它给 Clean Room 带来了安全风险，因此他们希望以描述性理由拒绝请求。要拒绝模版添加请求，提供商执行以下命令：

CALL samooha_by_snowflake_local_db.provider.reject_template_request('dcr_cleanroom',
  '01b4d41d-0001-b572',
  'Failed security assessment');

Copy

有关 provider.approve_template_request 和 provider.reject_template_request 命令的参考文档，请参阅 Snowflake Data Clean Room：提供商 API 参考指南中的“使用者定义的模板”部分。

以使用者身份检查请求的状态¶

在任何时候，使用者都可以执行 consumer.list_template_requests 命令，以检查其模板添加请求的状态。该命令返回以下信息：

唯一标识请求的 UUID。
请求发送到的提供商账户，采用账户定位器格式。
模板名称，由使用者在发送请求时指定。
用于定义模板的 Jinja 代码。
请求的状态，可以是 PENDING、APPROVED 或 REJECTED 之一。
提供商操作的原因（如果请求遭据的话）。

例如，假设使用者向 dcr_cleanroom Clean Room 发送模板添加请求。要检查请求的状态以确定请求是否获得批准，使用者执行以下命令：

CALL samooha_by_snowflake_local_db.consumer.list_template_requests('dcr_cleanroom');

Copy

有关 consumer.list_template_requests 命令的参考文档，请参阅 Snowflake Data Clean Room：使用者 API 参考指南中的“使用者定义的模板”部分。

列出来自使用者的所有请求¶

提供商执行 provider.list_template_requests 命令以查看所有请求，包括已批准或拒绝的请求。

例如，假设提供商的 Clean Room 的名称为 dcr_cleanroom。要列出所有已发出的请求而不管结果如何，提供商执行以下命令：

CALL samooha_by_snowflake_local_db.provider.list_template_requests('dcr_cleanroom');

Copy

有关 provider.list_template_requests 命令的参考文档，请参阅 Snowflake Data Clean Room：提供商 API 参考指南中的“使用者定义的模板”部分。