回调

本主题介绍可用于 Snowflake Native Apps 的回调函数。

Snowflake Native App Framework 提供回调以帮助管理应用程序生命周期。您可以使用这些回调来增强应用程序的功能和工作流。

要使用回调，请将其添加到清单文件的 lifecycle_callbacks 不分，如以下示例所示：

lifecycle_callbacks:
    before_configuration_change: app_schema.before_config_change_callback

回调类型

Snowflake Native App Framework 提供同步和异步回调。

同步回调

调用同步回调是触发 SQL 命令的一部分。同步回调会阻止调用 SQL 命令。如果回调返回错误，则该命令将返回错误，并且将在作为命令的 SQL 错误消息中返回消息。

同步回调在仓库中运行，因此调用过程必须设置会话仓库。

异步回调

异步回调在调用 SQL 命令后完成后在背景中运行。异步回调不会阻止调用 SQL 命令，并且调用命令不会返回异步回调中的错误。

为确保异步回调具有最新信息，回调签名不提供状态或状态信息。相反，回调应使用适当的 SQL 命令检索最新信息，例如 SHOW CONFIGURATIONS 或 SHOW SPECIFICATIONS。有关更多信息，请参阅每个异步回调的描述。

忽略异步回调的返回值。

小心

不保证异步回调的执行顺序。您的应用程序不应依赖异步回调的顺序来执行其操作。

权限

不需要将本主题中列出的回调过程授予任何应用程序角色。该过程可以在应用程序内部，并且不需要由使用者运行。Snowflake Native App Framework 触发回调。

规范与连接回调

after_specification_change 和 after_server_connection_change 都会在批准或拒绝规范时运行。两个回调之间的区别如下：

  • after_specification_change 是应用程序规范框架的一部分。仅当使用者批准或拒绝规范请求时才会触发。

  • after_server_connection_change 是应用程序间通信框架的一部分。它由任何直接或间接影响应用程序规范连接状态的操作触发，包括以下操作：

    • 批准规范

    • 删除已批准的规范

    • 删除已批准的规范

    • 删除服务器应用程序

当应用程序需要响应连接本身的变化时，例如连接的建立、丢失或服务器应用程序的删除，使用 after_server_connection_change。此回调提供更好的连接跟踪，因为它涵盖的事件范围比单独批准的规范更广。

当应用程序只需要响应批准或拒绝规范请求时，或者处理除 CONNECTION 之外的应用程序规范类型时，使用 after_specification_change。

回调引用

为 Snowflake Native Apps 提供了以下类别的回调：

配置回调

当 配置 发生更改时，会触发这些回调。

validate_configuration_change

此回调是同步回调。

此回调作为 ALTER APPLICATION SET CONFIGURATION VALUE 命令的一部分进行调用。此回调允许应用程序对服务器应用程序提供的值执行其他自定义验证。如果回调失败（例如出现语法错误），或者回调返回并出错，则 set 命令失败，并且不会设置新值。

签名
validate_configuration_change(configuration_name, configuration_value)
参数

  • configuration_name：选择使用 时默认使用的角色和仓库。配置对象的名称。

  • configuration_value：选择使用 时默认使用的角色和仓库。服务器应用程序提供的值。

返回值

回调必须返回 JSON 格式的字符串来指示验证成功或错误。

{
  "type": "SUCCESS | ERROR",
  "payload":{
      "error_message": "Error message indicating the validation failure"
  }
}

如果函数返回 type 的 ERROR，则错误消息作为 SET 命令的 SQL 错误消息的一部分返回。如果函数返回 type 的 SUCCESS，错误消息将被忽略。

before_configuration_change

此回调是同步回调。此回调作为 ALTER APPLICATION SET CONFIGURATION VALUE 和 ALTER APPLICATION UNSET CONFIGURATION 命令的一部分进行调用。此回调允许应用程序根据设置的配置值执行进一步的操作。对于 ALTER APPLICATION UNSET CONFIGURATION 命令，传递到回调中的值为 null。

签名
before_configuration_change(configuration_name, configuration_value)
参数

  • configuration_name：选择使用 时默认使用的角色和仓库。配置对象的名称。

  • configuration_value：选择使用 时默认使用的角色和仓库。服务器应用程序提供的值。

返回值

忽略回调的返回值。

after_configuration_change

