CREATE API INTEGRATION

CREATE API INTEGRATION

계정에 새 API 통합(API integration) 객체를 만들거나 기존 API 통합을 교체하는 명령이에요.

출처: 문서

본문

API 통합 객체는 HTTPS API를 통해 도달하는 서비스에 대한 정보를 저장해요. 다음 중 일부에 대한 정보를 포함해요:

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

  • Git 저장소 API.

  • MCP 커넥터(MCP Connectors)가 Cortex Agent에 타사 도구를 노출하는 데 사용하는 외부 Model Context Protocol(MCP) 서버.

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

  • 서비스를 사용할 충분한 권한이 있는 외부 서비스의 식별자와 접근 자격 증명. 예를 들어 AWS에서는 역할의 ARN(Amazon resource name)이 식별자와 접근 자격 증명으로 사용돼요.

이 사용자에게 적절한 권한이 부여되면 Snowflake는 이 사용자를 사용해 리소스에 접근할 수 있어요. 예를 들어 이것은 클라우드 플랫폼의 네이티브 HTTPS 프록시 서비스 인스턴스, 예를 들어 Amazon API Gateway 인스턴스일 수 있어요.

  • API 통합 객체는 또한 그 서비스에서 허용되는(그리고 선택적으로 차단되는) 엔드포인트와 리소스를 지정해요.

관련 명령: ALTER API INTEGRATION, DROP INTEGRATION, SHOW INTEGRATIONS, Writing external functions, CREATE EXTERNAL FUNCTION

구문 (Syntax)

구문은 각 외부 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>' ]
  ;

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>' ]
  ;

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>' ]
  ;

google_api_gateway는 따옴표 안에 넣지 않아야 해요.

Git 저장소용

Git 저장소와 통합할 때는 개인 액세스 토큰 또는 OAuth를 사용할 수 있어요.

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>' ]
  ;

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>' ]
  ;

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

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>' ]
  ;

git_https_api는 따옴표 안에 넣지 않아야 해요.

외부 MCP 서버용

외부 Model Context Protocol(MCP) 서버와 통합할 때는 표준 OAuth 2.0 또는 OAuth Dynamic Client Registration(DCR)을 사용해요. 엔드투엔드 설정은 MCP Connectors를 참고하세요.

CREATE [ OR REPLACE ] API INTEGRATION [ IF NOT EXISTS ] <integration_name>
  API_PROVIDER = external_mcp
  API_ALLOWED_PREFIXES = ('<...>')
  API_USER_AUTHENTICATION = (
    TYPE = OAUTH2
    OAUTH_CLIENT_ID = '<client_id>'
    OAUTH_CLIENT_SECRET = '<client_secret>'
    OAUTH_TOKEN_ENDPOINT = '<token_endpoint_url>'
    OAUTH_AUTHORIZATION_ENDPOINT = '<authorization_endpoint_url>'
    [ OAUTH_CLIENT_AUTH_METHOD = { CLIENT_SECRET_BASIC | CLIENT_SECRET_POST | NONE } ]
    [ OAUTH_DISCOVERY_URL = '<discovery_url>' ]
    [ OAUTH_REFRESH_TOKEN_VALIDITY = <integer> ]
  )
  ENABLED = { TRUE | FALSE }
  [ COMMENT = '<string_literal>' ]
  ;

CREATE [ OR REPLACE ] API INTEGRATION [ IF NOT EXISTS ] <integration_name>
  API_PROVIDER = external_mcp
  API_ALLOWED_PREFIXES = ('<...>')
  API_USER_AUTHENTICATION = (
    TYPE = OAUTH_DYNAMIC_CLIENT
    OAUTH_RESOURCE_URL = '<resource_url>'
  )
  ENABLED = { TRUE | FALSE }
  [ COMMENT = '<string_literal>' ]
  ;

external_mcp는 따옴표 안에 넣지 않아야 해요.

필수 파라미터 (Required parameters)

Amazon API Gateway용

*integration_name*

API 통합의 이름을 지정해요. 이 이름은 객체 식별자(Object identifiers) 규칙을 따르며, 계정의 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 resource name)이에요.

API_ALLOWED_PREFIXES = (...)

통합을 사용하는 외부 함수가 참조할 수 있는 HTTPS 프록시 서비스 엔드포인트(예: Amazon API Gateway)와 그 프록시 내 리소스를 명시적으로 제한해요. 쉼표로 구분된 URL 목록을 지원하며, 각 URL은 접두사로 취급돼요.

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 테넌트의 ID를 지정해요. API 통합은 하나의 테넌트에만 인증할 수 있으므로, 허용 및 차단 위치는 모두 이 테넌트에 속한 API Management 인스턴스를 가리켜야 해요.

