CREATE EXTERNAL ACCESS INTEGRATION

UDF 또는 프로시저 처리기에서 외부 네트워크 위치에 액세스하기 위한 외부 액세스 통합 을 만듭니다.

참고 항목:

ALTER EXTERNAL ACCESS INTEGRATION , DROP INTEGRATION , SHOW INTEGRATIONS , DESCRIBE INTEGRATION

구문

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

필수 매개 변수

name

외부 액세스 통합을 위한 식별자입니다.

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

자세한 내용은 식별자 요구 사항 섹션을 참조하십시오.

ALLOWED_NETWORK_RULES = (rule_name [ , rule_name ... ])

허용되는 네트워크 규칙 을 지정합니다. 송신 규칙만 지정할 수 있습니다.

ENABLED = { TRUE | FALSE }

이 통합의 활성화 여부를 지정합니다. 통합이 비활성화되면 이에 의존하는 모든 처리기 코드가 외부 네트워크 위치에 연결할 수 없게 됩니다.

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

기본값은 TRUE 입니다.

선택적 매개 변수

ALLOWED_API_AUTHENTICATION_INTEGRATIONS = ( integration_name_1 [, integration_name_2, ... ] | none )

OAuth 인증 서버가 UDF 또는 프로시저에서 사용하는 시크릿을 발급한 보안 통합을 지정합니다. 보안 통합은 외부 API 통합에 사용되는 유형 이어야 합니다.

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

  • 나열된 모든 통합을 허용하려면 하나 이상의 Snowflake 보안 통합 이름이 필요합니다.

  • 통합을 허용하지 않으려면 none.

이 매개 변수에 의해 지정된 보안 통합과 ALLOWED_AUTHENTICATION_SECRETS 매개 변수로 지정된 시크릿은 이 외부 액세스 통합을 사용하는 UDF 또는 프로시저에서 시크릿을 사용할 수 있도록 허용하는 방법입니다. 자세한 내용은 사용법 노트 섹션을 참조하십시오.

보안 통합에 대한 참조 정보는 CREATE SECURITY INTEGRATION(External API 인증) 섹션을 참조하십시오.

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

허용된 네트워크 규칙에 참조된 외부 네트워크 위치에 액세스할 때 UDF 또는 프로시저 핸들러 코드가 사용할 수 있는 시크릿을 지정합니다.

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

  • 나열된 시크릿을 허용하기 위한 하나 이상의 Snowflake 시크릿 이름입니다.

  • 시크릿을 허용하려면 all.

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

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

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

COMMENT = 'string_literal'

외부 액세스 통합에 대한 설명을 지정합니다.

기본값: 값 없음

액세스 제어 요구 사항

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

권한

오브젝트

참고

CREATE INTEGRATION

계정

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

USAGE

시크릿

통합에서 참조하는 모든 시크릿에 필요합니다.

USAGE

스키마

통합에서 참조하는 시크릿을 포함하는 모든 스키마에 필요합니다.

CREATE EXTERNAL ACCESS INTEGRATION

계정

외부 액세스 통합을 생성할 수 있는 권한을 부여합니다. 이 권한은 다른 타입의 통합을 생성할 수 있는 권한을 부여하지 않습니다.

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

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

