向使用者请求引用和对象级权限¶

在使用者账户中定义引用的工作流程¶

要请求引用和对象级权限，提供商需在开发和发布 Snowflake Native App 时执行以下操作：

1. 确定哪些对象需要引用及其相应的权限。

2. 在清单文件中定义引用。

3. 在安装脚本中添加存储过程，以处理清单文件中定义的每个引用的回调。

安装 Snowflake Native App 之后，使用者执行以下操作：

1. 查看 Snowflake Native App 所需的引用。

2. 通过调用 SYSTEM$REFERENCE 系统函数来创建引用。

3. 运行回调存储过程，传递引用的 ID。

使用者运行回调存储过程后， Snowflake Native App 可以访问请求的对象。

此工作流程概述使用者手动创建引用的过程。请参阅 创建用户界面以请求权限和引用，详细了解如何创建用户界面，以允许使用者使用 Snowsight 创建引用并授予权限。

引用中可以包含的对象类型和权限¶

下表列出了引用可以包含的对象类型以及每个对象允许的权限：

删除引用定义¶

如果某个应用程序定义了引用，那么稍后会从该应用程序的后续版本中删除引用定义，调用依然使用已删除引用的任何函数或过程会导致使用者出错。例如，应用程序 my_app 版本 V1 的清单文件包括 REF_TO_TABLE 的引用定义，以及使用 REF_TO_TABLE 表引用创建 VIEW_SELECT_FROM_DEFINED_REF 视图的 CREATE_VIEW_FROM_TABLE 存储过程。

在 my_app V2 版本中，REF_TO_TABLE 的引用定义已从清单文件中移除。当使用者将其安装的应用程序 my_app 升级到版本 V2 时，调用 CREATE_VIEW_FROM_TABLE 过程会导致以下错误：

Reference definition '<REF_DEF_NAME>' cannot be found in the current version of the application '<APP_NAME>'

使用引用运行查询¶

以下示例演示如何使用引用运行查询：

SELECT * FROM reference('consumer_table');

SELECT reference('encrypt_func')(t.c1) FROM consumer_table t;

使用引用调用存储过程¶

以下示例演示如何使用引用调用存储过程：

CALL reference('consumer_proc')(11, 'hello world');

使用引用运行 DML 命令¶

以下示例演示如何使用引用修改表中的数据：

INSERT INTO reference('data_export')(C1, C2)
  SELECT T.C1, T.C2 FROM reference('other_table')

COPY INTO reference('the_table') ...

使用引用运行 DESCRIBE 命令¶

以下示例演示如何使用引用运行 DESCRIBE 操作：

DESCRIBE TABLE reference('the_table')

在任务中使用引用¶

CREATE TASK app_task
  WAREHOUSE = reference('consumer_warehouse')
  ...;

ALTER TASK app_task SET WAREHOUSE = reference('consumer_warehouse');

在视图定义中使用引用¶

CREATE VIEW app_view
  AS SELECT reference('function')(T.C1) FROM reference('table') AS T;

在函数正文中使用引用¶

CREATE FUNCTION app.func(x INT)
  RETURNS STRING
  AS $$ select reference('consumer_func')(x) $$;

在外部函数中使用引用¶

CREATE EXTERNAL FUNCTION app.func(x INT)
  RETURNS STRING
  ...
  API_INTEGRATION = reference('app_integration');

在函数或过程中使用引用¶

CREATE FUNCTION app.func(x INT)
  RETURNS STRING
  ...
  EXTERNAL_ACCESS_INTEGRATIONS = (reference('consumer_external_access_integration'), ...);
  SECRETS = ('cred1' = reference('consumer_secret'), ...);

为了允许使用者调用使用对外部访问集成或密钥的引用的函数或存储过程，提供商可以执行以下操作：

1. 在安装脚本中，创建使用引用的函数或存储过程，例如：function_with_eai_secret_reference，如以下示例所示：

   CREATE FUNCTION app_schema.function_with_eai_secret_reference(arg1 STRING)
     RETURNS string
     LANGUAGE python
     RUNTIME_VERSION = 3.8
     HANDLER = 'my_handler'
     EXTERNAL_ACCESS_INTEGRATIONS = (reference('eai_ref'))
     PACKAGES = ('snowflake-snowpark-python','requests')
     SECRETS = ('cred' = reference('secret_ref') )
     ...
   AS
   $$
   

   Copy