테넌트 ID를 찾으려면 Azure 포털에 로그인하고 Azure Active Directory » Properties를 선택해요. 테넌트 ID는 Tenant ID 필드에 표시돼요.

AZURE_AD_APPLICATION_ID = *azure_application_id*

원격 서비스용 Azure AD(Active Directory) 앱의 "Application (client) id"예요. Microsoft Azure에서 외부 함수 만들기의 지침을 따랐다면, 그 지침의 워크시트에서 기록한 Azure Function App AD Application ID가 바로 이 값이에요.

API_ALLOWED_PREFIXES = (...)

통합을 사용하는 외부 함수가 참조할 수 있는 HTTPS 프록시 서비스 엔드포인트(예: Azure API Management 서비스)와 그 프록시 내 리소스를 명시적으로 제한해요. 쉼표로 구분된 URL 목록을 지원하며, 각 URL은 접두사로 취급돼요.

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)를 생성할 때 audience 클레임으로 사용돼요. Google 인증에 대한 자세한 내용은 Google 서비스 계정 인증 문서를 참고하세요.

API_ALLOWED_PREFIXES = (...)

통합을 사용하는 외부 함수가 참조할 수 있는 HTTPS 프록시 서비스 엔드포인트(예: Google Cloud API Gateways)와 그 프록시 내 리소스를 명시적으로 제한해요. 쉼표로 구분된 URL 목록을 지원하며, 각 URL은 접두사로 취급돼요.

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 저장소용

예제는 Setting up Snowflake to use Git을 참고하세요.

*integration_name*

API 통합의 이름을 지정해요. 이 이름은 객체 식별자 규칙을 따르며, 계정의 API 통합 중에서 고유해야 해요.

API_PROVIDER = git_https_api

이 통합이 CREATE GIT REPOSITORY와 함께 사용되어 원격 Git 저장소와의 통합을 만든다고 지정해요. 이 목적을 위한 유일한 유효한 값은 git_https_api예요. 값은 따옴표 안에 넣으면 안 돼요.

API_ALLOWED_PREFIXES = (...)

통합을 사용하는 요청이 참조할 수 있는 HTTPS 엔드포인트와 그 엔드포인트 아래의 리소스를 명시적으로 제한해요. 쉼표로 구분된 URL 목록을 지원하며, 각 URL은 접두사로 취급돼요.

대부분의 경우 Snowflake는 모든 HTTPS Git 저장소 URL을 지원해요. 예를 들어 자체 도메인 내의 회사 Git 서버에 사용자 지정 URL을 지정할 수 있어요.

https://example.com/my-repo

API_ALLOWED_PREFIXES = (...)의 각 URL은 접두사로 취급돼요. 예를 들어 다음을 지정할 수 있어요:

https://example.com/my-account

이 접두사 아래의 모든 리소스가 허용돼요. 예를 들어 다음은 허용돼요:

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

보안을 최대화하려면 허용 위치를 실용적으로 가능한 한 좁게 제한해야 해요.

ENABLED = { TRUE | FALSE }

이 API 통합이 활성화되는지 비활성화되는지 지정해요. API 통합이 비활성화되면 Git 저장소에 접근할 수 없어요.

값은 대소문자를 구분하지 않아요.

기본값은 TRUE예요.

외부 MCP 서버용

엔드투엔드 설정은 MCP Connectors를 참고하세요.

*integration_name*

API 통합의 이름을 지정해요. 이 이름은 객체 식별자 규칙을 따르며, 계정의 API 통합 중에서 고유해야 해요.

API_PROVIDER = external_mcp

이 통합이 외부 Model Context Protocol(MCP) 서버에 연결되며, MCP 커넥터가 Cortex Agent에 타사 도구를 노출하는 데 사용한다고 지정해요. 이 목적을 위한 유일한 유효한 값은 external_mcp예요. 값은 따옴표 안에 넣으면 안 돼요.

API_ALLOWED_PREFIXES = (...)

통합을 사용하는 요청이 나열된 URL 접두사 아래의 HTTPS 엔드포인트 하나 이상을 참조하도록 명시적으로 제한해요. 쉼표로 구분된 URL 목록을 지원하며, 각 URL은 접두사로 취급돼요. 외부 MCP 서버의 기본 URL로 설정해요. 예: 'https://mcp.atlassian.com/v1/mcp'.

