CREATE API INTEGRATION

계정에 새 API 통합 오브젝트를 만들거나 기존 API 통합을 대체합니다.

API 통합 오브젝트는 다음에 대한 정보를 포함하여 HTTPS 프록시 서비스에 대한 정보를 저장합니다.

  • 클라우드 플랫폼 공급자(예: Amazon AWS).

  • 프록시 서비스의 유형(클라우드 플랫폼 공급자가 두 가지 이상의 프록시 서비스 유형을 제공하는 경우).

  • 프록시 서비스를 사용하기에 충분한 권한이 있는 클라우드 플랫폼 역할의 식별자 및 액세스 자격 증명. 예를 들어, AWS에서 애 역할의 ARN(Amazon 리소스 이름)은 식별자 및 액세스 자격 증명의 역할을 합니다.

    이 클라우드 사용자에게 적절한 권한이 부여되면 Snowflake가 이 사용자를 사용하여 프록시 서비스(클라우드 플랫폼의 기본 HTTPS 프록시 서비스의 인스턴스. 예: Amazon API Gateway의 인스턴스)의 리소스에 액세스할 수 있습니다.

  • API 통합 오브젝트는 그러한 프록시 서비스에 대해 허용되고 선택적으로 차단되는 엔드포인트와 리소스도 지정합니다.

참고 항목:

ALTER API INTEGRATION , DROP INTEGRATION , SHOW INTEGRATIONS , 외부 함수 쓰기 , CREATE EXTERNAL FUNCTION

구문

구문은 클라우드 플랫폼마다 다릅니다.

Amazon API Gateway의 경우

CREATE [ OR REPLACE ] API INTEGRATION [ IF NOT EXISTS ] <integration_name>
    API_PROVIDER = { aws_api_gateway | aws_private_api_gateway | aws_gov_api_gateway | aws_gov_private_api_gateway }
    API_AWS_ROLE_ARN = '<iam_role>'
    [ API_KEY = '<api_key>' ]
    API_ALLOWED_PREFIXES = ('<...>')
    [ API_BLOCKED_PREFIXES = ('<...>') ]
    ENABLED = { TRUE | FALSE }
    [ COMMENT = '<string_literal>' ]
    ;
Copy

aws_api_gateway 또는 aws_private_api_gateway 또는 aws_gov_api_gateway 또는 aws_gov_private_api_gateway 는 따옴표로 묶여 있으면 됩니다.

Azure API Management의 경우

CREATE [ OR REPLACE ] API INTEGRATION [ IF NOT EXISTS ] <integration_name>
    API_PROVIDER = azure_api_management
    AZURE_TENANT_ID = '<tenant_id>'
    AZURE_AD_APPLICATION_ID = '<azure_application_id>'
    [ API_KEY = '<api_key>' ]
    API_ALLOWED_PREFIXES = ( '<...>' )
    [ API_BLOCKED_PREFIXES = ( '<...>' ) ]
    ENABLED = { TRUE | FALSE }
    [ COMMENT = '<string_literal>' ]
    ;
Copy

azure_api_management 가 따옴표로 묶여 있으면 안 됩니다.

Google Cloud API Gateway의 경우

CREATE [ OR REPLACE ] API INTEGRATION [ IF NOT EXISTS ] <integration_name>
    API_PROVIDER = google_api_gateway
    GOOGLE_AUDIENCE = '<google_audience_claim>'
    API_ALLOWED_PREFIXES = ( '<...>' )
    [ API_BLOCKED_PREFIXES = ( '<...>' ) ]
    ENABLED = { TRUE | FALSE }
    [ COMMENT = '<string_literal>' ]
    ;
Copy

google_api_gateway 가 따옴표로 묶여 있으면 안 됩니다.

필수 매개 변수

Amazon API Gateway의 경우

integration_name

API 통합의 이름을 지정합니다. 이 이름은 오브젝트 식별자 에 대한 규칙을 따릅니다. 계정에서 이름은 API 통합 간에 고유해야 합니다.

provider_info

HTTPS 프록시 서비스 유형을 지정합니다. 유효한 값은 다음과 같습니다.

  • aws_api_gateway: 리전 엔드포인트를 사용하는 Amazon API Gateway용.

  • aws_private_api_gateway: 개인 엔드포인트를 사용하는 Amazon API Gateway용.

  • aws_gov_api_gateway: 미국 정부 GovCloud 엔드포인트를 사용하는 Amazon API Gateway용.

  • aws_gov_private_api_gateway: 프라이빗 엔드포인트이기도 한 미국 정부 GovCloud 엔드포인트를 사용하는 Amazon API Gateway용.

iam_role

Amazon AWS의 경우 이것은 클라우드 플랫폼 역할의 ARN(Amazon 리소스 이름)입니다.

api_key

API 키 (〈구독 키’라고도 함)입니다.

ENABLED = < TRUE | FALSE >

