Overview of app specifications¶

Types of controlled access for Snowflake Native Apps¶

Snowflake Native Apps often need to interact with resources beyond the consumer's Snowflake account. These interactions can include connecting to external services, authenticating with third-party providers, or sharing data with other Snowflake accounts.

To access external services and share data, Snowflake provides the following objects:

外部访问集成:

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

Security integrations:

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

Shares and listings:

Allow apps to share data back to providers or third-party Snowflake accounts. Shares contain database objects to be shared, and listings provide the mechanism to share data across accounts and regions.

When using automated granting of privileges, an app has the required privileges to create these objects when running the setup script. However, because these objects enable external connections or data sharing, consumers must approve these operations when configuring the app.

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

• Consumers do not have to manually create integrations, shares, or listings required by the app and approve access to them using references.

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

• Consumers have clear visibility and control over external connections and data sharing requests.

Use app specifications for consumer approval¶

App specifications allow you to specify what controlled access the app requires. After the consumer installs the app, they review the app specification and approve or decline each request as necessary. This includes requests for external connections, authentication integrations, and data sharing permissions.

• For information about using app specifications to request access to external endpoint access, see 使用应用程序规范来请求外部访问集成 (EAIs).

• For information about using app specifications to request access to OAuth integrations, see 请求应用程序规范的安全集成.

• For information about using app specifications to share data through listings, see 请求符合应用程序规范的数据共享.

应用程序规范定义¶

An app specification definition contains the properties that are required for the app to perform controlled operations such as external connections or data sharing. These properties are displayed to the consumer for approval. The app specification definition contains a subset of the metadata and properties specific to each type of operation: external access integration, security integration, or listing.

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

For information about the app specification definition for external access integrations, see App specification definition for an EAI.

For information about the app specification definition for listings, see 为列表创建应用程序规范.

Sequence numbers of an app specification¶

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

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

Best practices when using app specifications¶

Automated granting of privileges ensures that the app has the required privileges to create objects like external access integrations, security integrations, or listings. However, consumers can choose to decline the app specification that enables external connections or data sharing. When developing an app, you must account for situations where app specifications might not be approved.

Consider the following scenarios:

• An app might request multiple network ports for an external access integration, but the consumer might allow only one. The app should include logic to handle errors that occur if a network port is not available.

• A data sharing request might be declined or only partially approved for some target accounts but not others. The app should gracefully handle these cases.

• Authentication integrations might be rejected, requiring the app to use alternative methods.

As a best practice, always include proper error handling and provide clear feedback to consumers about which features require approved specifications to function.

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

In some contexts, an app might need to know when the consumer has approved or declined an app specification. For example:

• The app might need to wait until an external access specification is approved before making API calls.

• Data population might need to start only after a listing specification is approved.

• OAuth flows might need to be initialized after security integration approval.

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

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

lifecycle_callbacks:
  specification_action: callbacks.on_spec_update

This example shows how to add a stored procedure named callbacks.on_spec_update to the manifest file. In the setup script, providers can add a stored procedure as shown in the following example:

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

This example shows the signature of a stored procedure called callbacks.on_spec_update. You include the code in the body of this procedure to check the status of the app specification, create objects, and perform actions as required.