보안을 최대화하려면 허용 위치를 가능한 한 좁게 제한하세요.

API_USER_AUTHENTICATION = (...)

외부 MCP 서버에 연결하는 데 사용되는 OAuth 설정을 지정해요. EXTERNAL_MCP는 OAuth만 지원하므로 이 파라미터는 필수예요. TYPE = OAUTH2와 TYPE = OAUTH_DYNAMIC_CLIENT 아래의 하위 파라미터 전체 목록은 아래 외부 MCP 서버용을 참고하세요.

ENABLED = { TRUE | FALSE }

이 API 통합이 활성화되는지 비활성화되는지 지정해요. API 통합이 비활성화되면 Cortex Agent가 외부 MCP 서버에 접근할 수 없어요.

값은 대소문자를 구분하지 않아요.

기본값은 TRUE예요.

선택 파라미터 (Optional parameters)

모든 통합 공통

API_KEY = *api_key*

API 키("구독 키"라고도 함)예요.

API_BLOCKED_PREFIXES = (...)

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

위치의 가능한 값은 위 API_ALLOWED_PREFIXES와 같은 규칙을 따라요.

API_BLOCKED_PREFIXES는 API_ALLOWED_PREFIXES보다 우선해요. 접두사가 둘 다와 일치하면 차단돼요. 즉 Snowflake는 API_ALLOWED_PREFIXES와 일치하는 모든 값 중에서 API_BLOCKED_PREFIXES와도 일치하는 값을 제외하고 허용해요.

값이 API_ALLOWED_PREFIXES 밖에 있으면 명시적으로 차단할 필요가 없어요.

COMMENT = '*string_literal*'

통합에 대한 설명이에요.

Git 저장소용

모든 통합 공통 파라미터 외에도 통합의 API_PROVIDER 파라미터를 git_https_api로 설정해 원격 Git 저장소에 연결할 때 다음 파라미터를 사용해요.

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

UDF 또는 프로시저 핸들러 코드가 API_ALLOWED_PREFIXES 값의 Git 저장소에 접근할 때 사용할 수 있는 시크릿을 지정해요. GIT_CREDENTIALS 파라미터로 Git 자격 증명을 지정할 때 이 목록에서 시크릿을 지정해요.

이 파라미터의 값은 다음 중 하나여야 해요:

  • 나열된 시크릿 중 하나를 허용하려는 완전 정규화된 Snowflake 시크릿 이름 하나 이상.

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

  • 시크릿을 허용하지 않는 none.

ALLOWED_API_AUTHENTICATION_INTEGRATIONS 파라미터도 허용된 시크릿을 지정할 수 있어요. 자세한 내용은 Usage notes를 참고하세요.

시크릿에 대한 참조 정보는 CREATE SECRET을 참고하세요.

API_USER_AUTHENTICATION = ( TYPE = snowflake_github_app | TYPE = OAUTH2 *oauth_parameters* )

OAuth 2.0 흐름에 대한 보안 통합 설정을 지정해요.

이 파라미터를 설정하는 방법은 저장소 제공자에 따라 달라져요. 자세한 내용은 Configure for authenticating with OAuth를 참고하세요.

  • TYPE = snowflake_github_app: Configure for authenticating with OAuth에 설명된 대로 Snowflake GitHub App을 사용해 GitHub로 인증해요. 이 경우 API_USER_AUTHENTICATION에 다른 값은 필요 없어요.

  • TYPE = OAUTH2: Configure for authenticating with OAuth에 설명된 대로 OAuth2 파라미터를 사용해 인증해요.

    이 값을 지정하면 다음 *oauth_parameters* 아래에서 필요에 따라 파라미터도 지정해야 해요.

  • *oauth_parameters*: 다음 파라미터를 포함한 지정된 OAuth 2.0 파라미터를 사용해 인증해요.

OAUTH_CLIENT_ID = '*client_id*'

OAuth2 클라이언트 ID.

OAUTH_CLIENT_SECRET = '*client_secret*'

OAuth2 클라이언트 시크릿.

OAUTH_AUTHORIZATION_ENDPOINT = '*authorization_endpoint_url*'

OAuth2 인증 엔드포인트의 URL.

OAUTH_TOKEN_ENDPOINT = '*token_endpoint_url*'

OAuth2 토큰 엔드포인트의 URL.

OAUTH_SCOPES = ( '*scope*' [, ... ] )

