使用应用程序规范来请求外部访问集成 (EAIs)

本主题介绍了如何配置 Snowflake Native App，以使用应用程序规范来请求访问使用者账户中的外部访问集成 (EAI)。外部访问集成允许应用程序连接到 Snowflake 外部的端点。

从应用程序访问外部端点

要访问外部端点，应用程序必须创建网络规则和外部访问集成。外部访问集成使用网络规则限制对特定外部网络位置的访问。网络规则定义了应用程序可以访问的外部端点。

要配置应用程序以使用外部访问集成，请执行以下操作：

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

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

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

备注

单一应用程序规范适用于该应用程序创建的所有外部访问集成。提供商可以为一个应用程序创建多个应用程序规范，但这并不是必需的。

外部访问集成的应用程序规范工作流程

配置应用程序以使用外部访问集成的一般工作流程如下：

  1. 提供商为应用程序配置 自动授予权限功能。这允许使用者授权应用程序创建外部访问集成。

    备注

    应用程序规范要求在清单文件中设置 manifest_version = 2。

  2. 提供商将 CREATE EXTERNAL ACCESS INTEGRATION 权限 添加到清单文件中。

  3. 提供商在安装脚本中添加 SQL 语句，根据需要创建以下对象：

    安装脚本会在应用程序安装、升级或运行时创建应用程序规范及其他对象。

  4. 使用者在配置应用程序时批准主机端口和其他外部服务。有关使用者如何查看和批准应用程序规范的更多信息，请参阅 使用应用程序规范批准与外部资源的连接。

外部访问集成的应用程序规范定义

对于外部访问集成，应用程序规范定义包含以下条目：

  • HOST_PORTS：应用程序所需的网络规则中定义的主机端口列表。

  • PRIVATE_HOST_PORTS：选择使用 时默认使用的角色和仓库。允许与 Snowflake 外部资源建立专用连接的专用主机端口列表。

备注

这些值必须与应用程序在 创建网络规则 时使用的值匹配。

设置清单文件的版本

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

manifest_version: 2
Copy

将 CREATE EXTERNAL ACCESS INTEGRATION 权限添加到清单文件

CREATE EXTERNAL ACCESS INTEGRATION 权限允许应用程序在安装或升级过程中创建外部访问集成。要配置应用程序以请求 CREATE EXTERNAL ACCESS INTEGRATION 权限，请将以下代码添加到清单文件的 privileges 部分：

manifest_version: 2
...
privileges:
  - CREATE EXTERNAL ACCESS INTEGRATION:
      description: "Allows the app to create an external access integration to connect to an external service."
...
Copy

通过 manifest_version: 2，当安装或升级应用程序时，Snowflake 会自动向应用程序授予 CREATE EXTERNAL ACCESS INTEGRATION 权限。

向安装脚本添加网络规则和外部访问集成

外部访问集成是 Snowflake 中用于访问特定外部网络位置的对象。外部访问集成包含一系列网络规则，用于指定应用程序可以访问的外部位置。

要为应用程序创建网络规则，请将 CREATE NETWORK RULE 命令添加到安装脚本中，如下例所示：

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

HOST_PORT 和 VALUE_LIST 属性表示网络规则必须指向有效的域、端口或端口范围。安装或升级应用程序后，使用者将授予应用程序使用这些域或端口的权限。

创建外部访问集成

要为应用程序创建外部访问集成，请将 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 SPECIFICATION eai_app_spec
        TYPE = EXTERNAL_ACCESS
        LABEL = 'Connection to an external API'
        DESCRIPTION = 'Access an API that exists outside Snowflake'
  HOST_PORTS = ('example.com')
Copy

此命令会创建名为 eai_app_spec 的应用程序规范。

在使用者账户中批准应用程序规范

提供商配置应用程序以创建网络规则、外部访问集成和应用程序规范后，使用者可以查看该应用程序规范，并在配置应用程序时根据需要对其进行批准或拒绝。有关更多信息，请参阅 使用应用程序规范批准与外部资源的连接。

语言: 中文