CREATE STORAGE INTEGRATION

CREATE STORAGE INTEGRATION 명령은 계정에 새 스토리지 통합(storage integration)을 만들거나 기존 통합을 교체하는 명령이에요. 스토리지 통합은 외부 클라우드 스토리지에 대해 생성된 IAM(신원 및 접근 관리) 엔터티와 선택적 허용·차단 스토리지 위치 집합을 저장하는 Snowflake 객체입니다.

출처: CREATE STORAGE INTEGRATION

본문

계정에 새 스토리지 통합을 만들거나 기존 통합을 교체하는 명령입니다. 스토리지 통합은 외부 클라우드 스토리지(Amazon S3, Google Cloud Storage, Microsoft Azure)에 대해 생성된 IAM 엔터티와 선택적 허용·차단 스토리지 위치 집합을 저장하는 Snowflake 객체예요. 조직의 클라우드 공급자 관리자는 생성된 엔터티에 스토리지 위치에 대한 권한을 부여합니다. 이 옵션은 사용자가 스테이지를 만들거나 데이터를 로드·언로드할 때 자격 증명을 제공하지 않아도 되게 해줍니다.

단일 스토리지 통합은 여러 외부 스테이지를 지원할 수 있어요. 스테이지 정의의 URL은 STORAGE_ALLOWED_LOCATIONS 파라미터에 지정된 스토리지 위치와 일치해야 합니다.

Syntax

CREATE [ OR REPLACE ] STORAGE INTEGRATION [IF NOT EXISTS]
  <name>
  TYPE = { EXTERNAL_STAGE | POSTGRES_EXTERNAL_STORAGE | POSTGRES_INTERNAL_STORAGE }
  cloudProviderParams
  ENABLED = { TRUE | FALSE }
  STORAGE_ALLOWED_LOCATIONS = ('<cloud>://<bucket>/<path>/' [ , '<cloud>://<bucket>/<path>/' ... ] )
  [ STORAGE_BLOCKED_LOCATIONS = ('<cloud>://<bucket>/<path>/' [ , '<cloud>://<bucket>/<path>/' ... ] ) ]
  [ COMMENT = '<string_literal>' ]

Where:

cloudProviderParams (for Amazon S3) ::=
  STORAGE_PROVIDER = 'S3'
  STORAGE_AWS_ROLE_ARN = '<iam_role>'
  [ STORAGE_AWS_EXTERNAL_ID = '<external_id>' ]
  [ STORAGE_AWS_OBJECT_ACL = 'bucket-owner-full-control' ]
  [ USE_PRIVATELINK_ENDPOINT = { TRUE | FALSE } ]

cloudProviderParams (for Google Cloud Storage) ::=
  STORAGE_PROVIDER = 'GCS'

cloudProviderParams (for Microsoft Azure) ::=
  STORAGE_PROVIDER = 'AZURE'
  AZURE_TENANT_ID = '<tenant_id>'
  [ USE_PRIVATELINK_ENDPOINT = { TRUE | FALSE } ]

Required parameters (필수 파라미터)

name — 통합의 식별자(이름)를 지정하는 문자열이에요. 계정 내에서 고유해야 합니다. 또한 식별자는 알파벳 문자로 시작해야 하고, 전체 식별자 문자열을 큰따옴표로 감싸지 않는 한 공백이나 특수 문자를 포함할 수 없어요 (예: "My object"). 큰따옴표로 감싼 식별자는 대소문자를 구분합니다. 자세한 내용은 Identifier requirements 문서를 참고하세요.
TYPE = { EXTERNAL_STAGE | POSTGRES_EXTERNAL_STORAGE | POSTGRES_INTERNAL_STORAGE } — 통합 유형을 지정해요. (POSTGRES_INTERNAL_STORAGE에 대한 자세한 내용은 CREATE STORAGE INTEGRATION (Postgres Internal Storage) 문서를 참고하세요.)
ENABLED = { TRUE | FALSE } — 이 스토리지 통합을 스테이지에서 사용할 수 있는지 여부를 지정해요. 값은 대소문자를 구분하지 않습니다. 기본값: TRUE
STORAGE_ALLOWED_LOCATIONS = ('<cloud>://<bucket>/<path>/' [ , ... ] ) — 통합을 사용하는 외부 스테이지가 하나 이상의 스토리지 위치(즉 S3 버킷, GCS 버킷, Azure 컨테이너)를 참조하도록 명시적으로 제한해요. 데이터 파일을 로드/언로드하는 데 사용되는 기존 버킷과 선택적으로 경로의 URL을 쉼표로 구분한 목록을 지원합니다. 또는 * 와일드카드("모든 버킷 및/또는 경로에 대한 접근 허용"을 의미)를 지원합니다.
cloudProviderParams — 클라우드 공급자별 파라미터(아래 참고).

Optional parameters (선택 파라미터)

