자습서: Snowflake Native SDK for Connectors Java Connector 예¶

전제 조건¶

시작하기 전에 다음 요구 사항을 충족하는지 확인합니다.

• Java에 대한 기본 지식

• Snowflake Native Apps 에 대한 기본 지식

• Streamlit UI 에 대한 기본 지식

• ACCOUNTADMIN 역할이 있는 Snowflake 계정에 액세스하기

• GitHub 앱 을 만들 수 있는 GitHub 계정

• 프로젝트를 빌드하고 배포 스크립트를 실행하기 위한 MacOS 또는 Linux 머신

Java 설치¶

Snowflake Native SDK for Connectors 에는 Java LTS (장기 지원) 버전 11 이상이 필요합니다. 컴퓨터에 최소 요구 사항인 Java 버전이 설치되어 있지 않은 경우 Oracle Java 또는 OpenJDK 를 설치해야 합니다.

리포지토리 복제¶

connectors-native-sdk 리포지토리를 컴퓨터에 복제합니다.

Snowflake CLI 구성¶

커넥터를 빌드, 배포 및 설치하려면 Snowflake CLI 도구가 필요합니다. 컴퓨터에 Snowflake CLI 가 설치되어 있지 않은 경우 여기 의 지침에 따라 설치하십시오.

도구가 설치된 후 구성 파일 에서 Snowflake에 대한 연결을 구성해야 합니다.

구성된 연결이 없는 경우 native_sdk_connection 이라는 이름의 연결을 새로 만듭니다. deployment/snowflake.toml 파일에서 연결 예시를 찾을 수 있습니다.

이미 연결이 구성되어 있고 커넥터와 함께 사용하려는 경우 이 자습서에서 이 연결을 사용할 때마다 native_sdk_connection 대신 해당 이름을 사용하십시오.

Connectors Native SDK Java¶

connectors-native-sdk-java 디렉터리에는 SDK 구성 요소에 대한 단위 및 통합 테스트와 함께 모든 Snowflake Native SDK for Connectors Java 코드가 포함되어 있습니다. Snowflake 내부의 Native Apps의 특성상 이는 Java 코드뿐만 아니라 작동하는 애플리케이션을 만드는 데 필요한 SQL 코드도 의미합니다. 데이터베이스 오브젝트의 정의는 src/main/resources 디렉터리에서 확인할 수 있습니다. 이러한 파일은 애플리케이션을 만들 때 애플리케이션 내에서 사용할 수 있는 오브젝트를 사용자 지정하는 데 사용됩니다. 예시 커넥터에서는 사용 가능한 모든 함수에 대한 오브젝트를 생성하는 all.sql 파일을 사용합니다. 이 파일은 애플리케이션 인스턴스의 설치 프로세스 중에 실행됩니다.

Connectors Native SDK Test Java¶

connectors-native-sdk-test-java 디렉터리에는 단위 테스트에 사용되는 도우미 라이브러리의 원본 코드(예: 특정 구성 요소, 사용자 지정 어설션 등을 모의하는 데 사용되는 오브젝트)가 포함되어 있습니다. 이러한 파일은 커넥터 애플리케이션의 일부가 아닙니다.

예시 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 구성 요소의 사용자 지정과 같은 사용자 지정 커넥터 로직이 포함되어 있습니다.

Connectors Native SDK Template¶

Snowflake Native SDK for Connectors 를 종속성으로 사용하여 새 커넥터를 빠르게 빌드하는 데 도움이 되는 템플릿 Gradle Java 프로젝트입니다. 자세한 내용은 자습서: Snowflake Native SDK for Connectors Java Connector 템플릿 에서 확인할 수 있습니다.

커넥터 빌드하기¶

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 섹션을 참조하십시오.

생성된 애플리케이션 패키지는 이제 계정의 Snowflake UI 에서 Data products 카테고리의 App packages 탭에 표시됩니다.

커넥터 설치하기¶

애플리케이션 설치가 프로세스의 마지막 단계입니다. 이전에 생성한 애플리케이션 패키지에서 애플리케이션을 생성합니다.

커넥터를 설치하려면 snow app run --connection=native_sdk_connection 명령을 실행합니다.