2. 在安装脚本中，创建一个名为 my_wrapper_procedure 的包装器存储过程。

   CREATE OR REPLACE PROCEDURE app_schema.my_wrapper_procedure(arg1 STRING)
     RETURNS STRING
     LANGUAGE SQL
     AS
     $$
       BEGIN
           ...
       END;
     $$;
   

   Copy

备注

包装器必须是存储过程，而不是函数。

1. 在 my_wrapper_procedure 中，添加对 function_with_eai_secret_reference 的调用，如以下示例所示：

   BEGIN
     RETURN app_schema.function_with_eai_secret_reference(arg1);
   END;
   

   Copy

2. 向应用程序角色授予 my_wrapper_procedure，以允许使用者调用该过程，如以下示例所示：

   GRANT USAGE ON PROCEDURE app_schema.my_wrapper_procedure(STRING)
     TO APPLICATION ROLE app_role;
   

   Copy

安装该应用程序后，使用者可以调用 my_wrapper_procedure，然后该存储过程再调用 function_with_eai_secret_reference。

在策略中使用引用¶

CREATE ROW ACCESS POLICY app_policy
  AS (sales_region varchar) RETURNS BOOLEAN ->
  'sales_executive_role' = reference('get_sales_team')
    or exists (
      select 1 from reference('sales_table')
        where sales_manager = reference('get_sales_team')()
        and region = sales_region
      );

外部访问集成的 JSON 格式¶

对于 EXTERNAL ACCESS INTEGRATION 引用，JSON 响应的预期结构是：

{
  "type": "CONFIGURATION",
  "payload": {
    "host_ports": ["host_port_1", ...],
    "allowed_secrets": "NONE|ALL|LIST",
    "secret_references": ["ref_name_1", ...]
  }
}

• host_ports

  字符串数组。每个值都必须是有效的域。

  或者，它还可以包括一个端口。有效端口范围为 1 至 65535（含 1 和 65535）。如果未指定端口，则默认为 443。如果外部网络位置支持动态端口，则需要指定所有可能的端口。

  • 要允许访问所有端口，请将端口指定为 0，例如：example.com:0。

  这些值用于为外部访问集成创建出口网络规则。有关更多信息，请参阅 CREATE NETWORK RULE。

• allowed_secrets

  指定 EXTERNAL ACCESS INTEGRATION 引用允许的密钥。有效值为：

  • NONE：不允许密钥。

  • ALL：允许任何现有的密钥。

  • LIST：允许在 secret_references 属性中指定的一组特定密钥。

  allowed_secrets 的值用于创建外部访问集成。有关更多信息，请参阅 CREATE EXTERNAL ACCESS INTEGRATION。

• secret_references：

  指定外部访问集成允许的密钥引用的列表。

  此处指定的值必须与清单中定义的密钥引用相同。

  此属性仅在 allowed_secrets 设置为 LIST 时适用。在此上下文中，secret_references 为必需的。

密钥引用的 JSON 格式¶

对于密钥引用，JSON 响应的预期结构为：

{
  "type": "CONFIGURATION",
    "payload": {
            "type": "OAUTH2",
            "security_integration": {
                    "oauth_scopes": ["scope_1", "scope_2"],
                    "oauth_token_endpoint" : "token_endpoint",
                    "oauth_authorization_endpoint" : "auth_endpoint"
            }
    }
}

• payload.type

  密钥的类型。有效值为：

  • OAUTH2：指定要用于 OAuth2 授予流程的密钥。有关更多信息，请参阅 CREATE SECRET。

• payload.security_integration

  指定为 OAuth 密钥配置 API 身份验证 所需的值。

JSON 格式错误响应¶

如果出现错误或引用尚未准备好进行配置，则错误响应的预期结构为：

 {
   "type": "ERROR",
   "payload":{
     "message": "The reference is not available for configuration ..."
  }
}

• message：Snowsight 中显示的应用程序的错误消息。