使用应用程序规范向使用者请求外部端点

本主题介绍提供商如何配置 Snowflake Native App 以使用应用程序规范。应用程序规范允许使用者批准或拒绝应用程序访问 Snowflake 外部服务的请求。

从 Snowflake Native App 访问外部服务

部分 Snowflake Native Apps 需要连接到 Snowflake 外部的资源。Snowflake 根据所需的外部连接类型提供不同的对象。

使用 自动授予权限功能 时，应用程序在运行安装脚本时已具备创建这些对象所需的权限。但是，由于这些对象允许连接到 Snowflake 外部，使用者在配置应用程序时必须批准这些连接。

应用程序规范允许提供商指定应用程序请求的连接信息。使用者安装应用程序时，可查看应用程序规范并根据需要批准或拒绝该请求。

应用程序规范定义

应用程序规范定义是外部访问集成或安全集成所需的配置详细信息列表。应用程序规范定义包含应用程序规范的元数据和属性的一个子集。

访问外部端点

为访问 Snowflake 外部的服务，Snowflake 提供以下对象：

网络规则:

指定外部网络标识符列表（例如主机名）。

外部访问集成:

允许在用户定义函数或存储过程中安全访问外部网络端点。外部访问集成使用网络规则限制对特定外部网络位置的访问。

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

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

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

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

  • PRIVATE_HOST_PORTS：允许与 Snowflake 外部资源建立私有连接的私有主机端口列表。

备注

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

访问第三方身份验证提供商

为了实现第三方身份验证服务，Snowflake 提供了安全集成。安全集成允许应用程序连接到第三方身份验证服务，例如 OAuth。安全集成允许应用程序使用安全的身份验证和访问控制。

备注

Snowflake Native Apps 仅支持 API_AUTHENTICATION 类型的安全集成。有关更多信息，请参阅 CREATE SECURITY INTEGRATION（外部 API 身份验证）。

安全集成的应用程序规范定义

对于安全集成，应用程序规范定义 包括连接第三方提供商所需的信息。对于 OAuth，应用程序规范定义包括：

安全集成类型

应用程序规范中定义的值

CLIENT_CREDENTIALS

  • :code:`OAUTH_TOKEN_ENDPOINT`（必填）

  • :code:`OAUTH_ALLOWED_SCOPES`（必填）

应用程序规范的序列号

序列号类似于应用程序规范的版本号。当提供商更改应用程序规范的定义时，序列号会自动递增。应用程序规范的定义包含配置详细信息和其他必需信息。不属于定义的字段（例如 description）不会触发序列号的更新。

通过序列号，提供商和使用者能够了解应用程序规范的当前状态以及已启用哪些外部端点。

应用程序规范工作流程

配置和使用应用程序规范的一般工作流程如下：

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

    备注

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

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

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

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

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

将 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

清单文件 privileges 部分中的此条目指定应用程序使用外部访问集成。为了让应用程序使用自动授予权限功能，清单文件还需要设置 manifest_version: 2。

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

外部访问集成是 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 的外部访问集成，允许应用程序访问外部资源或端点。它使用 setup.my_network_rule 网络规则。

向安装脚本添加安全集成

安全集成允许应用程序连接到第三方身份验证服务，例如 OAuth。要为应用程序创建安全集成，请使用 CREATE SECURITY INTEGRATION（外部 API 身份验证） 命令，如下例所示：

CREATE SECURITY INTEGRATION external_oauth_provider
  TYPE = API_AUTHENTICATION
  AUTH_TYPE = OAUTH2
  OAUTH_CLIENT_AUTH_METHOD = CLIENT_SECRET_POST
  OAUTH_CLIENT_ID = 'YOUR_CLIENT_ID'
  OAUTH_CLIENT_SECRET = 'YOUR_CLIENT_SECRET'
  OAUTH_GRANT = 'CLIENT_CREDENTIALS'
  OAUTH_TOKEN_ENDPOINT = 'https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/token'
  OAUTH_ALLOWED_SCOPES = ('https://graph.microsoft.com/.default')
  ENABLED = TRUE;
Copy

此示例展示如何创建安全集成，以通过客户端凭据的 OAuth 方式连接到 Microsoft Sharepoint。有关连接到 OAuth 提供商的其他受支持方法，请参阅 CREATE SECURITY INTEGRATION（外部 API 身份验证）。

在安装脚本中创建应用程序规范

要创建应用程序规范，提供商需要将 ALTER APPLICATION SET SPECIFICATIONS 命令添加到安装脚本中。

为外部访问集成创建应用程序规范

以下示例展示如何为外部访问集成创建应用程序规范：

ALTER APPLICATION SET SPECIFICATION eai_app_spec
        TYPE = EXTERNAL_ACCESS
        LABEL = 'Connection to an external API'
        DESCRIPTION = 'Access an API that exists outside Snowflake'
Copy

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

为安全集成创建应用程序规范

以下示例显示如何使用 CLIENT_CREDENTIALS OAuth 类型为安全集成创建应用程序规范：

ALTER APPLICATION SET SPECIFICATION oauth_app_spec
  TYPE = SECURITY_INTEGRATION
  LABEL = 'Connection to an external OAuth provider'
  DESCRIPTION = 'Integrates an external identity provider in the app'
  OAUTH_TYPE = 'CLIENT_CREDENTIALS'
  OAUTH_TOKEN_ENDPOINT = 'https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/token'
  OAUTH_ALLOWED_SCOPES = ('https://graph.microsoft.com/.default');
Copy

备注

创建应用程序规范时提供的值必须与在安装脚本中 创建安全集成 时使用的值完全相同。

有关使用其他 OAuth 类型的信息，请参阅 ALTER APPLICATION SET SPECIFICATIONS。

使用应用程序规范的最佳实践

自动授予权限功能 可确保应用程序具备创建外部访问集成所需的权限。但是，使用者可以选择拒绝启用连接外部端点的应用程序规范。开发应用程序时，提供商必须考虑应用程序规范可能未获批准的情况

例如，应用程序可能要求使用多个网络端口进行外部访问集成，但使用者可能只允许一个网络端口。应用程序应包含处理网络端口不可用时所发生错误的逻辑。此外，最佳实践是捕获所有可能发生的 HTTP 异常。

在应用程序规范中使用回调函数

在某些情况下，应用程序可能需要知道使用者批准或拒绝应用程序规范的时间。例如，应用程序可能需要等到应用程序规范获得批准后才能创建对象。

为了应对这种情况，Snowflake Native App Framework 提供了一种机制，允许提供商定义回调存储过程，并在使用者批准或拒绝应用程序规范时运行该过程。

提供商可以将存储过程添加到清单文件中，如以例所示：

lifecycle_callbacks:
  specification_action: callbacks.on_spec_update
Copy

此示例展示如何将名为 callbacks.on_spec_update 的存储过程添加到清单文件中。在安装脚本中，提供商可以像下例所示添加存储过程：

CREATE OR REPLACE PROCEDURE callbacks.on_spec_update (
  name STRING,
  status STRING,
  payload STRING)
  ...
Copy

此示例展示名为 callbacks.on_spec_update 的存储过程的签名。在该过程主体中，提供商需包含检查应用程序规范状态、创建对象以及按需执行操作所需的代码。

语言: 中文