Snowpipe REST API를 사용한 데이터 로드 준비

Snowpipe REST API를 사용한 데이터 로드 준비

이 주제는 REST API를 호출할 때 Snowpipe를 시작하는 방법을 설명해요. 여기에는 필수 클라이언트 SDK 설치, (필요하면) 스테이지와 파이프 만들기, 각 Snowpipe 사용자에 대한 일회성 보안 설정 지침이 포함돼요.

참고 — 이 섹션의 지침은 데이터가 로드될 Snowflake 데이터베이스에 이미 대상 테이블이 있다고 가정해요.

출처: Documentation

본문

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

Snowpipe 서비스는 Java SDK 또는 Python SDK가 필요해요. 이 SDK는 편의를 위해 Snowflake가 제공해요.

중요 — 이진 파일은 Snowflake와의 마스터 서비스 계약(MSA) 조건에 따라 클라이언트 소프트웨어로 제공돼요.

Java SDK 설치

참고 — 개발자 노트는 GitHub의 소스 코드와 함께 호스팅돼요.

Python SDK 설치

Python SDK는 Python 3.6 이상이 필요하다는 점에 주의해요.

SDK를 설치하려면 다음 명령을 실행해요.

pip install snowflake-ingest

또는 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 권한이 필요해요.

예를 들어 mydb.myschema 스키마에 mystage 스테이지에 스테이징된 파일의 모든 데이터를 mytable 테이블에 로드하는 파이프를 만들어요.

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

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

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

Snowpipe 데이터 로드를 단일 사용자로 제한할 계획이라면 한 번만 사용자에 대해 키 페어 인증을 구성하면 돼요. 그 후에는 각 데이터 로드에 사용되는 데이터베이스 객체에 대한 액세스 제어 권한만 부여하면 돼요.

참고 — 최소 권한의 일반 원칙을 따르기 위해, 파이프를 사용해 파일을 수집하는 데 사용할 별도의 사용자와 역할을 만드는 것을 권장해요. 사용자는 이 역할을 기본 역할로 만들어야 해요.

키 페어 인증 및 키 교체 사용

Snowpipe REST 엔드포인트는 JWT(JSON Web Token)와 함께 키 페어 인증이 필요해요. JWT는 RSA 암호화를 사용하는 공개/개인 키 페어로 서명돼요.

이 과정의 일부로 다음을 수행해야 해요.

  • 공개-개인 키 페어를 생성해요. 생성된 개인 키는 파일(예: rsa_key.p8이라는 이름)에 있어야 해요.
  • 공개 키를 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 <privileges> … TO ROLE 명령을 사용해 이러한 권한을 역할에 부여해요.

참고 — 보안 관리자(즉, 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;

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

Snowpipe를 사용해 파일을 로드하기 위해 만든 내부 또는 외부 스테이지에 데이터 파일을 복사해요.

  • 클라우드 스토리지 서비스가 제공하는 도구를 사용해 외부 스테이지에 파일을 복사해요.
  • PUT 명령을 사용해 내부 스테이지에 파일을 복사해요.

참고 — Snowflake 계정이 Amazon Web Services에 호스팅되어 있다면 항상 PUT … OVERWRITE = TRUE 문법을 사용할 것을 권장해요. Amazon S3는 버킷에 만들어진 새 객체에 대해 읽기 이후 쓰기 일관성을 제공해요. 그러나 객체가 만들어지기 전에 HEAD 또는 GET 요청이 이루어지면 S3는 객체에 대해 *최종 일관성(eventual consistency)*을 제공해요. 즉, 객체가 만들어진 직후 새 객체에 대한 즉시 요청이 file not found 예외를 반환할 수 있어요. OVERWRITE = TRUE 매개 변수를 설정하면 S3 버킷에서 객체가 만들어지기 전에 HEAD 요청이 시작되는 것을 피할 수 있어요. S3 일관성 모델에 대한 자세한 내용은 S3 문서를 참고해요.

더 알아보기