应用程序配置

本主题介绍 Snowflake Native App 如何使用应用程序配置对象来请求使用者的输入。

应用程序配置：概述

应用程序配置是一个键值对，它提供了 Snowflake Native App 和使用者之间的协调机制。当 Snowflake Native App 需要来自使用者的输入时，它会定义一个配置键以及解释配置目的的描述。然后，使用者提供该键的值。

应用程序配置支持以下类型：

APPLICATION_NAME

使用者提供使用者账户中已安装应用程序的名称。此类型用于 应用程序间通信。

STRING

使用者提供任意字符串值。此类型可用于各种用例，例如提供外部 URLs、账户标识符或其他应用程序特定设置。

应用程序配置工作流涉及以下步骤：

  1. 应用程序使用 ALTER APPLICATION SET CONFIGURATION DEFINITION 创建配置定义，指定所需信息的类型以及有权访问配置的应用程序角色。

  2. 使用者使用 SHOW CONFIGURATIONS 或 Snowsight 查看传入的配置请求。

  3. 使用者使用 ALTER APPLICATION SET CONFIGURATION VALUE 或 Snowsight 提供请求的值。

  4. 应用程序检索该值并使用它来执行进一步的操作，例如为连接创建应用程序规范。

Snowflake Native App Framework 提供回调，以便在设置或更改配置值时通知应用程序。有关更多信息，请参阅 配置回调。

术语

应用程序配置使用以下术语：

配置定义

应用程序创建的对象，用于向使用者请求特定信息。配置定义指定请求的信息类型、标签、描述以及有权访问配置的应用程序角色。

配置值

使用者为响应配置定义请求而提供的值。

使用配置

本节介绍如何创建、显示和管理配置。

创建配置请求

为了向使用者请求配置值，应用程序会在安装脚本中或在运行时创建配置定义。配置定义指定预期值的类型、向使用者显示的标签和描述，以及可以查看配置和编辑值的应用程序角色。

以下示例演示如何创建类型 STRING 的配置定义，该配置定义会向使用者请求公司 URL：

ALTER APPLICATION SET CONFIGURATION DEFINITION company_url
  TYPE = STRING
  LABEL = 'Company URL'
  DESCRIPTION = 'Provide the company website URL'
  APPLICATION_ROLES = (app_user)
  SENSITIVE = FALSE;

以下属性控制配置的显示和管理方式：

  • LABEL：选择使用 时默认使用的角色和仓库。在 Snowsight 中显示给使用者的名称。

  • DESCRIPTION：选择使用 时默认使用的角色和仓库。帮助使用者理解配置用途的描述。

  • APPLICATION_ROLES：选择使用 时默认使用的角色和仓库。可以查看和设置此配置之值的应用程序角色。被授予指定应用程序角色之一的使用者角色可以查看配置并编辑其值。

  • SENSITIVE：选择使用 时默认使用的角色和仓库。指定是否应将配置值视为敏感值。当设置为 TRUE 时，SHOW CONFIGURATIONS 的输出中不显示该值。有关更多信息，请参阅 敏感配置。

查看配置请求

应用程序创建配置请求后，使用者可以使用 SQL 或 Snowsight 查看待处理的请求：

要使用 SQL 查看配置请求和配置定义的详细信息，请使用 SHOW CONFIGURATIONS 和 DESCRIBE CONFIGURATION 命令：

SHOW CONFIGURATIONS IN APPLICATION example_app;

DESCRIBE CONFIGURATION company_url IN APPLICATION example_app;

提供配置值

应用程序创建配置请求后，使用者可以使用 SQL 或 Snowsight 提供请求值。

要使用 SQL 为配置提供值，请使用 ALTER APPLICATION SET CONFIGURATION VALUE 命令：

ALTER APPLICATION <app> SET CONFIGURATION <config> VALUE = '<value>';

更新配置的值

您可以使用 SQL 或 Snowsight 更新配置的值。

要更新配置值，请使用与设置初始值时相同的语法：

ALTER APPLICATION <app> SET CONFIGURATION <config> VALUE = '<value>';

取消设置配置的值

您可以使用 SQL 或 Snowsight 取消设置配置的值。

