示例 – 为具有容器的应用程序中的服务配置外部访问权限¶

向清单文件添加外部访问集成引用¶

以下示例展示了提供商如何在清单文件中定义外部访问集成：

references:
  ...
  - my_external_access:
      label: "Default External Access Integration"
      description: "This EAI is required to access xyz.com"
      privileges:
        - USAGE
      object_type: EXTERNAL ACCESS INTEGRATION
      required_at_setup: true
      register_callback: config.REGISTER_EAI_CALLBACK
      configuration_callback: config.get_config_for_ref

此示例在 references 下指定了一些属性，其中包括：

• my_external_access：指定外部引用的名称。

  • privileges：列举外部访问集成所需权限。本例中需要 USAGE 权限。

  • object_type: EXTERNAL ACCESS INTEGRATION：表示对于外部访问集成的引用。

  • required_at_setup：设置为 true 时，表示使用者授予对于对象的访问权限，之后应用程序才能创建对象。

  • register_callback：指定用于向应用程序注册引用的回调存储过程。

  • configuration_callback：指定密钥的配置回调函数。有关更多信息，请参阅 向安装脚本中添加 configuration_callback 函数。

向清单文件添加密钥引用。¶

以下示例展示了提供商如何在清单文件中定义密钥：

references:
 ...
 - consumer_secret:
     label: "Consumer secret"
     description: "Needed to authenticate with an external endpoint"
     privileges:
       - READ
     object_type: SECRET
     register_callback: config.register_my_secret
     configuration_callback: config.get_config_for_ref

此示例在 references 下指定了一些属性，其中包括：

• consumer_secret：指定引用的名称。

  • privileges：列出密钥所需权限。这个例子中指定了 READ 权限。

  • object_type: SECRET：表示该引用为密钥。

  • register_callback：指定用于向应用程序注册引用的回调存储过程。

  • configuration_callback：指定密钥的配置回调函数。有关更多信息，请参阅 向安装脚本中添加 configuration_callback 函数。

向安装脚本中添加 configuration_callback 函数¶

在为密钥和外部访问集成添加引用之后，必须向安装脚本中添加 configuration_callback 函数。要创建外部访问集成或密钥，应用程序必须能确定主机端口、密钥类型、OAuth 的授权和令牌端点等的值。configuration_callback 函数将此信息从使用者账户提供给应用程序。

CREATE OR REPLACE PROCEDURE CONFIG.GET_CONFIG_FOR_REFERENCE(ref_name STRING)
RETURNS STRING
LANGUAGE SQL
AS
$$
BEGIN
 CASE (UPPER(ref_name))
   WHEN 'my_external_access' THEN
     RETURN '{
       "type": "CONFIGURATION",
       "payload":{
         "host_ports":["google.com"],
         "allowed_secrets" : "LIST",
         "secret_references":["CONSUMER_SECRET"]}}';
   WHEN 'consumer_secret' THEN
     RETURN '{
       "type": "CONFIGURATION",
       "payload":{
         "type" : "OAUTH2",
         "security_integration": {
           "oauth_scopes": ["https://www.googleapis.com/auth/analytics.readonly"],
           "oauth_token_endpoint": "https://oauth2.googleapis.com/token",
           "oauth_authorization_endpoint":
               "https://accounts.google.com/o/oauth2/auth"}}}';
  END CASE;
  RETURN '';
END;
$$;

Snowsight 运行此回调过程，以填充配置对话框，该对话框提示用户配置所需对象。

此过程需要授予应用程序角色才能执行，如下例所示：

GRANT USAGE ON PROCEDURE CONFIG.GET_CONFIG_FOR_REFERENCE(STRING)
  TO APPLICATION ROLE app_admin;

在具有容器的应用程序中使用外部访问集成的最佳实践¶

在具有容器的应用程序中使用外部访问集成时，Snowflake 建议遵循以下最佳实践：

• 必须绑定对于在 CREATE SERVICE 或 ALTER SERVICE 命令中指定的任何外部访问集成引用，然后才能在安装脚本中运行命令。如果引用未绑定，这些命令将会失败。

• 对于在服务规范中指定的任何对密钥的引用，均必须在运行安装脚本中的 CREATE SERVICE 或 ALTER SERVICE 命令之前予以绑定。如果引用未绑定，这些命令将会失败。

• 如果在 configuration_callback 函数中返回类型为 ERROR 的有效负载，提供商应返回一条包含有用信息的错误消息，以帮助使用者理解错误的原因及其解决方式。例如：

  • 如果应用程序中出现错误

  • 如果尚不需要引用

  • 如果尚未准备好允许引用。

• 如果 configuration_callback 函数包含引用，并且 required_at_setup 属性设置为 TRUE，则在安装之时，configuration_callback 函数必须成功。在这种情况下，configuration_callback 函数不能依赖于使用者提供的信息。

• 在使用对外部访问集成服务的引用时，如果应用程序需要使用者提供的密钥，请考虑使用 ALLOWED_AUTHENTICATION_SECRETS = ALL 创建该服务。这简化了在外部访问集成中处理密钥的过程。

• 如果一个应用只需要访问特定端点，并且不需要任何密钥，请使用 ALLOWED_AUTHENTICATION_SECRETS = NONE。默认值为 NONE。有关更多信息，请参阅 CREATE EXTERNAL ACCESS INTEGRATION。

• 如果应用程序需要更新引用，首先解除绑定引用，然后提示使用者创建并将新对象绑定到引用。使用者可以选择编辑和绑定现有对象。请参阅 CREATE EXTERNAL ACCESS INTEGRATION。