Snowpipe REST API를 사용하여 데이터 로드 준비하기

이 항목에서는 REST API를 호출할 때 Snowpipe를 시작하는 방법에 대해 설명하며, 필수 클라이언트 SDK 설치, 스테이지(필요한 경우) 및 파이프 생성, 각 Snowpipe 사용자에 대한 일회성 보안 설정에 대한 지침을 제공합니다.

이 항목의 내용:

참고

이 섹션의 지침에서는 Snowflake 데이터베이스에 데이터를 로드할 대상 테이블이 이미 있는 것으로 가정합니다.

클라이언트 요구 사항(Java 또는 Python SDK)

Snowpipe 서비스를 위해서는 Java SDK 또는 Python SDK 중 하나 가 필요합니다. 이러한 SDKs는 사용자의 편의를 위해 Snowflake가 제공합니다.

중요

바이너리는 Snowflake와의 마스터 서비스 계약(MSA) 약관에 따라 클라이언트 소프트웨어로 제공됩니다.

Java SDK 설치하기

  1. Maven Central Repository에서 Java SDK 설치 관리자 다운로드:

    Sonatype (또는 https://repo1.maven.org/maven2/net/snowflake/snowflake-ingest-sdk)

  2. JAR 파일을 기존 프로젝트에 통합합니다.

참고

개발자 노트는 GitHub 에 소스 코드와 함께 호스팅됩니다.

Python SDK 설치하기

Python SDK에는 Python 3.6 이상이 필요합니다.

SDK를 설치하려면 다음 명령을 실행합니다.

pip install snowflake-ingest
Copy

또는, PyPI 에서 wheel 파일을 다운로드한 후 기존 프로젝트에 통합합니다.

참고

개발자 노트는 GitHub 에 소스 코드와 함께 호스팅됩니다.

1단계: 스테이지 만들기(필요한 경우)

Snowpipe가 로드를 지원하는 스테이지 타입은 다음과 같습니다.

  • 명명된 내부(Snowflake) 또는 외부(Amazon S3, Google Cloud Storage 또는 Microsoft Azure) 스테이지

  • 테이블 스테이지

CREATE STAGE 명령을 사용하여 명명된 스테이지를 생성하거나 기존 스테이지를 사용하도록 선택할 수 있습니다. 사용자가 파일을 임시로 스테이징한 후에 Snowpipe가 대상 테이블에 파일을 로드합니다.

2단계: 파이프 만들기

Snowpipe 가 수집 큐에서 테이블로 데이터를 로드하기 위해 사용하는 COPY INTO <table> 문을 정의하기 위해 시스템에 새 파이프를 만듭니다. 자세한 내용은 CREATE PIPE 섹션을 참조하십시오.

참고

파이프를 생성하려면 CREATE PIPE 액세스 제어 권한과 데이터베이스, 스키마 및 스테이지에 대한 USAGE 권한이 필요합니다.

예를 들어, mystage 스테이지에서 스테이징된 파일의 모든 데이터를 mytable 테이블로 로드하는 파이프를 mydb.myschema 스키마에 생성합니다.

create pipe mydb.myschema.mypipe if not exists as copy into mydb.myschema.mytable from @mydb.myschema.mystage;
Copy

3단계: 보안 구성하기(사용자별)

Snowpipe를 사용하여 연속으로 데이터를 로드할 각 사용자에 대해 Snowpipe REST 엔드포인트를 호출하기 위한 공개-개인 키 페어를 생성합니다. 또한, 데이터 로드에 대한 오브젝트(즉, 대상 데이터베이스, 스키마 및 테이블), 스테이지 오브젝트 및 파이프에 대한 충분한 권한을 부여합니다.

Snowpipe 데이터 로드를 1명의 사용자로 제한하려는 경우 사용자에 대한 키 페어 인증을 한 번만 구성하면 됩니다. 이후에는 각 데이터를 로드하기 사용되는 데이터베이스 오브젝트에 대한 액세스 제어 권한만 부여하면 됩니다.

참고

최소 권한의 일반 원칙을 따르려면 파이프를 사용하여 파일을 수집하기 위해 사용할 별도의 사용자와 역할을 생성하는 것이 좋습니다. 이 역할을 기본 역할로 사용하여 사용자를 생성해야 합니다.

키 페어 인증 및 키 순환 사용하기

Snowpipe REST 엔드포인트는 JSON 웹 토큰(JWT)이 포함된 키 페어 인증이 필요합니다. JWTs는 RSA 암호화가 적용된 공용/개인 키 페어를 사용하여 서명됩니다.

이 프로세스의 일부로서 다음을 수행해야 합니다.

  1. 공개-개인 키 페어를 생성합니다. 생성된 개인 키는 파일(예: 이름이 rsa_key.p8 인 파일)에 있어야 합니다.

  2. Snowflake 사용자에게 공개 키를 할당합니다. 사용자에게 키를 할당한 후 DESCRIBE USER 명령을 실행합니다. 출력에서 RSA_PUBLIC_KEY_FP 속성은 사용자에게 할당된 공개 키의 지문으로 설정되어야 합니다.

키 페어를 생성하고 사용자에게 키를 할당하는 방법에 대한 지침은 키 페어 인증 및 키 페어 순환 을 참조하십시오.

지문 생성과 JWT 토큰 생성의 언어별 예시는 다음 섹션을 참조하십시오.

액세스 권한 부여하기

Snowpipe REST 엔드포인트를 호출하려면 다음 최소 권한이 있는 역할이 필요합니다.

오브젝트

권한

참고

명명된 파이프

OPERATE(insertFiles 엔드포인트), MONITOR(insertReport, loadHistoryScan 엔드포인트)

명명된 스테이지

USAGE(외부 스테이지), READ(내부 스테이지)

명명된 파일 형식

USAGE

선택 사항으로, 스테이지(1단계: 스테이지 만들기(필요한 경우) 참조) 또는 파이프(2단계: 파이프 만들기) 중 하나가 명명된 파일 형식을 참조하는 경우에만 필요합니다.

대상 데이터베이스

USAGE

대상 스키마

USAGE

대상 테이블

INSERT , SELECT

GRANT <권한> 명령을 사용하여 역할에 이러한 권한을 부여합니다.

참고

보안 관리자(즉, SECURITYADMIN 역할 사용자) 이상 또는 계정에 대한 CREATE ROLE 권한과 전역 MANAGE GRANTS 권한이 모두 있는 역할만 역할을 생성하고 권한을 부여할 수 있습니다.

예를 들어, mypipe 라는 파이프를 통해 데이터를 로딩할 수 있는 snowpipe1 이라는 역할을 만듭니다. 파이프는 외부 스테이지를 참조합니다.

 -- Create a role for the Snowpipe privileges.
use role securityadmin;

create or replace role snowpipe1;

-- Grant the USAGE privilege on the database and schema that contain the pipe object.
grant usage on database mydb to role snowpipe1;
grant usage on schema mydb.myschema to role snowpipe1;

-- Grant the INSERT and SELECT privileges on the target table.
grant insert, select on mydb.myschema.mytable to role snowpipe1;

-- Grant the USAGE privilege on the external stage.
grant usage on stage mydb.myschema.mystage to role snowpipe1;

-- Grant the OPERATE and MONITOR privileges on the pipe object.
grant operate, monitor on pipe mydb.myschema.mypipe to role snowpipe1;

-- Grant the role to a user
grant role snowpipe1 to user jsmith;

-- Set the role as the default role for the user
alter user jsmith set default_role = snowpipe1;
Copy

4단계: 스테이지 데이터 파일

Snowpipe를 사용하여 파일을 로드하기 위해 생성한 내부 또는 외부 스테이지에 데이터 파일을 복사합니다.

  • 클라우드 저장소 서비스에서 제공하는 도구를 사용하여 파일을 외부 스테이지에 복사합니다.

  • PUT 명령을 사용하여 내부 스테이지에 파일을 복사합니다.

    참고

    Snowflake 계정이 Amazon Web Services에서 호스팅되는 경우에는 항상 PUT … OVERWRITE = TRUE 구문을 사용하는 것이 좋습니다.

    Amazon S3는 버킷에서 생성된 새 오브젝트에 쓰기 후 읽기 일관성을 제공합니다. 그러나 오브젝트를 생성하기 전 오브젝트에 대한 HEAD 또는 GET 요청이 수행되면 S3는 오브젝트에 대한 최종 일관성 을 제공합니다. 즉, 새 오브젝트가 생성된 직후의 요청에서 file not found 예외가 반환될 수 있습니다. OVERWRITE = TRUE 매개 변수를 설정하면 S3 버킷에 오브젝트가 생성되기 전에 HEAD 요청이 시작되지 않습니다.

    S3 일관성 모델에 대한 자세한 내용은 S3 설명서 를 참조하십시오.

다음 항목: 데이터를 로드하기 위한 Snowpipe REST 엔드포인트 개요 에서 공개 REST 엔드포인트를 호출하여 데이터를 로드하고 로드 내역 보고서를 검색하는 방법에 대해 알아봅니다.

언어: 한국어