教程：Snowflake Native SDK for Connectors 示例 Java 连接器¶

先决条件¶

在开始之前，请确保您满足以下要求：

• Java 基础知识

• Snowflake Native Apps 基础知识

• Streamlit UI (https://docs.streamlit.io/) 基础知识

• 访问具有 ACCOUNTADMIN 角色的 Snowflake 账户

• GitHub 账户，可以创建 GitHub 应用程序 (https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps)

• 构建项目和运行部署脚本的 MacOS 或 Linux 计算机

Java 安装¶

Snowflake Native SDK for Connectors 需要 Java LTS（长期支持）版本 11 或更高版本。如果计算机上未安装所需的最低 Java 版本，则必须安装 Oracle Java 或 OpenJDK。

存储库克隆¶

将 connectors-native-sdk (https://github.com/snowflakedb/connectors-native-sdk) 存储库克隆到计算机。

Snowflake CLI 配置¶

构建、部署和安装连接器需要 Snowflake CLI 工具。如果计算机上没有 Snowflake CLI – 根据`此处 <https://docs.snowflake.cn/en/developer-guide/snowflake-cli/installation/installation>`_ 的说明进行安装。

安装该工具后 – 您需要在 配置文件 中配置与 Snowflake 的连接。

如果您没有配置任何连接 – 请创建一个名为 native_sdk_connection 的新连接。您可以在 deployment/snowflake.toml 文件中找到示例连接。

如果您已经配置了连接，并希望将其与连接器一起使用 – 在本教程中使用此连接时，请使用其名称而不是 native_sdk_connection。

连接器原生 SDK Java¶

connectors-native-sdk-java 目录包含所有 Snowflake Native SDK for Connectors Java 代码，并针对 SDK 组件进行了单元测试和集成测试。由于 Snowflake 内部原生应用程序的性质，这不仅意味着 Java 代码，还有 SQL 代码，这是创建正常工作的应用程序所必需的。数据库对象的定义可以在 src/main/resources 目录中找到。这些文件在创建应用程序时用于自定义应用程序内部可用的对象。在示例连接器中，我们使用 all.sql 文件，该文件为所有可用功能创建对象。此文件将在应用程序实例的安装过程中执行。

连接器原生 SDK 测试 Java¶

connectors-native-sdk-test-java 目录包含单元测试中使用的 helper 库的源代码，例如用于模拟特定组件的对象、自定义断言等。这些文件不是连接器应用程序的一部分。

Java GitHub 连接器示例¶

实际示例连接器位于 examples/connectors-native-sdk-example-java-github-connector 目录内部。app/ 目录包含运行 Native App 所需的所有文件：

• app/streamlit/ 目录包含运行连接器的 Streamlit UI 所必需的源文件。

• setup.sql 文件在应用程序安装期间运行，负责创建必要的数据库对象。此文件将执行前面提到的 all.sql 文件，以及一些自定义 sql 代码。

• manifest.yml 文件是 Native App 的清单。需要先创建一个应用程序包，然后再创建应用程序实例本身。此文件指定应用程序属性以及应用程序所需的权限。

此外，examples/connectors-native-sdk-example-java-github-connector 目录还包含 src/ 子目录，其中包含自定义连接器逻辑，例如实施所需类和自定义默认 SDK 组件。

连接器原生 SDK 模板¶

模板 Gradle Java 项目，使用 Snowflake Native SDK for Connectors 作为依赖项来帮助您快速构建新连接器。您可以在 教程：Snowflake Native SDK for Connectors Java 连接器模板 阅读更多相关内容。

构建连接器¶

构建使用 Snowflake Native SDK for Connectors 创建的连接器与构建典型的 Java 应用程序略有不同。除了使用源构建 .jar 存档之外，还必须进行一些其他操作。构建应用程序包括以下步骤：

1. 将自定义内部组件复制到构建目录

2. 将 SDK 组件复制到构建目录

部署连接器¶

要部署 Native App，需要在 Snowflake 内创建应用程序包。之后，需要将 sf_build 目录中的所有文件上传到 Snowflake。

请注意 – 出于开发目的，可以选择版本创建，可以直接从暂存文件创建应用程序实例。此方法允许您查看大多数连接器文件中的变化，无需重新创建版本和应用程序实例。

将执行以下操作：

1. 创建新的应用程序包（如果不存在）

2. 在包中创建架构和文件暂存区

3. 将文件从 sf_build 目录上传到暂存区（此步骤可能需要一些时间）

要部署连接器，请执行命令 snow app deploy --connection=native_sdk_connection。

有关 snow app deploy 命令的更多信息，请参阅 snow app deploy。

创建的应用程序包现在将在 App packages 选项卡、Data products 类别、账户的 Snowflake UI 中可见。

安装连接器¶

安装应用程序是该过程的最后一步。该步骤会使用之前创建的应用程序包创建应用程序。

要安装连接器，请执行命令：snow app run --connection=native_sdk_connection。

有关 snow app run 命令的更多信息，请参阅 Snow 应用程序运行。

安装的应用程序现在将在 Installed apps 选项卡、Data products 类别、账户的 Snowflake UI 中可见。

更新连接器文件¶

如果在任何时候希望修改任何连接器文件，您可以轻松地将修改的文件上传到应用程包暂存区。上传命令取决于更新了哪些文件。

在运行任何更新命令之前，您必须通过运行以下命令将连接器的新文件复制到 sf_build 目录中：./gradlew copyInternalComponents

权限¶

应用程序需要两个账户级权限才能操作：CREATE DATABASE 和 EXECUTE TASK。

需要第一个特权来为引入的数据创建目标数据库。此数据库应在应用程序外创建，这样，如果卸载应用程序，引入的数据可以保持不变。但是，本示例不支持此功能，始终会创建新的数据库。

需要第二个权限来计划周期性任务，这些任务将从 GitHub 提取数据并将其保存在目标数据库中。

可以使用安全选项卡或通过在连接器配置屏幕中按下 Grant privileges 按钮授予这些权限。后者将使屏幕上出现弹出窗口。

仓库引用¶

连接器需要仓库来运行和计划引入任务。应用程序将通过 引用 使用仓库。仓库引用在 manifest.yml 文件中定义：

references:
  - WAREHOUSE_REFERENCE:
      label: "Warehouse used for ingestion"
      description: "Warehouse which will be used to schedule ingestion tasks"
      privileges: [USAGE]
      object_type: WAREHOUSE
      register_callback: PUBLIC.REGISTER_REFERENCE

引用可以使用安全选项卡设置，与上述权限相同，也可以通过按 Choose warehouse 按钮设置。

目标数据库和架构¶

如前所述，连接器需要一个数据库来存储引入的数据。在后续的一个步骤中，将使用用户指定的架构创建此数据库。数据库的名称由用户决定，只要提供的数据库不存在。

完成的连接器配置屏幕应类似于：

权限 SDK 设置¶

OAuth2 身份验证要求在用户账户中创建安全集成、密钥和外部访问集成。我们的连接器使用 Native Apps 权限 SDK 请求创建这些对象。

连接器所需的外部访问集成和密钥的引用在 manifest.yml 文件中定义：

references:
  - GITHUB_EAI_REFERENCE:
      label: "GitHub API access integration"
      description: "External access integration that will enable connection to the GitHub API using OAuth2"
      privileges: [USAGE]
      object_type: "EXTERNAL ACCESS INTEGRATION"
      register_callback: PUBLIC.REGISTER_REFERENCE
      configuration_callback: PUBLIC.GET_REFERENCE_CONFIG
  - GITHUB_SECRET_REFERENCE:
      label: "GitHub API secret"
      description: "Secret that will enable connection to the GitHub API using OAuth2"
      privileges: [READ]
      object_type: SECRET
      register_callback: PUBLIC.REGISTER_REFERENCE
      configuration_callback: PUBLIC.GET_REFERENCE_CONFIG

此外，需要在 setup.sql 文件中添加一个特殊程序。在 configuration_callback 属性中引用了上述每个引用：

CREATE OR REPLACE PROCEDURE PUBLIC.GET_REFERENCE_CONFIG(ref_name STRING)
    RETURNS STRING
    LANGUAGE SQL
    AS
        BEGIN
            CASE (ref_name)
                WHEN 'GITHUB_EAI_REFERENCE' THEN
                    RETURN OBJECT_CONSTRUCT(
                        'type', 'CONFIGURATION',
                        'payload', OBJECT_CONSTRUCT(
                            'host_ports', ARRAY_CONSTRUCT('api.github.com'),
                            'allowed_secrets', 'LIST',
                            'secret_references', ARRAY_CONSTRUCT('GITHUB_SECRET_REFERENCE')
                        )
                    )::STRING;
                WHEN 'GITHUB_SECRET_REFERENCE' THEN
                    RETURN OBJECT_CONSTRUCT(
                        'type', 'CONFIGURATION',
                        'payload', OBJECT_CONSTRUCT(
                            'type', 'OAUTH2',
                            'security_integration', OBJECT_CONSTRUCT(
                                'oauth_scopes', ARRAY_CONSTRUCT('repo'),
                                'oauth_token_endpoint', 'https://github.com/login/oauth/access_token',
                                'oauth_authorization_endpoint', 'https://github.com/login/oauth/authorize'
                            )
                        )
                    )::STRING;
                ELSE
                    RETURN '';
            END CASE;
        END;

对于外部访问集成引用，该过程提供：

• host_ports – 外部数据源的主机名，将在引入期间访问

• secret_references – OAuth 密钥引用名称数组

• allowed_secrets – LIST，告知权限 SDK 使用 secret_references 字段中指定的密钥

对于密钥参考，该过程提供：

• type – 使用我们的密钥时，为 OAUTH2

• security_integration – 创建的安全集成的属性：

  • oauth_scopes – 连接器请求的 OAuth 作用域列表（如果使用 GitHub 应用程序 – 此字段为可选字段）

  • oauth_token_endpoint – 将从中获取刷新和访问令牌的端点

  • oauth_authorization_endpoint – 将向其发送授权请求的端点

GitHub 应用程序设置¶

下一步是在用户账户中设置 GitHub 应用程序。此应用程序将用于授予对该账户的有限访问权限，以便引入数据。

第一步是按下连接器 UI 中的 Request access 按钮。

第一个屏幕允许您查看允许外部连接的端点。

按下 Next 后，您将看到第二个屏幕。选择 OAuth2 以创建新的集成和密钥，然后复制提供的重定向 URL，其中将包含您的组织名称和账户区域。

接下来，进入 GitHub 账户设置页面，然后进入 开发者设置 > GitHub Apps，并按下 New GitHub App 按钮：

1. 输入应用程序的名称和主页 URL

2. 将您复制的重定向 URL 粘贴到 Callback URL 字段

3. 确保选中 Expire user authorization tokens 选项

4. 确保未选中 Request user authorization (OAuth) during installation

5. 如果不需要，取消选中 Webhook 部分的 Active 选项

6. 选择连接器工作所需的权限：

   1. 具有 Read-only 访问权限的 存储库权限 > Issues

   2. 具有 Read-only 访问权限的 存储库权限 > Metadata

7. 如果应用程序仅供您使用，则使用此示例连接器，最好在安装访问部分选择 Only on this account

创建应用程序后，按左侧边栏中的 Install app 选项，然后在账户中安装应用程序。您可以选择应用程序（以及扩展连接器）能够访问的存储库。如果没有进行此安装，连接器将只能访问公共存储库。

OAuth 集成设置¶

安装完成后返回 GitHub 应用程序，并生成新的客户端密钥。确保立即复制该密钥，因为不会再次显示。将客户端密钥粘贴到连接器的 OAuth 配置弹出窗口中。最后，复制应用程序的客户端 ID（不是应用程序 ID），并将其粘贴到连接器的 OAuth 配置弹出窗口中。

按下 Connect 后，将弹出一个 GitHub 窗口，要求您为 GitHub 账户进行应用程序授权。授权后，系统会将您自动重定向回连接器 UI。成功授权后（可能需要几秒钟才能完成并关闭弹出窗口），页面将填充外部访问集成和密钥引用的 IDs。

按下 Connect 按钮将触发连接器内的 TEST_CONNECTION 过程。此过程将尝试访问 GitHub API octocat 端点 (https://api.github.com/octocat)，以检查是否正确配置外部连接，以及是否正确获得 OAuth 访问令牌。

测试成功时，应用程序将进入最终步骤。