Overview of app specifications¶

从 Snowflake Native App 访问外部服务¶

Some Snowflake Native Apps need to connect to resources that exist outside Snowflake. To handle connections to these resources, Snowflake provides different objects for different types of connections.

To access external services, Snowflake provides the following objects:

外部访问集成:

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

Security integrations:

允许安全访问第三方身份验证提供商，例如 OAuth.安全集成提供安全的身份验证和访问控制。

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

通过应用程序规范自动授予权限具有以下优势：

• 使用者不必手动创建应用程序所需的外部访问集成或安全集成，并使用引用审批对它们的访问。

• 提供商不必编写代码来检查安装或升级期间是否存在所需的权限和对象。

Use app specifications to allow consumers to approve external connections¶

App specifications allow a provider to specify what connection information the app requests. After the consumer installs the app, they review the app specification and approve or decline it as necessary.

有关使用应用程序规范请求访问外部端点的信息，请参阅 使用应用程序规范来请求外部访问集成 (EAIs)。有关使用应用程序规范请求 OAuth 集成访问权限的信息，请参阅 请求应用程序规范的安全集成. 使用应用程序规范来请求外部访问集成 (EAIs)。

应用程序规范定义¶

An app specification definition contains the properties that are required for the app to configure connections to resources outside of Snowflake. These properties are displayed to the consumer for approval. an external access integration or security integration. The app specification definition contains a subset of the metadata and properties of an external access integration or security integration.

有关安全集成的应用程序规范定义的信息，请参阅 安全集成的应用程序规范定义。

For information about the app specification definition for external access integrations, see 外部访问集成的应用程序规范定义.

应用程序规范的序列号¶

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

序列号允许提供商和使用者识别应用程序规范的不同版本。例如，如果提供商在应用程序规范定义中添加了新的配置详细信息，则序列号将递增。当使用者查看应用程序规范时，他们可以看到序列号已更改，并且可以查看更新的应用程序规范。

Best practices when using app specifications¶

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

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

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

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

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

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

lifecycle_callbacks:
  specification_action: callbacks.on_spec_update

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

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

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