CREATE EXTERNAL ACCESS INTEGRATION

UDF 또는 프로시저 핸들러에서 외부 네트워크 위치로의 접근을 위해 외부 접근 인티그레이션(external access integration)을 만드는 명령이에요.

출처: 문서

본문

UDF 또는 프로시저 핸들러에서 외부 네트워크 위치로의 접근을 위해 외부 접근 인티그레이션을 만들어요.

함께 보기: ALTER EXTERNAL ACCESS INTEGRATION, DROP INTEGRATION, SHOW INTEGRATIONS, DESCRIBE INTEGRATION

구문 (Syntax)

CREATE [ OR REPLACE ] EXTERNAL ACCESS INTEGRATION <name>
  ALLOWED_NETWORK_RULES = ( <rule_name_1> [, <rule_name_2>, ... ] )
  [ ALLOWED_API_AUTHENTICATION_INTEGRATIONS = { ( <integration_name_1> [, <integration_name_2>, ... ] ) | none } ]
  [ ALLOWED_AUTHENTICATION_SECRETS = { ( <secret_name_1> [, <secret_name_2>, ... ] ) | all | none } ]
  ENABLED = { TRUE | FALSE }
  [ COMMENT = '<string_literal>' ]

필수 매개변수 (Required parameters)

name 외부 접근 인티그레이션의 식별자예요.

식별자 값은 반드시 알파벳 문자로 시작해야 하며, 전체 식별자 문자열이 큰따옴표로 묶이지 않는 한 공백이나 특수 문자를 포함할 수 없어요 (예: "My object"). 큰따옴표로 묶인 식별자는 대소문자를 구분해요.

자세한 내용은 식별자 요구 사항(Identifier requirements)을 참고해요.

ALLOWED_NETWORK_RULES = (rule_name [ , rule_name ... ]) 허용되는 네트워크 규칙을 지정해요. 이그레스(egress) 규칙만 지정할 수 있어요.

ENABLED = { TRUE | FALSE } 이 인티그레이션이 활성화될지 비활성화될지 지정해요. 인티그레이션이 비활성화되면 그것에 의존하는 핸들러 코드는 외부 네트워크 위치에 도달할 수 없어요.

값은 대소문자를 구분하지 않아요. 기본값은 TRUE예요.

선택 매개변수 (Optional parameters)

ALLOWED_API_AUTHENTICATION_INTEGRATIONS = ( integration_name_1 [, integration_name_2, ... ] ) | none UDF 또는 프로시저가 사용하는 시크릿을 발급한 OAuth 인가 서버인 보안 인티그레이션을 지정해요. 보안 인티그레이션은 외부 API 인티그레이션에 사용되는 유형이어야 해요.

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

나열된 인티그레이션 중 하나를 허용할 하나 이상의 Snowflake 보안 인티그레이션 이름
인티그레이션을 허용하지 않으려면 none

이 매개변수가 지정하는 보안 인티그레이션 — 그리고 ALLOWED_AUTHENTICATION_SECRETS 매개변수가 지정하는 시크릿 — 은 이 외부 접근 인티그레이션을 사용하는 UDF 또는 프로시저에서 시크릿 사용을 허용하는 방법이에요. 자세한 내용은 사용 메모를 참고해요.

보안 인티그레이션에 대한 참조 정보는 CREATE SECURITY INTEGRATION (External API Authentication)을 참고해요.

ALLOWED_AUTHENTICATION_SECRETS = ( secret_name [, secret_name ... ] ) | all | none UDF 또는 프로시저 핸들러 코드가 허용된 네트워크 규칙에 참조된 외부 네트워크 위치에 접근할 때 사용할 수 있는 시크릿을 지정해요.

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

나열된 시크릿 중 하나를 허용할 하나 이상의 Snowflake 시크릿 이름
어떤 시크릿이든 허용할 all
시크릿을 허용하지 않으려면 none

ALLOWED_API_AUTHENTICATION_INTEGRATIONS 매개변수도 허용되는 시크릿을 지정할 수 있어요. 자세한 내용은 사용 메모를 참고해요.

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

COMMENT = 'string_literal' 외부 접근 인티그레이션에 대한 설명(comment)을 지정해요.

