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

关于引用¶

在某些情况下，已安装的 Snowflake Native App 需要访问使用者账户中存在于 APPLICATION 对象外部的现有对象。例如，应用程序可能需要访问使用者数据库中的现有表。

在这种情况下，使用者仅授予 APPLICATION 对象对对象的访问权限并不够，因为应用程序无法确定使用者账户中的架构和对象的名称。

为了让 Snowflake Native App 访问 APPLICATION 对象外部的现有对象，Snowflake Native App Framework 提供了引用，允许客户指定对象的名称和架构，并启用对该对象的访问。

在清单文件中定义引用¶

以下示例演示如何在 manifest.yml 文件中为 APPLICATION 对象外部存在的使用者账户中的表定义引用：

references:
  - consumer_table:
      label: "Consumer table"
      description: "A table in the consumer account that exists outside the APPLICATION object."
      privileges:
        - INSERT
        - SELECT
      object_type: TABLE
      multi_valued: false
      register_callback: config.register_single_reference

此示例定义了名为 consumer_table 的引用，它需要具有使用者账户中表的 INSERT 和 SELECT 权限。register_callback 属性指定用于将使用者表绑定到此引用定义的存储过程。

使用 multi_valued 将多个使用者对象绑定到同一引用。当指定此属性时，将对具有单个值引用的对象执行相同的操作。该属性还可以用于具有多值引用的对象。请参阅 支持的引用函数 以了解有关 Snowflake Native App Framework 引用操作的更多信息。

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

为引用创建回调存储过程¶

在 manifest.yml 文件中定义引用后，提供商必须向安装脚本添加存储过程，以注册引用的回调。

以下示例演示用于处理 在清单文件中定义引用 中所示引用的回调的存储过程：

CREATE APPLICATION ROLE app_admin;

CREATE OR ALTER VERSIONED SCHEMA config;
GRANT USAGE ON SCHEMA config TO APPLICATION ROLE app_admin;

CREATE PROCEDURE CONFIG.REGISTER_SINGLE_REFERENCE(ref_name STRING, operation STRING, ref_or_alias STRING)
  RETURNS STRING
  LANGUAGE SQL
  AS $$
    BEGIN
      CASE (operation)
        WHEN 'ADD' THEN
          SELECT SYSTEM$SET_REFERENCE(:ref_name, :ref_or_alias);
        WHEN 'REMOVE' THEN
          SELECT SYSTEM$REMOVE_REFERENCE(:ref_name, :ref_or_alias);
        WHEN 'CLEAR' THEN
          SELECT SYSTEM$REMOVE_ALL_REFERENCES(:ref_name);
      ELSE
        RETURN 'unknown operation: ' || operation;
      END CASE;
      RETURN NULL;
    END;
  $$;

GRANT USAGE ON PROCEDURE CONFIG.REGISTER_SINGLE_REFERENCE(STRING, STRING, STRING)
  TO APPLICATION ROLE app_admin;

此示例创建名为 REGISTER_SINGLE_REFERENCE 的存储过程，用于调用系统函数，对作为实参传递给存储过程的引用执行特定操作。

创建用于请求对象配置的回调存储过程¶

对于某些对象类型，提供商必须向安装脚本添加存储过程以提供其他配置。当使用者允许引用使用 Snowsight 时，将使用此回调。

以下示例演示如何为 在清单文件中定义引用 中所示的引用定义配置回调存储过程：

CREATE OR REPLACE CONFIG.GET_CONFIGURATION_FOR_REFERENCE(ref_name STRING)
  RETURNS STRING
  LANGUAGE SQL
  AS
  $$
  BEGIN
    CASE (ref_name)
      WHEN 'CONSUMER_EXTERNAL_ACCESS' THEN
        RETURN '{
          "type": "CONFIGURATION",
          "payload":{
            "host_ports":["google.com"],
            "allowed_secrets" : "LIST",
            "secret_references":["CONSUMER_SECRET"]}}';
      WHEN 'CONSUMER_SECRET' THEN
        RETURN '{
          "type": "CONFIGURATION",
          "payload":{
            "type" : "OAUTH2",
            "security_integration": {
              "oauth_scopes": ["https://www.googleapis.com/auth/analytics.readonly"],
              "oauth_token_endpoint": "https://oauth2.googleapis.com/token",
              "oauth_authorization_endpoint":
                "https://accounts.google.com/o/oauth2/auth"}}}';
     END CASE;
     RETURN '';
   END;
   $$;

GRANT USAGE ON PROCEDURE CONFIG.GET_CONFIGURATION_FOR_REFERENCE(STRING)
  TO APPLICATION ROLE app_admin;

此示例创建名为 GET_CONFIGURATION_FOR_REFERENCE 的存储过程，该存储过程返回 JSON 格式的配置，用于构建类型为 EXTERNAL ACCESS INTEGRATION 的引用或 SECRET 引用。Switch 语句中的条目应该映射到 manifest.yml 文件中的引用名称。

查看应用程序中定义的引用¶

当提供商在 manifest.yml 文件中定义引用时，它们将作为已安装的 Snowflake Native App 包含在内。

要查看为 Snowflake Native App 定义的引用，请运行 SHOW REFERENCES 命令，如以下示例所示：

SHOW REFERENCES IN APPLICATION hello_snowflake_app;

将对象绑定到应用程序¶

在查看 Snowflake Native App 的引用定义后，使用者可以运行 SYSTEM$REFERENCE 系统函数来创建引用，如以下示例所示：

SELECT SYSTEM$REFERENCE('table', 'db1.schema1.table1', 'persistent', 'select', 'insert');

此命令会返回引用的标识符。使用者可以将标识符传递给引用的回调存储过程，如以下示例所示：

CALL app.config.register_single_reference(
  'consumer_table' , 'ADD', SYSTEM$REFERENCE('TABLE', 'db1.schema1.table1', 'PERSISTENT', 'SELECT', 'INSERT'));

在本例中，consumer_table 是 manifest.yml 文件中定义的引用的名称。使用者运行关联引用的存储过程后，Snowflake Native App 可访问使用者账户中的表。

:ref:` 上一部分 <label-native_apps_reference_create_callback>` 中的回调存储过程调用 SYSTEM$SET_REFERENCE 系统函数，如以下示例所示：

SELECT SYSTEM$SET_REFERENCE(:ref_name, :ref_or_alias);

有关与引用相关的其他系统功能，请参阅 支持的引用函数。

使用引用时的注意事项¶

Snowflake 建议您不要跨版本修改引用定义。要在新版本中更新引用定义（例如，要将权限更改为 SELECT、SELECT 中的 INSERT），您必须定义具有不同名称的新引用定义。已更新的 Snowflake Native App 可以在新版本的应用程序中使用此新引用。

要在另一个对象中嵌入引用（例如，将引用分配给变量），该引用必须已绑定到使用者账户中的对象。例如，除非您首先将引用绑定到使用者仓库，否则无法创建任务。

在 Snowflake Native App 中使用引用的示例¶

以下部分提供在不同上下文中使用引用的示例。

SELECT * FROM reference('consumer_table');

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

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

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

COPY INTO reference('the_table') ...

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'), ...);

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 格式¶

配置回调函数返回一个 JSON 格式的响应。外部访问集成和密钥引用返回的 JSON 格式不同。

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

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

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

支持的引用函数¶

Snowflake Native App Framework 支持以下函数执行与引用相关的不同操作。