此回调是异步回调。此回调在 ALTER APPLICATION SET CONFIGURATION VALUE 和 ALTER APPLICATION UNSET CONFIGURATION 命令完成后调用。此回调允许在服务器应用程序提供值时通知客户端应用程序。

签名
after_configuration_change(configuration_name)
参数

  • configuration_name：选择使用 时默认使用的角色和仓库。配置对象的名称。

检索最新状态

在回调中，以下代码片段可用于检索配置的当前状态和值：

session.sql(f"""
  SHOW CONFIGURATIONS ->>
      SELECT "status", "value"
      FROM $1
      WHERE "name" = '{configuration_name}';
  """);

连接回调

连接状态发生变化时会触发这些回调。

after_server_connection_change

此回调是异步回调。此回调由任何直接或间接影响应用程序规范连接状态的操作触发，包括以下操作：

  • 批准规范

  • 删除已批准的规范

  • 删除已批准的规范

  • 删除服务器应用程序

签名
after_server_connection_change(server_name)
参数

  • server_name：选择使用 时默认使用的角色和仓库。连接已更改的服务器应用程序的名称。

检索最新状态

在回调中，以下代码片段检索服务器应用程序的当前连接状态：

session.sql(f"""
  SHOW SPECIFICATIONS ->>
  SELECT "status"
  FROM $1
  WHERE PARSE_JSON("definition"):"SERVER_APPLICATION"::STRING = '{server_name}';
  """);

after_client_connection_change

此回调是异步回调。此回调由任何直接或间接影响应用程序规范连接状态的操作触发，包括以下操作：

  • 批准规范

  • 删除已批准的规范

  • 删除已批准的规范

  • 删除客户端应用程序

签名
after_client_connection_change(client_name)
参数

  • client_name：选择使用 时默认使用的角色和仓库。连接已更改的客户端应用程序的名称。

检索最新状态

在回调中，以下代码片段检索已授予客户端应用程序的角色（如果有）：

session.sql(f"""
  SHOW GRANTS TO APPLICATION {client_name} ->>
  SELECT "name"
  FROM $1
  WHERE "granted_on" = 'APPLICATION_ROLE'
      AND STARTSWITH("name", CURRENT_DATABASE())
  """);

after_server_version_change

此回调是异步回调。服务器应用程序的版本或补丁号更改后会调用此回调。这允许客户端应用程序对升级或降级做出反应。

签名
after_server_version_change(server_name)
参数

  • server_name：选择使用 时默认使用的角色和仓库。版本已更改的服务器应用程序的名称。

检索最新状态

在回调中，以下代码片段可用于检索服务器应用程序的当前版本：

session.sql(f"""
  SHOW APPLICATIONS ->>
  SELECT "version", "patch"
  FROM $1
  WHERE "name" = {server_name}
  """);

规范回调

当任何类型的规范状态发生变化时，都会触发回调

  • after_specification_change

after_specification_change

此回调是异步回调。此回调在 ALTER APPLICATION APPROVE SPECIFICATION 或 ALTER APPLICATION DECLINE SPECIFICATION 命令完成后调用。此回调允许应用程序在其规范状态发生更改时收到通知。

此回调替换了 specification_action 回调的功能。您只能指定清单文件中的 after_specification_change 或 specification_action 之一。有关 specification_action 回调的信息，请参阅 在应用程序规范中使用回调函数。

签名
after_specification_change(spec_name)
参数

  • spec_name：选择使用 时默认使用的角色和仓库。已批准或拒绝的应用程序规范的名称。

检索最新状态

在回调中，以下代码片段可用于检索规范的当前状态：

session.sql(f"""
  SHOW SPECIFICATIONS ->>
      SELECT "status"
      FROM $1
      WHERE "name" = '{spec_name}';
  """);

回调历史记录

使用以下 SQL 函数和 Account Usage 视图来监控您的 Snowflake Native Apps 的回调调用情况：

  • :doc:`/sql-reference/functions/application_callback_history`（Information Schema 表函数）：返回当前账户中应用程序的回调调用历史记录。使用此表函数查询特定应用程序或回调的回调历史记录。

  • :doc:`/sql-reference/account-usage/application_callback_history`（Account Usage 视图）：提供账户中应用程序的回调调用历史记录。使用此视图可分析账户中所有应用程序的回调活动。