기본값: 값 없음

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

이 작업을 실행하는 데 사용하는 역할(role)은 최소한 다음 권한을 가져야 해요.

권한 (Privilege)	객체 (Object)	비고
CREATE INTEGRATION	Account	기본적으로 ACCOUNTADMIN 역할만 이 권한을 가져요. 필요에 따라 추가 역할에 부여될 수 있어요.
USAGE	Secret	인티그레이션이 참조하는 모든 시크릿에 필요해요.
USAGE	Schema	인티그레이션이 참조하는 시크릿을 포함하는 모든 스키마에 필요해요.
CREATE EXTERNAL ACCESS INTEGRATION	Account	외부 접근 인티그레이션을 만들 수 있는 권한을 부여해요. 이 권한은 다른 유형의 인티그레이션을 만들 수 있는 권한은 부여하지 않아요.

지정된 권한 집합으로 사용자 지정 역할을 만드는 방법은 사용자 지정 역할 만들기(Creating custom roles)를 참고해요. 보호 가능한 객체에 대해 SQL 작업을 수행하기 위한 역할과 권한 부여의 일반적인 내용은 접근 제어 개요(Overview of Access Control)를 참고해요.

사용 메모 (Usage notes)

아래에 설명된 대로 두 개의 외부 접근 인티그레이션 매개변수로 UDF 또는 프로시저가 사용할 시크릿을 허용할 수 있어요.

ALLOWED_AUTHENTICATION_SECRETS 매개변수 사용. 시크릿을 매개변수 값으로 지정하거나 매개변수 값을 all로 설정해 핸들러 코드가 모든 시크릿을 사용하도록 할 수 있어요.
ALLOWED_API_AUTHENTICATION_INTEGRATIONS 매개변수 사용. 시크릿 자체가 이 매개변수도 지정한 이름의 보안 인티그레이션을 지정하면 그 시크릿이 사용 허용돼요. 시크릿은 API_AUTHENTICATION 매개변수로 보안 인티그레이션을 지정해요. 즉, 시크릿과 외부 접근 인티그레이션 모두 보안 인티그레이션을 지정할 때, 그 시크릿은 외부 접근 인티그레이션을 지정하는 함수와 프로시저에서 사용 허용돼요.

이 두 대안은 서로 독립적으로 동작한다는 점에 주의해요. 다른 매개변수의 값과 관계없이 두 매개변수 중 하나(또는 둘 다)가 허용하면 시크릿이 허용돼요. 예를 들어 한 매개변수를 none으로 설정해도 다른 매개변수가 지정한 시크릿이 핸들러 코드에서 사용되는 것을 막지 않아요.

네트워크 규칙을 호스트 이름으로 지정할 수 있지만, Snowflake는 IP 수준의 세분성에서 규칙을 강제해요. Snowflake는 애플리케이션의 트래픽을 검사하지 않으므로, 외부 위치의 호스트가 진짜 서비스를 제공하고 같은 호스트의 다른 서비스에 연결할 수 없는지 확인하는 것은 사용자의 책임이에요. 가능할 때마다 인터넷 엔드포인트와 통신할 때는 HTTPS와 TLS 같은 안전한 프로토콜을 사용해야 해요.

메타데이터에 관해서는 다음 사항에 주의해요.

⚠️ 주의: 고객은 Snowflake 서비스를 사용할 때 (User 객체를 제외하고) 개인 데이터·민감 데이터·수출 통제 데이터·기타 규제 데이터를 메타데이터로 입력하지 않도록 해야 해요. 자세한 내용은 Snowflake의 메타데이터 필드를 참고해요.

CREATE OR REPLACE <object> 문은 원자적(atomic)으로 동작해요. 즉, 객체를 교체할 때 기존 객체는 삭제되고 새 객체는 단일 트랜잭션 안에서 생성돼요.

예시 (Examples)

Google 번역 API에 대한 접근을 제공하는 외부 접근 인티그레이션을 만들어요. 더 완전한 예시는 외부 접근 인티그레이션 만들기와 사용(Creating and using an external access integration)을 참고해요.

자격 증명을 나타내는 시크릿을 만들어요.

