示例 – 使用应用程序规范访问外部端点

本主题介绍如何配置 Snowflake Native App 以连接到 Snowflake 外部的端点。示例展示了如何配置应用程序的清单文件和安装脚本，以实现以下操作：

  • 使用 自动授予权限功能，向使用者请求创建外部访问集成所需的权限。

  • 将外部访问集成添加到应用程序中。

  • 使用 应用程序规范 向使用者请求权限，以连接到外部端点。

设置清单文件的版本

要启用应用程序权限的自动授予，请在清单文件的开头设置版本，如以下示例所示：

manifest_version: 2
Copy

在清单文件中请求 CREATE EXTERNAL ACCESS INTEGRATION 权限

CREATE EXTERNAL ACCESS INTEGRATION 权限允许应用程序在安装或升级过程中创建外部访问集成。要向使用者请求此权限，请在清单文件中添加以下条目：

privileges:
  - CREATE EXTERNAL ACCESS INTEGRATION:
      description: "Required to create eai integrations so we can simplify your life"
Copy

CREATE EXTERNAL ACCESS INTEGRATION 权限会在安装或升级前自动授予应用程序，并具有以下优势：

  • 使用者无需手动创建应用程序所需的外部访问集成，也无需通过引用方式批准访问。

  • 提供商无需编写代码来检查 CREATE EXTERNAL ACCESS INTEGRATION 权限是否存在，即可在安装或升级期间继续创建对象。

为外部访问集成创建网络规则

外部访问集成需要定义外部端点的网络规则。例如，要创建网络规则，请将 CREATE NETWORK RULE 命令添加到应用程序的安装脚本中：

CREATE OR REPLACE NETWORK RULE setup.my_network_rule
   TYPE = HOST_PORT
   VALUE_LIST = ( 'example.com' )
   MODE = EGRESS;
Copy

此命令会创建一个网络规则，用于定义到主机端口 example.com 的出站请求 (egress)。

创建外部访问集成

在安装脚本中创建网络规则后，使用 CREATE EXTERNAL ACCESS INTEGRATION 命令创建外部访问集成，如下例所示：

CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION my_app_prefix_eai_rule
  ALLOWED_NETWORK_RULES = (setup.my_network_rule)
  ENABLED = TRUE;
Copy

备注

此命令会在使用者账户中创建外部访问集成。但是，在使用者批准应用程序规范（该规范允许对所请求的主机端口进行外部访问）之前，该外部访问集成不可用。有关更多信息，请参阅 使用应用程序规范批准与外部资源的连接。

创建用户定义的函数以访问外部端点

创建外部访问集成之后，安装脚本可以创建用户定义的函数和存储过程，利用该集成连接到网络规则中定义的端点。

以下示例展示了一个用户定义的函数，该函数使用了 my_app_prefix_eai_rule 外部访问集成。

CREATE OR REPLACE FUNCTION setup.EXTERNAL_ACCESS_UDF(hostname STRING)
  RETURNS STRING
  LANGUAGE JAVA
  HANDLER='TestHostNameLookup.compute'
  EXTERNAL_ACCESS_INTEGRATIONS = (my_app_prefix_eai_rule)
  AS
  '
      import java.net.InetAddress;
      import java.net.UnknownHostException;
      class TestHostNameLookup {{
          public static String compute(String hostname) throws Exception {{
              InetAddress addr = null;
              try {
                  addr = InetAddress.getByName(hostname);
              } catch(UnknownHostException ex) {
                  return "Hostname lookup failed";
              }
              return "Hostname lookup successful";
          }
      }
';
GRANT USAGE ON FUNCTION setup.EXTERNAL_ACCESS_UDF(STRING)
  TO APPLICATION ROLE app_public;
Copy

此函数将 EXTERNAL_ACCESS_INTEGRATIONS 的值设置为之前创建的外部访问集成。

此函数使用 InetAddress Java 包来查找传递给该过程的主机名。提供的主机名必须与外部访问集成所用网络规则的 VALUE_LIST 属性中指定的值相匹配。

创建应用程序规范

应用程序可以在安装、升级期间，或在运行时通过存储过程来创建应用程序规范。以下示例展示如何使用 ALTER APPLICATION SET SPECIFICATIONS 命令创建应用程序规范：

ALTER APPLICATION SET SPECIFICATION my_app_specification
        TYPE = EXTERNAL_ACCESS
        LABEL = 'An external api'
        DESCRIPTION = 'Used to connect to an external API'
        HOST_PORTS  = 'example.com';
Copy
语言: 中文