CREATE API INTEGRATION

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

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

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

  • Git 리포지토리.

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

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

    이 사용자에게 적절한 권한이 부여될 경우 Snowflake는 이 사용자를 통해 리소스에 액세스할 수 있습니다. 예를 들어, 이는 클라우드 플랫폼의 네이티브 HTTPS 프록시 서비스 인스턴스(예: Amazon API Gateway의 인스턴스)일 수 있습니다.

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

참고 항목:

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

구문

구문은 각 외부 API마다 다릅니다.

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 가 따옴표로 묶여 있으면 안 됩니다.

Git 리포지토리의 경우

CREATE [ OR REPLACE ] API INTEGRATION [ IF NOT EXISTS ] <integration_name>
  API_PROVIDER = git_https_api
  API_ALLOWED_PREFIXES = ('<...>')
  [ API_BLOCKED_PREFIXES = ('<...>') ]
  [ ALLOWED_AUTHENTICATION_SECRETS = ( { <secret_name> [, <secret_name>, ... ] | all | none } ) ]
  ENABLED = { TRUE | FALSE }
  [ COMMENT = '<string_literal>' ]
  ;
Copy

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

필수 매개 변수

Amazon API Gateway의 경우

integration_name

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

API_PROVIDER = { aws_api_gateway | aws_private_api_gateway | aws_gov_api_gateway | aws_gov_private_api_gateway }

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용.

API_AWS_ROLE_ARN = iam_role

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

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

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

ENABLED = { TRUE | FALSE }

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

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

기본값은 TRUE 입니다.

Azure API Management Service의 경우

integration_name

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

API_PROVIDER = azure_api_management

이 통합이 Azure API Management 서비스와 함께 사용됨을 지정합니다. azure_api_management 주위에 따옴표를 사용하지 마십시오.

AZURE_TENANT_ID = 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_AD_APPLICATION_ID = azure_application_id

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

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

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

ENABLED = { TRUE | FALSE }

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

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

기본값은 TRUE 입니다.

Google Cloud API Gateway의 경우

integration_name

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

API_PROVIDER = google_api_gateway

이 통합이 Google Cloud와 함께 사용됨을 지정합니다. 이 목적에 유일하게 유효한 값은 google_api_gateway 입니다. 값을 따옴표로 묶어서는 안 됩니다.

GOOGLE_AUDIENCE = google_audience

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

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

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

ENABLED = { TRUE | FALSE }

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

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

기본값은 TRUE 입니다.

Git 리포지토리의 경우

예를 보려면 리포지토리 API와 상호 작용하기 위한 API 통합 만들기 를 참조하십시오.

integration_name

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

API_PROVIDER = git_https_api

이 통합이 CREATE GIT REPOSITORY 와 함께 사용되어 Git 리포지토리와의 통합 을 생성하도록 지정합니다. 이 목적에 유일하게 유효한 값은 git_https_api 입니다. 값을 따옴표로 묶어서는 안 됩니다.

API_ALLOWED_PREFIXES = (...)

통합을 사용하여 하나 이상의 HTTPS 프록시 서비스 엔드포인트와 이러한 프록시 내의 리소스를 참조하는 함수를 명시적으로 제한합니다. 접두사로 처리되는 URL의 쉼표로 구분된 목록을 지원합니다.

Snowflake는 다음 URL 사용을 지원합니다.

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

https://github.com/my-account

그 의미는

https://github.com/my-account

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

https://github.com/my-account/myproject

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

ENABLED = { TRUE | FALSE }

이 API 통합을 사용할지, 사용하지 않을지 지정합니다. API 통합이 비활성화되면 Git 리포지토리에 액세스할 수 없습니다.

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

기본값은 TRUE 입니다.

선택적 매개 변수

API_BLOCKED_PREFIXES = (...)

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

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

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

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

API_KEY = api_key

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

ALLOWED_AUTHENTICATION_SECRETS = ( secret_name [, secret_name ... ] | all | none )

API_ALLOWED_PREFIXES 값에서 Git 리포지토리에 액세스할 때 UDF 또는 프로시저 처리기 코드가 사용할 수 있는 시크릿을 지정합니다. GIT_CREDENTIALS 매개 변수 를 사용하여 Git 자격 증명을 지정할 때 이 목록에서 시크릿을 지정합니다.

이 매개 변수의 값은 다음 중 하나여야 합니다.

  • 나열된 시크릿을 허용하기 위한 하나 이상의 정규화된 Snowflake 시크릿 이름.

  • (기본값) 모든 시크릿을 허용하기 위한 all.

  • 시크릿을 허용하지 않으려면 none.

ALLOWED_API_AUTHENTICATION_INTEGRATIONS 매개 변수는 허용되는 시크릿을 지정할 수도 있습니다. 자세한 내용은 사용법 노트 섹션을 참조하십시오.

시크릿에 대한 참조 정보는 CREATE SECRET 섹션을 참조하십시오.

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 <오브젝트> 문은 원자성입니다. 즉, 오브젝트가 바뀔 때 단일 트랜잭션으로 이전 오브젝트가 삭제되고 새 오브젝트가 생성됩니다.

예

Amazon API Gateway

다음은 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

Git 리포지토리

Git 리포지토리를 통합하는 데 사용되는 API 통합의 예는 리포지토리 API와 상호 작용하기 위한 API 통합 만들기 섹션을 참조하십시오.

언어: 한국어