시크릿을 만들려면 현재 스키마에 CREATE SECRET 권한이 있는 역할을 할당받아야 해요. 이 명령이 지원하는 다른 종류의 시크릿은 CREATE SECRET을 참고해요. 이 예시에서 google_translate_oauth는 보안 인티그레이션을 가리켜요. 자세한 내용은 CREATE SECURITY INTEGRATION (External API Authentication)을 참고해요.

CREATE OR REPLACE SECRET oauth_token
  TYPE = OAUTH2
  API_AUTHENTICATION = google_translate_oauth
  OAUTH_REFRESH_TOKEN = 'my-refresh-token';

시크릿을 사용할 UDF 개발자가 사용할 수 있도록 developer 역할에 READ 권한을 부여해요.

시크릿을 사용해야 하는 개발자에게 필요한 역할을 만들어요.

USE ROLE USERADMIN;
CREATE OR REPLACE ROLE developer;

developer 역할에 READ 권한을 부여해요.

USE ROLE SECURITYADMIN;
GRANT READ ON SECRET oauth_token TO ROLE developer;

외부 네트워크 위치를 나타내는 네트워크 규칙을 만들어요. CREATE NETWORK RULE에 설명된 권한이 있는 역할을 사용해요.

USE ROLE SYSADMIN;
CREATE OR REPLACE NETWORK RULE google_apis_network_rule
  MODE = EGRESS
  TYPE = HOST_PORT
  VALUE_LIST = ('translation.googleapis.com');

시크릿과 네트워크 규칙을 사용해 외부 접근 인티그레이션을 만들어요.

USE ROLE ACCOUNTADMIN;
CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION google_apis_access_integration
  ALLOWED_NETWORK_RULES = (google_apis_network_rule)
  ALLOWED_AUTHENTICATION_SECRETS = (oauth_token)
  ENABLED = true;

UDF 개발자가 사용할 수 있도록 인티그레이션에 대한 USAGE 권한을 developer 역할에 부여해요.

GRANT USAGE ON INTEGRATION google_apis_access_integration TO ROLE developer;

지정된 텍스트를 지정된 언어의 문구로 번역하는 google_translate_python UDF를 만들어요. 자세한 내용은 함수 또는 프로시저에서 외부 접근 인티그레이션 사용(Using the external access integration in a function or procedure)을 참고해요.

USE ROLE developer;

CREATE OR REPLACE FUNCTION google_translate_python(sentence STRING, language STRING)
RETURNS STRING
LANGUAGE PYTHON
RUNTIME_VERSION = 3.10
HANDLER = 'get_translation'
EXTERNAL_ACCESS_INTEGRATIONS = (google_apis_access_integration)
PACKAGES = ('snowflake-snowpark-python','requests')
SECRETS = ('cred' = oauth_token )
AS
$$
import _snowflake
import requests
import json
session = requests.Session()
def get_translation(sentence, language):
  token = _snowflake.get_oauth_access_token('cred')
  url = "https://translation.googleapis.com/language/translate/v2"
  data = {'q': sentence,'target': language}
  response = session.post(url, json = data, headers = {"Authorization": "Bearer " + token})
  return response.json()['data']['translations'][0]['translatedText']
$$;

user 역할을 가진 사람이 호출할 수 있도록 google_translate_python 함수에 USAGE 권한을 부여해요.

GRANT USAGE ON FUNCTION google_translate_python(string, string) TO ROLE user;

문구를 번역하도록 google_translate_python 함수를 실행해요.

USE ROLE user;
SELECT google_translate_python('Happy Thursday!', 'zh-CN');

이는 다음 출력을 생성해요.

-------------------------------------------------------
| GOOGLE_TRANSLATE_PYTHON('HAPPY THURSDAY!', 'ZH-CN') |
-------------------------------------------------------
| 快乐星期四！                                          |
-------------------------------------------------------

더 알아보기 (Learn more)

외부 접근 인티그레이션 만들기와 사용 — 전체 예시
ALTER EXTERNAL ACCESS INTEGRATION — 외부 접근 인티그레이션 수정
SHOW INTEGRATIONS — 인티그레이션 조회