要使用 SQL 取消设置配置的值，请使用 ALTER APPLICATION UNSET CONFIGURATION 命令：

ALTER APPLICATION <app> UNSET CONFIGURATION <config>;

检索配置的值

除了 SHOW CONFIGURATIONS 或 DESCRIBE CONFIGURATION ，应用程序还可以检索使用者使用 get_configuration_value 函数提供的配置的值。以下示例展示如何检索配置的值：

SELECT SYS_CONTEXT('SNOWFLAKE$APPLICATION', 'GET_CONFIGURATION_VALUE' , '<config_name>')

备注

只有应用程序可以从系统上下文中检索配置值。要以使用者身份查看配置值，您可以使用 SQL 或 Snowsight 查看配置详细信息。有关更多信息，请参阅 查看配置请求。

敏感配置

当应用程序创建配置时，可以通过设置 SENSITIVE = TRUE 将配置标记为敏感。当应用程序需要向使用者请求个人访问令牌或 API 键等敏感信息时，这一功能非常有用。

备注

SENSITIVE 属性仅支持用于类型 STRING 的配置。

当配置敏感时，使用者提供的值将受到保护，不会受到其他使用者用户和角色的影响。Snowflake Native App Framework 应用的保护措施与在 Snowflake 中的 SECRET 对象 类似：

  • 使用者设置值后，ALTER APPLICATION SET CONFIGURATION VALUE 命令的查询历史记录会对该值进行脱敏，使其不会暴露给其他使用者角色或用户。

  • 该值不会显示在 SHOW CONFIGURATIONS、DESCRIBE CONFIGURATION、INFORMATION_SCHEMA 视图，或 ACCOUNT_USAGE 视图的输出中。

创建配置的应用程序始终可以检索使用者提供的值，即使配置是敏感的也一样。这是设计使然，因为应用程序配置的目的是让使用者为应用程序提供值。

更改 SENSITIVE 属性

配置已设置值（即配置不处于 PENDING 状态）时，应用程序无法更改 SENSITIVE 属性。此限制可防止使用者的值意外暴露。如果应用程序在已设置了值时尝试更改 SENSITIVE 属性，命令完成时不会出现错误，但也不会生效。

要更改 SENSITIVE 属性，使用者必须首先使用 ALTER APPLICATION UNSET CONFIGURATION 取消设置配置值：

SQL 参考

以下 SQL 命令、函数和视图用于管理应用程序配置。

SQL 命令

SQL 函数

Information Schema 视图和函数

  • APPLICATION_CONFIGURATIONS 视图：选择使用 时默认使用的角色和仓库。此 Information Schema 视图为当前在指定数据库或 INFORMATION_SCHEMA 所在的当前数据库中定义的每个应用程序配置显示一行。

  • APPLICATION_CONFIGURATION_VALUE_HISTORY：选择使用 时默认使用的角色和仓库。返回配置的值历史记录。

Account Usage 架构视图

回调

当配置值更改时，Snowflake Native App Framework 可以调用在应用程序中的 清单 文件。这些回调允许应用程序验证、准备或响应配置更改。例如，在配置应用程序间通信时，一个常见的用例是使用 before_configuration_change 回调，以在使用者提供服务器应用程序名称时自动创建连接规范。这避免了要求使用者在设置配置值后执行额外的手动步骤。有关应用程序间通信的更多信息，请参阅 应用程序间通信。

以下配置回调可用：

validate_configuration_change

一个同步回调，作为 ALTER APPLICATION SET CONFIGURATION VALUE 命令的一部分被调用。允许应用程序对提供的值执行自定义验证。如果回调返回错误，则命令失败，并且不会设置新值。

before_configuration_change

一个同步回调，作为 ALTER APPLICATION SET CONFIGURATION VALUE 和 ALTER APPLICATION UNSET CONFIGURATION 命令的一部分被调用。允许应用程序在保存配置值之前根据配置值执行操作。

after_configuration_change

一个异步回调，在 ALTER APPLICATION SET CONFIGURATION VALUE 或 ALTER APPLICATION UNSET CONFIGURATION 命令完成后被调用。允许应用程序对变更做出反应，例如出于通知或跟踪目的。

有关完整的回调签名和返回值，请参阅 回调。