CREATE API INTEGRATION¶

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

API 통합 오브젝트는 HTTPS API 를 통해 연결된 서비스에 대한 정보를 저장하며, 여기에는 다음 중 일부에 대한 정보가 포함됩니다.

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

Git 리포지토리 API

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

서비스를 사용하기에 충분한 권한이 있는 외부 서비스의 식별자 및 액세스 자격 증명. 예를 들어, 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 = ('<...>')
  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 리포지토리의 경우¶

Git 리포지토리와 통합할 때는 개인 액세스 토큰 또는 OAuth를 사용할 수 있습니다.

참고

OAuth를 사용하여 Git 리포지토리에서 작업하는 기능은 리포지토리가 `github.com<https://github.com/>`_에서 호스팅되는 경우에만 지원됩니다.

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

CREATE [ OR REPLACE ] API INTEGRATION [ IF NOT EXISTS ] <integration_name>
  API_PROVIDER = git_https_api
  API_ALLOWED_PREFIXES = ('https://github.com/<...>')
  [ API_BLOCKED_PREFIXES = ('<...>') ]
  API_USER_AUTHENTICATION = (
    TYPE = snowflake_github_app
  )
  ENABLED = { TRUE | FALSE }
  [ COMMENT = '<string_literal>' ]
  ;

Copy

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 ]
  USE_PRIVATELINK_ENDPOINT = { TRUE | FALSE }
  [ TLS_TRUSTED_CERTIFICATES = ( { <secret_name> [, <secret_name>, ... ] } ) ]
  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 인스턴스를 참조해야 합니다.

테넌트를 찾으려면ID, Azure 포털에 로그인하고 Azure Active Directory » Properties 를 선택합니다. 테넌트 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 관리 서비스) 및 해당 프록시 내의 리소스를 참조하는 외부 함수를 명시적으로 제한합니다. 접두사로 처리되는 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 Gateways)와 이러한 프록시 내의 리소스를 참조하는 외부 함수를 명시적으로 제한합니다. 접두사로 처리되는 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 리포지토리의 경우¶

예를 보려면 Git을 사용하기 위해 Snowflake 설정하기 를 참조하십시오.

integration_name

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

API_PROVIDER = git_https_api

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

API_ALLOWED_PREFIXES = (...)

통합을 사용하여 하나 이상의 HTTPS 엔드포인트 및 해당 엔드포인트 아래의 리소스를 참조하는 요청을 명시적으로 제한합니다. 접두사로 처리되는 URL의 쉼표로 구분된 목록을 지원합니다.

참고

OAuth를 사용하여 인증할 때는 허용된 접두사의 기본 URL에 https://github.com 을 지정해야 합니다. OAuth를 사용한 Git 리포지토리 인증은 워크스페이스에서만 지원되며, 리포지토리가 github.com에서 호스팅되는 경우에만 가능합니다.

대부분의 경우 Snowflake는 모든 HTTPS Git 리포지토리 URL을 지원합니다. 예를 들어, 사용자 지정 URL을 자체 도메인 내의 기업용 Git 서버로 지정할 수 있습니다.

https://example.com/my-repo

API_ALLOWED_PREFIXES = (...) 의 각 URL은 접두사로 처리됩니다. 예를 들어 다음을 지정할 수 있습니다.

https://github.com/my-account

이 접두사를 사용하면 URL 아래의 모든 리소스가 허용됩니다. 예를 들어, 다음이 허용됩니다.

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

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

ENABLED = { TRUE | FALSE }

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

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

기본값은 TRUE 입니다.

선택적 매개 변수¶

모든 통합의 경우¶

API_KEY = api_key

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

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'

통합 설명.

Git 리포지토리의 경우¶

모든 통합에 대한 매개 변수 외에도 통합의 API_PROVIDER 매개 변수를 git_https_api 로 설정하여 원격 Git 리포지토리에 연결하는 통합을 사용하는 경우 다음 매개 변수를 사용하십시오.

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 섹션을 참조하십시오.

API_USER_AUTHENTICATION = ( TYPE = snowflake_github_app )

OAuth 2.0 흐름에 대한 보안 통합 설정을 지정합니다. 값 snowflake_github_app 은 Snowflake가 리포지토리에 연결할 때 사용할 인증 유형으로 OAuth 2.0을 지정합니다.

참고

OAuth를 사용하여 Git 리포지토리에서 작업하는 기능은 리포지토리가 `github.com<https://github.com/>`_에서 호스팅되는 경우에만 지원됩니다.

TLS_TRUSTED_CERTIFICATES = ( {secret_name} [, {secret_name} ... ] )

비공개 링크를 통해 Git 리포지토리 서버로 인증 할 때 사용될 자체 서명 인증서를 포함하는 시크릿을 지정합니다. 이 매개 변수는 인증 기관에서 인증서에 서명한 것이 아니라 자체 서명된 경우에만 필요합니다.

이 매개 변수의 값은 하나 이상의 완전한 Snowflake 시크릿 이름을 지정해야 합니다. 해당 SECRET_STRING 값이 Base64로 인코딩된 인증서 데이터인 일반 문자열 유형이어야 합니다.

USE_PRIVATELINK_ENDPOINT = { TRUE | FALSE }

이 API 통합이 비공개 연결 을 통한 아웃바운드 비공개 링크 연결로 원격 Git 리포지토리에 액세스하는 방식을 구성 하는 데만 사용될지 여부를 지정합니다.

공개 Git 서버의 경우 이 매개 변수는 FALSE (기본값)로 설정해야 합니다.

기본값은 FALSE 입니다.

액세스 제어 요구 사항¶

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

권한	오브젝트	참고
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의 메타데이터 필드 섹션을 참조하십시오.

OR REPLACE 및 IF NOT EXISTS 절은 상호 배타적입니다. 두 문자를 같은 문에 함께 사용할 수 없습니다.
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 통합의 예는 Git을 사용하기 위해 Snowflake 설정하기 섹션을 참조하십시오.