인증에 적용할 OAuth2 범위 목록.

ALLOWED_API_AUTHENTICATION_INTEGRATIONS = ( *name* [, ... ] | all | none )

API 인증 통합을 사용해 자격 증명을 얻을 수 있는 시크릿을 지정해요. 자세한 내용은 Usage notes for external access integrations를 참고하세요.

USE_PRIVATELINK_ENDPOINT = { TRUE | FALSE }

TRUE로 설정하면 Snowflake는 PrivatedLink 엔드포인트를 사용해 Git 저장소에 연결해요. 이 파라미터는 REST API를 사용하는 Snowflake 계정에만 적용돼요.

기본값: FALSE

TLS_TRUSTED_CERTIFICATES = ( *secret_name* [, ... ] )

이가 통합에 비공개(프라이빗/사용자 지정) CA(인증 기관)가 사용되는지 여부를 지정해요. 통합이 비공개 CA를 사용하면 이 목록에 CA 체인을 한 개 이상 추가해 Snowflake가 신뢰하는 인증 기관 목록에 추가해야 해요.

이 값의 시크릿이 없으면 Snowflake의 기본 신뢰 저장소가 사용돼요.

외부 MCP 서버용

TYPE = OAUTH2

표준 OAuth 2.0을 사용해 인증해요. 다음 파라미터를 지정해요:

OAUTH_CLIENT_ID = '*client_id*'

OAuth2 클라이언트 ID.

OAUTH_CLIENT_SECRET = '*client_secret*'

OAuth2 클라이언트 시크릿.

OAUTH_TOKEN_ENDPOINT = '*token_endpoint_url*'

OAuth2 토큰 엔드포인트의 URL.

OAUTH_AUTHORIZATION_ENDPOINT = '*authorization_endpoint_url*'

OAuth2 인증 엔드포인트의 URL.

OAUTH_CLIENT_AUTH_METHOD = { CLIENT_SECRET_BASIC | CLIENT_SECRET_POST | NONE }

클라이언트 인증 방법을 지정해요.

  • CLIENT_SECRET_BASIC: 클라이언트 ID와 시크릿을 HTTP Basic 인증 헤더로 보내요.

  • CLIENT_SECRET_POST: 클라이언트 ID와 시크릿을 폼 본문으로 보내요.

  • NONE: 클라이언트 인증을 사용하지 않아요. OAUTH_CLIENT_SECRET을 생략한 공개 클라이언트에 사용해요.

기본값: CLIENT_SECRET_BASIC

OAUTH_DISCOVERY_URL = '*discovery_url*'

OAuth 2.0 Discovery 문서의 URL. 제공하면 Snowflake가 이 URL에서 발급자, 인증, 토큰 엔드포인트를 감지하고, 명시적으로 지정한 값이 재정의(override)돼요.

OAUTH_REFRESH_TOKEN_VALIDITY = *integer*

리프레시 토큰의 수명(초). 기본값 0은 리프레시 토큰이 만료되지 않는 것으로 취급돼요. 유한한 수명을 원하면 양수 값으로 설정하세요.

TYPE = OAUTH_DYNAMIC_CLIENT

네이티브 클라이언트로 등록(Dynamic Client Registration)하는 OAuth를 사용해 인증해요. 다음 파라미터를 지정해요:

OAUTH_RESOURCE_URL = '*resource_url*'

OAuth 리소스가 있는 서비스의 URL. Snowflake는 이 URL을 사용해 MCP 서버에 연결해요.

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

이 작업을 실행하는 역할은 최소한 다음 권한을 가져야 해요:

Privilege Object Notes
CREATE INTEGRATION Account 기본적으로 ACCOUNTADMIN 역할만 이 권한을 가져요. 필요에 따라 다른 역할에도 부여할 수 있어요.

사용 참고사항 (Usage notes)

  • API 통합을 만들려면 호출자가 계정에 CREATE INTEGRATION 권한이 있어야 해요.

  • 메타데이터에 관해: 고객은 Snowflake 서비스를 사용할 때 메타데이터로 개인 데이터(User 객체 외), 민감 데이터, 수출 통제 데이터 또는 기타 규제 데이터를 입력하지 않도록 해야 해요. 자세한 내용은 Metadata fields in Snowflake를 참고하세요.

  • OR REPLACE와 IF NOT EXISTS 절은 상호 배타적이에요. 같은 문에서 둘 다 사용할 수 없어요.

  • CREATE OR REPLACE <object> 문은 원자적이에요. 즉 객체를 교체할 때 기존 객체가 삭제되고 새 객체가 단일 트랜잭션으로 만들어져요.