이 API 통합을 사용할지, 사용하지 않을지 지정합니다. API 통합을 사용하지 않을 경우 이 통합에 의존하는 어떤 외부 함수도 작동하지 않습니다.

이 값은 대/소문자를 구분하지 않습니다.

기본값은 TRUE 입니다.

API_ALLOWED_PREFIXES = (...)

통합을 사용하여 하나 이상의 HTTPS 프록시 서비스 엔드포인트(예: Amazon API Gateway)와 이러한 프록시 내의 리소스를 참조하는 외부 함수를 명시적으로 제한합니다. 접두사로 처리되는 URLs의 쉼표로 구분된 목록을 지원합니다(자세한 내용은 아래 참조).

API_ALLOWED_PREFIXES = (...) 의 각 URL은 접두사로 처리됩니다. 다음과 같이 지정한다고 예를 들어 봅시다.

https://xyz.amazonaws.com/production/

그 의미는

https://xyz.amazonaws.com/production/

아래의 모든 리소스가 허용된다는 뜻입니다. 예를 들어 다음이 허용됩니다.

https://xyz.amazonaws.com/production/ml1

보안을 극대화하려면 허용된 위치를 가능한 한 좁게 제한해야 합니다.

Azure API Management Service의 경우

integration_name

API 통합의 이름을 지정합니다. 이 이름은 오브젝트 식별자 에 대한 규칙을 따릅니다. 계정에서 이름은 API 통합 간에 고유해야 합니다.

tenant_id

모든 Azure API Management 인스턴스가 속한 Office 365 tenant의 ID를 지정합니다. API 통합은 하나의 tenant에만 인증할 수 있으므로, 허용 및 차단된 위치는 모두 이 tenant에 속하는 API Management 인스턴스를 참조해야 합니다.

Tenant ID를 찾으려면 Azure 포털에 로그인하여 Azure Active Directory » Properties 를 클릭하십시오. tenant ID는 Tenant ID 필드에 표시됩니다.

azure_application_id

원격 서비스를 위한 Azure AD(Active Directory) 앱의 〈애플리케이션(클라이언트) ID’입니다. Microsoft Azure에서 외부 함수 만들기 의 지침을 준수한 경우 이는 해당 지침의 워크시트에 기록한 Azure Function App AD Application ID 입니다.

api_key

API 키 (〈구독 키’라고도 함)입니다.

ENABLED = < TRUE | FALSE >

이 API 통합을 사용할지, 사용하지 않을지 지정합니다. API 통합을 사용하지 않을 경우 이 통합에 의존하는 어떤 외부 함수도 작동하지 않습니다.

이 값은 대/소문자를 구분하지 않습니다.

기본값은 TRUE 입니다.

API_ALLOWED_PREFIXES = (...)

통합을 사용하여 하나 이상의 HTTPS 프록시 서비스 엔드포인트(예: Azure API Management 서비스)와 이러한 프록시 내의 리소스를 참조하는 외부 함수를 명시적으로 제한합니다. 접두사로 처리되는 URLs의 쉼표로 구분된 목록을 지원합니다(자세한 내용은 아래 참조).

API_ALLOWED_PREFIXES = (...) 의 각 URL은 접두사로 처리됩니다. 다음과 같이 지정한다고 예를 들어 봅시다.

https://my-external-function-demo.azure-api.net/my-function-app-name

그 의미는

https://my-external-function-demo.azure-api.net/my-function-app-name

아래의 모든 리소스가 허용된다는 뜻입니다. 예를 들어 다음이 허용됩니다.

https://my-external-function-demo.azure-api.net/my-function-app-name/my-http-trigger-function

보안을 극대화하려면 허용된 위치를 가능한 한 좁게 제한해야 합니다.

Google Cloud API Gateway의 경우

integration_name

API 통합의 이름을 지정합니다. 이 이름은 오브젝트 식별자 에 대한 규칙을 따릅니다. 계정에서 이름은 API 통합 간에 고유해야 합니다.

google_audience

이것은 Google API Gateway에 대해 인증하기 위해 JWT(JSON Web Token)을 생성할 때 대상 그룹 클레임으로 사용됩니다. Google 인증에 대한 자세한 내용은 Google 서비스 계정 인증 설명서 를 참조하십시오.

ENABLED = < TRUE | FALSE >

이 API 통합을 사용할지, 사용하지 않을지 지정합니다. API 통합을 사용하지 않을 경우 이 통합에 의존하는 어떤 외부 함수도 작동하지 않습니다.

이 값은 대/소문자를 구분하지 않습니다.

기본값은 TRUE 입니다.

API_ALLOWED_PREFIXES = (...)

통합을 사용하여 하나 이상의 HTTPS 프록시 서비스 엔드포인트(예: Google Cloud API Gateway)와 이러한 프록시 내의 리소스를 참조하는 외부 함수를 명시적으로 제한합니다. 접두사로 처리되는 URLs의 쉼표로 구분된 목록을 지원합니다(자세한 내용은 아래 참조).