snow app run 명령에 대한 자세한 내용은 snow app run 섹션을 참조하십시오.

설치된 애플리케이션은 이제 계정의 Snowflake UI 에서 Data products 카테고리의 Installed apps 탭에 표시됩니다.

커넥터 파일 업데이트하기¶

커넥터 파일을 수정하려는 경우 언제든지 애플리케이션 패키지 스테이지에 수정된 파일을 쉽게 업로드할 수 있습니다. 업로드 명령은 업데이트된 파일에 따라 달라집니다.

업데이트 명령을 실행하기 전에 ./gradlew copyInternalComponents 를 실행하여 sf_build 디렉터리에 커넥터의 새 파일을 복사해야 합니다.

권한¶

애플리케이션은 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 - secret_references 필드에서 지정된 시크릿을 사용하도록 Permission SDK 에 지시하는 LIST

프로시저에서 제공하는 시크릿 참조:

• type - 시크릿의 경우 OAUTH2

• security_integration - 생성된 보안 통합의 속성:

  • oauth_scopes - 커넥터가 요청한 OAuth 범위의 목록(GitHub 앱을 사용하는 경우 - 이 필드는 선택 사항임)

  • oauth_token_endpoint - 새로 고침 및 액세스 토큰을 획득할 엔드포인트

  • oauth_authorization_endpoint - 승인 요청이 전송될 엔드포인트

GitHub 앱 설정¶

다음 단계는 사용자 계정에 GitHub 앱을 설정하는 것입니다. 이 앱은 데이터를 수집할 수 있도록 계정에 대한 제한된 액세스 권한을 부여하는 데 사용됩니다.

첫 번째 단계는 커넥터 UI 에서 Request access 버튼을 누르는 것입니다.

첫 번째 화면에서는 외부 연결이 허용되는 엔드포인트를 검토할 수 있습니다.

Next 를 누르면 두 번째 화면이 표시됩니다. OAuth2 를 선택하여 새 통합 및 시크릿을 생성하고 제공된 리디렉션 URL (조직 이름과 계정의 리전 포함)을 복사합니다.

다음으로, GitHub 계정 설정 페이지로 이동한 다음 Developer settings > 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 액세스 권한을 가진 Repository permissions > Issues

   2. Read-only 액세스 권한을 가진 Repository permissions > Metadata

7. 이 예시 커넥터를 사용하여 앱이 본인만 사용하는 경우 설치 액세스 섹션에서 Only on this account 를 선택하는 것이 가장 좋음

앱이 생성된 후 왼쪽 사이드바에서 Install app 옵션을 누르고 계정에 애플리케이션을 설치합니다. 앱(및 확장 프로그램인 커넥터)이 액세스할 수 있는 리포지토리를 선택할 수 있습니다. 이 설치가 없으면 커넥터는 공용 리포지토리에만 액세스할 수 있습니다.

OAuth 통합 설정¶

설치 후 GitHub 앱으로 돌아가서 새 클라이언트 시크릿을 생성합니다. 다시 표시되지 않으므로 즉시 복사하십시오. 커넥터의 OAuth 구성 팝업에 클라이언트 시크릿을 붙여넣습니다. 마지막으로 애플리케이션의 클라이언트 ID (앱이 아닌 ID)를 복사본으로 만들어 커넥터의 OAuth 구성 팝업에 붙여넣습니다.

Connect 를 누르면 GitHub 창이 나타나며 GitHub 계정에 대한 앱 승인을 요청합니다. 승인 후 - 커넥터 UI 로 자동 리디렉션됩니다. 승인에 성공하면(완료하고 팝업을 닫는 데 몇 초 정도 걸릴 수 있음) 외부 액세스 통합 및 시크릿 참조의 ID로 페이지가 채워집니다.

Connect 버튼을 누르면 커넥터 내부의 TEST_CONNECTION 프로시저가 트리거됩니다. 이 프로시저는 GitHub API octocat 엔드포인트 에 접속하여 외부 연결이 올바르게 구성되었는지, OAuth 액세스 토큰이 올바르게 획득되었는지 확인합니다.

테스트에 성공하면 애플리케이션이 마무리 단계로 진행됩니다.