사용법 노트

  • 아래에 설명된 대로 두 개의 외부 액세스 통합 매개 변수를 사용하여 UDF 또는 프로시저에서 시크릿을 사용하도록 허용할 수 있습니다.

    • ALLOWED_AUTHENTICATION_SECRETS 매개 변수 포함. 매개 변수 값으로 시크릿을 지정하거나 매개 변수 값을 all 로 설정하여 핸들러 코드가 모든 시크릿을 사용할 수 있도록 할 수 있습니다.

    • ALLOWED_API_AUTHENTICATION_INTEGRATIONS 매개 변수 포함. 시크릿 자체에 이 매개 변수로 이름이 지정된 보안 통합을 지정하는 경우 시크릿 을 사용할 수 있습니다. 시크릿은 API_AUTHENTICATION 매개 변수와 보안 통합을 지정합니다. 즉, 시크릿과 외부 액세스 통합이 모두 보안 통합을 지정하는 경우 시크릿은 외부 액세스 통합을 지정하는 함수 및 프로시저에서 사용할 수 있습니다.

    이 두 가지 대안은 서로 독립적으로 작동한다는 점에 유의하십시오. 매개 변수 중 하나(또는 둘 다)가 허용하는 경우 시크릿은 허용되며, 다른 매개 변수에 지정된 값과 관계가 없습니다. 예를 들어, 매개 변수 중 하나를 none 으로 설정해도 다른 매개 변수에 지정된 시크릿이 핸들러 코드에서 사용되는 것을 방지할 수 없습니다.

  • 호스트 이름을 사용하여 네트워크 규칙을 지정할 수 있는 반면, Snowflake는 IP 수준의 세분성으로 규칙을 적용합니다. Snowflake는 애플리케이션의 트래픽을 검사하지 않으므로, 외부 위치의 호스트에 진정한 서비스가 있는지, 동일한 호스트의 다른 서비스에 연결할 수 없는지 확인하는 것은 사용자 본인의 책임입니다. 가능하면 인터넷 엔드포인트와 통신할 때 HTTPS 및 TLS와 같은 보안 프로토콜을 사용해야 합니다.

  • 메타데이터 관련:

    주의

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

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

예

Google Translation API에 대한 액세스를 제공하는 외부 액세스 통합을 생성합니다.

더 완전한 예를 보려면 외부 액세스 통합 생성 및 사용하기 섹션을 참조하십시오.

  1. 자격 증명을 나타내는 시크릿을 만듭니다.

    현재 스키마에 대해 CREATE SECRET 권한이 있는 역할이 할당되어 있어야 시크릿을 생성할 수 있습니다. 이 명령이 지원하는 다른 종류의 시크릿은 CREATE SECRET 섹션을 참조하십시오. 이 예에서 google_translate_oauth 는 보안 통합을 가리킵니다. 자세한 내용은 CREATE SECURITY INTEGRATION(External API 인증) 섹션을 참조하십시오.

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

  2. UDF 개발자가 사용할 수 있도록 시크릿에 대한 READ 권한을 developer 역할에 부여합니다.

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

    USE ROLE USERADMIN;
CREATE OR REPLACE ROLE developer;
    Copy

    developer 역할에 READ 권한을 부여합니다.

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

  3. 외부 네트워크 위치를 나타내는 네트워크 규칙을 만듭니다. 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');
    Copy

  4. 시크릿 및 네트워크 규칙을 사용하여 외부 액세스 통합을 만듭니다.

    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;
    Copy

  5. UDF 개발자가 사용할 수 있도록 통합에 대한 USAGE 권한을 developer 역할에 부여합니다.

    GRANT USAGE ON INTEGRATION google_apis_access_integration TO ROLE developer;
    Copy

  6. 지정된 텍스트를 지정된 언어의 문구로 번역하는 UDF google_translate_python 을 만듭니다. 자세한 내용은 함수 또는 프로시저에서 외부 액세스 통합 사용하기 섹션을 참조하십시오.

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

  7. 사용자 역할을 가진 사용자가 호출할 수 있도록 google_translate_python 함수에 대한 USAGE 권한을 부여합니다.

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

  8. google_translate_python 함수를 실행하여 문구를 번역합니다.

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

    그러면 다음과 같은 출력이 생성됩니다.

    -------------------------------------------------------
| GOOGLE_TRANSLATE_PYTHON('HAPPY THURSDAY!', 'ZH-CN') |
-------------------------------------------------------
| 快乐星期四！                                          |
-------------------------------------------------------
언어: 한국어