API_ALLOWED_PREFIXES = (...) 의 각 URL은 접두사로 처리됩니다. 다음과 같이 지정한다고 예를 들어 봅시다.

https://my-external-function-demo.uc.gateway.dev/x

그 의미는

https://my-external-function-demo.uc.gateway.dev/x

아래의 모든 리소스가 허용된다는 뜻입니다. 예를 들어 다음이 허용됩니다.

https://my-external-function-demo.uc.gateway.dev/x/y

보안을 극대화하려면 허용된 위치를 가능한 한 좁게 제한해야 합니다.

선택적 매개 변수

이러한 선택적 매개 변수는 다음 각각에 적용됩니다.

  • Amazon API Gateway.

  • Azure API Management Service.

  • Google Cloud API Gateway.

API_BLOCKED_PREFIXES = (...)

Snowflake에서 호출할 수 없는 HTTPS 프록시 서비스의 엔드포인트와 리소스를 나열합니다.

위치에 대해 가능한 값은 위의 API_ALLOWED_PREFIXES 에 대한 것과 같은 규칙을 따릅니다.

API_BLOCKED_PREFIXES가 API_ALLOWED_PREFIXES에 우선합니다. 둘 모두와 일치하는 접두사는 차단됩니다. 즉, Snowflake는 API_BLOCKED_PREFIXES와도 일치하는 값을 제외하고 API_ALLOWED_PREFIXES와 일치하는 모든 값을 허용합니다.

어떤 값이 API_ALLOWED_PREFIXES 외부에 있으면 이를 명시적으로 차단할 필요가 없습니다.

COMMENT = '<string_literal>'

외부 함수에 대한 설명입니다.

액세스 제어 요구 사항

이 SQL 명령을 실행하는 데 사용되는 역할 에는 최소한 다음 권한 이 있어야 합니다.

권한

오브젝트

참고

CREATE INTEGRATION

계정

Only the ACCOUNTADMIN role has this privilege by default. The privilege can be granted to additional roles as needed.

지정된 권한 세트로 사용자 지정 역할을 만드는 방법에 대한 지침은 사용자 지정 역할 만들기 섹션을 참조하십시오.

보안 오브젝트 에 대해 SQL 작업을 수행하기 위한 역할과 권한 부여에 대한 일반적인 정보는 액세스 제어의 개요 섹션을 참조하십시오.

사용법 노트

  • API 통합에 대한 OWNERSHIP 또는 USAGE 권한이 있는 Snowflake 역할만 API 통합을 직접(예: 해당 API 통합을 지정하는 외부 함수를 만들어 직접) 사용할 수 있습니다.

  • API 통합 오브젝트는 특정 HTTPS 프록시 URL이 아니라, 해당 계정 내의 특정 클라우드 플랫폼 계정과 역할에 연결됩니다. 클라우드 공급자 계정에서 둘 이상의 HTTPS 프록시 서비스 인스턴스를 만들 수 있으며, 똑같은 API 통합을 사용하여 해당 계정의 여러 프록시 서비스에 인증할 수 있습니다.

  • Snowflake 계정에는 예컨대 다양한 클라우드 플랫폼 계정에 대해 여러 개의 API 통합 오브젝트가 있을 수 있습니다.

  • 여러 외부 함수가 똑같은 API 통합 오브젝트를 사용할 수 있으므로, 똑같은 HTTPS 프록시 서비스를 사용할 수 있습니다.

  • 메타데이터 관련:

    주의

    고객은 Snowflake 서비스를 사용할 때 개인 데이터(사용자 오브젝트 제외), 민감한 데이터, 수출 통제 대상 데이터 또는 기타 규제 데이터가 메타데이터로 입력되지 않도록 해야 합니다. 자세한 내용은 Snowflake의 메타데이터 필드 섹션을 참조하십시오.

  • CREATE OR REPLACE <오브젝트> 문은 원자성입니다. 즉, 오브젝트가 바뀔 때 단일 트랜잭션으로 이전 오브젝트가 삭제되고 새 오브젝트가 생성됩니다.

API 통합을 만들고 후속 CREATE EXTERNAL FUNCTION 문에서 해당 API 통합을 사용하는 방법을 보여주는 예입니다.

create or replace api integration demonstration_external_api_integration_01
    api_provider=aws_api_gateway
    api_aws_role_arn='arn:aws:iam::123456789012:role/my_cloud_account_role'
    api_allowed_prefixes=('https://xyz.execute-api.us-west-2.amazonaws.com/production')
    enabled=true;

create or replace external function local_echo(string_col VARCHAR)
    returns variant
    api_integration = demonstration_external_api_integration_01
    as 'https://xyz.execute-api.us-west-2.amazonaws.com/production/remote_echo';
Copy