连接配置

连接配置是紧跟在连接器配置之后的向导步骤。此步骤允许用户指定与源系统建立连接所需的属性，以便开始将数据引入到 Snowflake 中。名为 PUBLIC.SET_CONNECTION_CONFIGURATION(connection_configuration VARIANT) 的过程是负责此向导阶段的入口点。可通过 UI 或工作表调用此过程。使用自定义逻辑覆盖时，需要替换此过程，以指定自定义 Java 处理程序。

要调用此过程，用户需要已获得 ADMIN 应用程序角色。

连接配置步骤在内部由几个阶段组成。其中一些是完全可自定义的，默认情况下，不执行任何操作。这些阶段如下所示：

  1. 状态验证

  2. 输入验证

  3. 配置更新

  4. 内部回调

  5. 连接验证

  6. 状态更新

要求

在原生应用程序安装过程中，连接配置至少需要执行以下 SQL 文件：

此外，还有一个要求取决于 SDK 用户：

  • PUBLIC.TEST_CONNECTION() 过程的自定义实现

状态验证

要执行连接配置，连接器的内部状态需要为 CONFIGURING，配置状态为 CONFIGURED 或 CONNECTED。第一个配置状态将在连接器配置步骤之后直接设置，如果由于某种原因必须在后续步骤中更新连接配置，则会出现后一个配置状态。

不能通过使用 ConnectionConfigurationHandlerBuilder 或覆盖存储过程来覆盖此验证。但是，也可以实现一个自定义处理程序，它不会进行这种验证。

输入验证

输入必须是包含属性映射的 variant，但这可能不适用于所有情况。因此，SDK 提供了名为 PUBLIC.SET_CONNECTION_CONFIG_VALIDATE(config VARIANT) 的内部存储过程。默认情况下，此过程仅返回 'responseCode': 'OK'，覆盖此过程可以在验证期间更新提供的配置。此功能支持自定义逻辑。例如，将输入或转换修剪为大写/小写。要返回以任何方式转换的配置，响应需要在响应 Variant 中包含一个额外的 "config" 属性，此属性应将更新的配置作为 Variant 包含在内。通过覆盖 SQL 或使用 ConnectionConfigurationHandlerBuilder 并提供 ConnectionConfigurationInputValidator 接口的自定义实现来对该过程进行自定义。

以下是使用转换的自定义实现的有效响应：

{
    "response_code" : "OK",
    "config": {
        "key1": "value1",
        "key2": "value2"
    }
}
Copy

配置更新

成功通过验证后，配置将保存到内部 APP_CONFIG 表中。负责此阶段的服务将提供的 Variant 保存在 connection_configuration 键下。此配置在保存时不遵循任何其他要求，提供的属性集由用户决定。

内部回调

内部回调是另一个可自定义的步骤。默认情况下，它会调用 PUBLIC.SET_CONNECTION_CONFIGURATION_INTERNAL(connection_configuration VARIANT)，返回 'response_code': 'OK'。例如，它可用于通过授予其他过程外部访问集成来更改其他过程。可以通过 ConnectionConfigurationCallback 脚本或使用 ConnectionConfigurationHandlerBuilder 提供 接口的自定义实现来将其覆盖。

连接验证

此步骤会触发 PUBLIC.TEST_CONNECTION 过程。此过程尝试在源系统中查询数据。默认情况下，此过程未实现，需要由 SDK 用户提供。此外，可以向 ConnectionConfigurationHandlerBuilder 提供 ConnectionValidator 接口实现来自定义此阶段，在这种情况下，不需要实现存储过程。建议在此过程中仅执行最少的连接检查，以确保正确配置了 Snowflake 的外部访问功能，并且连接器具有使用这些功能所需的所有权限。

状态更新

成功完成上述所有阶段后，连接器的内部状态将更新为：

{
    "status": "CONFIGURING",
    "configurationStatus": "CONNECTED"
}
Copy

有关状态转换的整个图表，请参阅 连接器流。

查看配置

ADMIN 和 VIEWER 用户可以使用 PUBLIC.GET_CONNECTION_CONFIGURATION() 过程，该过程从内部表返回当前连接配置。

响应

成功响应

如果该过程成功完成，将从 TEST_CONNECTION 过程返回响应。我们建议使用以下格式：

{
  "response_code": "OK"
}
Copy

错误响应

如果出现错误，响应将遵循以下格式：

{
  "response_code": "<ERROR_CODE>",
  "message": "<error message>"
}
Copy

可能的错误代码包括：

  • INVALID_CONNECTOR_STATUS – 连接器状态无效。预期状态：[CONFIGURING]

  • INVALID_CONNECTOR_CONFIGURATION_STATUS – 连接器配置状态无效。预期状态：CONFIGURED

  • INTERNAL_ERROR – 内部出现问题，消息应具有描述性

  • PROCEDURE_NOT_FOUND – 调用的过程不存在。在这种情况下，主要是关于 TEST_CONNECTION 过程

  • UNKNOWN_SQL_ERROR – 如果调用内部过程时发生意外情况，则会出现此错误

  • INVALID_RESPONSE – 如果从内部过程接收的响应不包含 response_code 或错误响应不包含 message，但包含 response_code，则会发生此错误

  • UNKNOWN_ERROR – 这表示出现了意外错误 – 转发引发异常的消息

  • 从 TEST_CONNECTION() 过程接收的自定义错误代码 – 由连接器开发者定义

  • 从 SET_CONNECTION_CONFIGURATION_INTERNAL() 过程接收的自定义错误代码 – 由连接器开发者定义

语言: 中文