STORAGE_BLOCKED_LOCATIONS = ('<cloud>://<bucket>/<path>/' [ , ... ] ) — 통합을 사용하는 외부 스테이지가 하나 이상의 스토리지 위치(즉 S3 버킷 또는 GCS 버킷)를 참조하는 것을 명시적으로 금지해요. STORAGE_ALLOWED_LOCATIONS가 * 와일드카드로 설정되어 계정의 모든 버킷 접근을 허용할 때 흔히 사용됩니다.

참고 개별 클라우드 스토리지 위치 URL만 따옴표로 감싸야 합니다. STORAGE_BLOCKED_LOCATIONS 값 전체를 따옴표로 감싸면 값이 유효하지 않으며, 결과적으로 사용자가 스토리지 통합을 참조하는 스테이지를 만들 때 해당 파라미터 설정이 무시됩니다.
COMMENT = '<string_literal>' — 통합에 대한 주석을 지정하는 문자열(리터럴)이에요. 기본값: 값 없음

Cloud provider parameters (cloudProviderParams)

Amazon S3

STORAGE_PROVIDER = 'S3' — 데이터 파일을 저장하는 클라우드 스토리지 공급자를 지정해요.
STORAGE_AWS_ROLE_ARN = '<iam_role>' — 데이터 파일이 포함된 S3 버킷에 권한을 부여하는 AWS IAM 역할의 Amazon Resource Name(ARN)을 지정해요. 자세한 내용은 Configuring secure access to Amazon S3 문서를 참고하세요.
STORAGE_AWS_EXTERNAL_ID = '<external_id>' — AWS와 신뢰 관계를 설정하기 위해 Snowflake가 사용하는 외부 ID를 선택적으로 지정해요. 이 스토리지 통합에 대해 구성한 IAM 역할의 신뢰 정책에 같은 외부 ID를 지정해야 합니다. 이 파라미터 값을 지정하지 않으면 Snowflake가 스토리지 통합을 만들 때 외부 ID를 자동으로 생성해요.
STORAGE_AWS_OBJECT_ACL = 'bucket-owner-full-control' — AWS 접근 제어 목록(ACL) 지원을 활성화해 버킷 소유자에게 완전한 제어 권한을 부여해요. 언로드된 테이블 데이터에서 Amazon S3 버킷에 생성된 파일은 AWS IAM 역할이 소유합니다. ACL은 한 AWS 계정의 IAM 역할이 하나 이상의 다른 AWS 계정의 S3 버킷에 접근하도록 구성된 사용 사례를 지원합니다. 사용자가 COPY INTO <location>으로 Snowflake 테이블 데이터를 S3 스테이지의 데이터 파일로 언로드하면 언로드 작업은 언로드된 데이터 파일에 ACL을 적용하고, 파일에 "s3:x-amz-acl":"bucket-owner-full-control" 권한을 적용해 S3 버킷 소유자에게 파일에 대한 완전한 제어권을 부여합니다.
USE_PRIVATELINK_ENDPOINT = { TRUE | FALSE } — 보안 태세를 강화하기 위해 아웃바운드 프라이빗 연결을 사용할지 지정해요. 자세한 내용은 Private connectivity to external stages for Amazon Web Services 문서를 참고하세요.

Google Cloud Storage

STORAGE_PROVIDER = 'GCS' — 데이터 파일을 저장하는 클라우드 스토리지 공급자를 지정해요.

Microsoft Azure

STORAGE_PROVIDER = 'AZURE' — 데이터 파일을 저장하는 클라우드 스토리지 공급자를 지정해요.
AZURE_TENANT_ID = '<tenant_id>' — 허용·차단 스토리지 계정이 속한 Office 365 테넌트의 ID를 지정해요. 스토리지 통합은 하나의 테넌트에만 인증할 수 있으므로 허용·차단 스토리지 위치는 모두 이 테넌트에 속한 스토리지 계정을 참조해야 해요. 테넌트 ID를 찾으려면 Azure 포털에 로그인한 뒤 Azure Active Directory » Properties를 클릭하세요. 테넌트 ID는 Tenant ID 필드에 표시됩니다.
USE_PRIVATELINK_ENDPOINT = { TRUE | FALSE } — 보안 태세를 강화하기 위해 아웃바운드 프라이빗 연결을 사용할지 지정해요. 자세한 내용은 Private connectivity to external stages and Snowpipe automation for Microsoft Azure 문서를 참고하세요.

Microsoft Fabric OneLake

STORAGE_PROVIDER — 클라우드 스토리지 공급자를 지정해요. Microsoft Fabric OneLake 스토리지에는 'AZURE'를 사용하세요.
AZURE_TENANT_ID — Fabric 워크스페이스가 속한 Microsoft Entra ID(구 Azure Active Directory) 테넌트의 ID를 지정해요.

참고 Microsoft Fabric OneLake 스토리지 위치에는 프라이빗 연결 엔드포인트(USE_PRIVATELINK_ENDPOINT)가 지원되지 않습니다.