예제 (Examples)

Amazon API Gateway

다음 예제는 Amazon API Gateway용 API 통합을 만들어요:

CREATE API INTEGRATION myApiIntegration
  API_PROVIDER = aws_api_gateway
  API_AWS_ROLE_ARN = 'arn:aws:iam::123456789012:role/my_cloud_account_role'
  API_ALLOWED_PREFIXES = ('https://xyz.amazonaws.com/production/')
  API_BLOCKED_PREFIXES = ('https://xyz.amazonaws.com/production/blocked')
  ENABLED = TRUE;

Git 저장소

Git 저장소를 설정하려면 Setting up Snowflake to use Git을 참고하세요.

예를 들어 개인 액세스 토큰으로 GitHub에 인증하는 API 통합을 만들려면 OAuth 대신 시크릿을 사용해요. 개인 액세스 토큰을 사용하면 API_USER_AUTHENTICATION 없이 다음 예제를 사용할 수 있어요:

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

외부 MCP 서버

다음 예제는 OAuth Dynamic Client Registration을 사용해 Atlassian MCP 서버용 API 통합을 만들고, 그다음 그것을 참조하는 외부 MCP 서버 객체를 만들어요.

CREATE API INTEGRATION jira_mcp_api_integration
  API_PROVIDER = external_mcp
  API_ALLOWED_PREFIXES = ('https://mcp.jira.atlassian.com')
  API_USER_AUTHENTICATION = (
    TYPE = OAUTH_DYNAMIC_CLIENT
    OAUTH_RESOURCE_URL = 'https://mcp.atlassian.com/v1/mcp'
  )
  ENABLED = TRUE;

CREATE EXTERNAL MCP SERVER atlassian_mcp_server
  WITH DISPLAY_NAME = 'Atlassian (Jira & Confluence)'
  URL = 'https://mcp.atlassian.com/v1/mcp'
  API_INTEGRATION = jira_mcp_api_integration;

다음 예제는 사용자 지정 MCP 서버에 표준 OAuth 2.0을 사용하고 OAUTH_REFRESH_TOKEN_VALIDITY를 24시간으로 설정해 리프레시 토큰에 유한한 수명을 부여해요(기본값 0은 만료되지 않는 리프레시 토큰으로 취급):

CREATE API INTEGRATION custom_mcp_api_integration
  API_PROVIDER = external_mcp
  API_ALLOWED_PREFIXES = ('https://internal.mycompany.com/mcp')
  API_USER_AUTHENTICATION = (
    TYPE = OAUTH2
    OAUTH_CLIENT_ID = 'your_client_id'
    OAUTH_CLIENT_SECRET = 'your_client_secret'
    OAUTH_TOKEN_ENDPOINT = 'https://internal.mycompany.com/oauth/token'
    OAUTH_CLIENT_AUTH_METHOD = CLIENT_SECRET_BASIC
    OAUTH_AUTHORIZATION_ENDPOINT = 'https://internal.mycompany.com/oauth/authorize'
    OAUTH_REFRESH_TOKEN_VALIDITY = 86400
  )
  ENABLED = TRUE;

다음 예제는 제공자가 발급한 정적 클라이언트 ID로 인증하고 클라이언트 시크릿이 없는 공개 클라이언트에 OAUTH_CLIENT_AUTH_METHOD = NONE을 사용해요:

CREATE API INTEGRATION custom_mcp_integration
  API_PROVIDER = external_mcp
  API_ALLOWED_PREFIXES = ('https://internal.mycompany.com')
  API_USER_AUTHENTICATION = (
    TYPE = OAUTH2
    OAUTH_CLIENT_ID = 'your_static_client_id'
    OAUTH_CLIENT_AUTH_METHOD = NONE
    OAUTH_AUTHORIZATION_ENDPOINT = 'https://internal.mycompany.com/oauth/authorize'
    OAUTH_TOKEN_ENDPOINT = 'https://internal.mycompany.com/oauth/token'
  )
  ENABLED = TRUE;

제공자별 설정 단계와 추가 커넥터(GitHub, Glean, Linear, Salesforce)는 MCP Connectors를 참고하세요.

더 알아보기 (Learn more)

ALTER API INTEGRATION, DROP INTEGRATION, SHOW INTEGRATIONS, Writing external functions, CREATE EXTERNAL FUNCTION