Access control requirements (접근 제어 요구 사항)

이 작업을 실행하는 데 사용되는 역할은 최소한 다음 권한을 보유해야 해요.

지정된 권한 집합으로 사용자 정의 역할을 만드는 방법은 Creating custom roles 문서를, 보안 객체에 대한 SQL 작업의 역할·권한 부여에 대한 일반적인 정보는 Overview of Access Control 문서를 참고하세요.

Usage notes (사용 참고 사항)

주의 스토리지 통합을 다시 만들면(CREATE OR REPLACE STORAGE INTEGRATION 사용) 스토리지 통합과 그것을 참조하는 모든 스테이지 사이의 연결이 끊어집니다. 이는 스테이지가 이름이 아니라 숨겨진 ID로 스토리지 통합에 연결되기 때문이에요. CREATE OR REPLACE 구문은 내부적으로 객체를 다른 숨겨진 ID로 삭제·재생성합니다. 하나 이상의 스테이지와 연결된 후 스토리지 통합을 다시 만들어야 한다면, ALTER STAGE stage_name SET STORAGE_INTEGRATION = storage_integration_name을 실행해 각 스테이지와 스토리지 통합의 연결을 다시 설정해야 합니다.

Examples (예제)

다음 예제는 통합을 사용하는 외부 스테이지가 두 버킷과 경로 중 하나를 참조하도록 명시적으로 제한하는 통합을 만들어요.

Amazon S3

CREATE STORAGE INTEGRATION s3_int
  TYPE = EXTERNAL_STAGE
  STORAGE_PROVIDER = 'S3'
  STORAGE_AWS_ROLE_ARN = 'arn:aws:iam::001234567890:role/myrole'
  ENABLED = TRUE
  STORAGE_ALLOWED_LOCATIONS = ('s3://mybucket1/path1/', 's3://mybucket2/path2/');

S3 스토리지가 중국의 공용 AWS 리전에 있으면 STORAGE_PROVIDER 파라미터에 'S3CHINA'를, STORAGE_ALLOWED_LOCATIONS에 s3china:// 프로토콜을 사용하세요.

Google Cloud Storage

CREATE STORAGE INTEGRATION gcs_int
  TYPE = EXTERNAL_STAGE
  STORAGE_PROVIDER = 'GCS'
  ENABLED = TRUE
  STORAGE_ALLOWED_LOCATIONS = ('gcs://mybucket1/path1/', 'gcs://mybucket2/path2/');

Microsoft Azure

CREATE STORAGE INTEGRATION azure_int
  TYPE = EXTERNAL_STAGE
  STORAGE_PROVIDER = 'AZURE'
  ENABLED = TRUE
  AZURE_TENANT_ID = '<tenant_id>'
  STORAGE_ALLOWED_LOCATIONS = ('azure://myaccount.blob.core.windows.net/mycontainer/path1/', 'azure://myaccount.blob.core.windows.net/mycontainer/path2/');

다음 예제는 통합을 사용하는 외부 스테이지가 명시적으로 차단된 버킷을 제외하고 계정의 모든 버킷과 경로를 참조하도록 허용하는 통합을 만들어요.

Amazon S3

CREATE STORAGE INTEGRATION s3_int
  TYPE = EXTERNAL_STAGE
  STORAGE_PROVIDER = 'S3'
  STORAGE_AWS_ROLE_ARN = 'arn:aws:iam::001234567890:role/myrole'
  ENABLED = TRUE
  STORAGE_ALLOWED_LOCATIONS = ('*')
  STORAGE_BLOCKED_LOCATIONS = ('s3://mybucket3/path3/', 's3://mybucket4/path4/');

S3 스토리지가 중국의 공용 AWS 리전에 있으면 STORAGE_PROVIDER 파라미터에 'S3CHINA'를, STORAGE_BLOCKED_LOCATIONS에 s3china:// 프로토콜을 사용하세요.

Google Cloud Storage

CREATE STORAGE INTEGRATION gcs_int
  TYPE = EXTERNAL_STAGE
  STORAGE_PROVIDER = 'GCS'
  ENABLED = TRUE
  STORAGE_ALLOWED_LOCATIONS = ('*')
  STORAGE_BLOCKED_LOCATIONS = ('gcs://mybucket3/path3/', 'gcs://mybucket4/path4/');

Microsoft Azure

CREATE STORAGE INTEGRATION azure_int
  TYPE = EXTERNAL_STAGE
  STORAGE_PROVIDER = 'AZURE'
  ENABLED = TRUE
  AZURE_TENANT_ID = 'a123b4c5-1234-123a-a12b-1a23b45678c9'
  STORAGE_ALLOWED_LOCATIONS = ('*')
  STORAGE_BLOCKED_LOCATIONS = ('azure://myaccount.blob.core.windows.net/mycontainer/path3/', 'azure://myaccount.blob.core.windows.net/mycontainer/path4/');

CREATE STORAGE INTEGRATION