외부 액세스 통합 생성 및 사용하기

특정 외부 네트워크 위치에 대한 액세스를 활성화하기 위해 외부 위치를 지정하는 네트워크 규칙 목록과 사용하도록 허용된 시크릿 목록을 지정하는 외부 액세스 통합을 생성합니다. CREATE FUNCTION 또는 CREATE PROCEDURE로 UDF 또는 프로시저를 생성할 때 EXTERNAL_ACCESS_INTEGRATIONS 절을 사용하여 이 통합을 참조함으로써 처리기 코드가 시크릿을 사용하여 외부 위치에 인증하도록 허용할 수 있습니다.

관리자는 EXTERNAL_ACCESS_HISTORY 뷰를 사용하여 외부 네트워크 위치에 대한 요청을 모니터링할 수 있습니다.

외부 액세스를 설정하고 사용하는 데 활용할 수 있는 코드 예의 전체 시퀀스는 외부 네트워크 액세스 예시 섹션을 참조하십시오.

UDF 또는 프로시저에서 외부 네트워크 위치에 대한 액세스를 설정하려면 다음 단계를 따르십시오.

  1. 외부 네트워크 위치를 나타내는 네트워크 규칙을 만듭니다.

  2. 자격 증명 유지를 위한 시크릿을 만듭니다.

  3. 외부 위치에 액세스할 때 처리기에서 사용할 수 있도록 시크릿과 네트워크 규칙을 집계하여 외부 액세스 통합을 만듭니다.

  4. 값으로 나타낸 통합 이름으로 설정된 EXTERNAL_ACCESS_INTEGRATIONS 매개 변수로 UDF 또는 프로시저를 생성합니다. 이를 통해 외부 네트워크 위치에 액세스하고 통합에서 네트워크 규칙과 시크릿으로 지정된 자격 증명을 사용할 수 있는 함수 또는 프로시저 권한을 부여합니다.

    처리기 코드에서 시크릿의 내용에 액세스할 수 있도록 SECRET 매개 변수를 통합에 포함된 시크릿 이름으로 따로 설정합니다.

    함수 또는 프로시저 처리기 코드에서 통합에 포함된 네트워크 규칙에 지정된 외부 네트워크 위치에 액세스합니다. 허용된 네트워크 규칙에 지정되지 않은 네트워크 위치에 대한 액세스 시도는 거부됩니다.

외부 네트워크 위치를 나타내는 네트워크 규칙 만들기

CREATE NETWORK RULE 명령을 사용하여 외부 네트워크의 위치와 액세스 제한을 나타내는 네트워크 규칙을 만들 수 있습니다. 예를 들어 네트워크 규칙에서는 호스트 이름, 네트워크와의 통신 방향(수신 또는 송신)과 같은 네트워크 식별자를 지정합니다.

외부 네트워크에 대한 액세스를 지원하기 위해 관리자는 외부 액세스 통합 을 생성할 때 규칙을 포함합니다. 통합에 포함된 각 규칙은 함수 또는 프로시저가 액세스하도록 허용되는 외부 네트워크 위치를 지정합니다.

외부 액세스 통합에 사용할 네트워크 규칙을 생성할 때 다음을 지정합니다.

  • EGRESS를 MODE 매개 변수 값으로 지정합니다.

  • HOST_PORT를 TYPE 매개 변수 값으로 지정합니다.

  • VALUE_LIST 매개 변수에 외부 위치의 엔드포인트를 지정합니다.

  • (선택 사항) 외부 위치의 엔드포인트 이름을 포함한 포트 번호를 지정합니다. 포트 번호를 생략하면 Snowflake는 외부 액세스에 기본 포트 번호인 443을 사용합니다.

    예를 들어 엔드포인트에 포트 80이 필요한 경우 VALUE_LIST 매개 변수는 다음과 같을 수 있습니다.

    VALUE_LIST = ('example.com:80')
    
    Copy

액세스 제어

보안을 위해 Snowflake에서는 네트워크 규칙을 생성할 때 다음을 보유한 역할을 사용해야 합니다.

  • 규칙을 보유할 스키마에 대한 CREATE NETWORK RULE 권한입니다.

다음 예시의 코드는 Google Translation API에 대한 아웃바운드 요청에 대해 google_apis_network_rule 이라는 네트워크 규칙을 만듭니다.

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

자격 증명을 나타내는 시크릿 만들기

CREATE SECRET 을 사용하여 외부 네트워크 위치로 인증하는 데 필요한 자격 증명을 나타내는 시크릿을 만들 수 있습니다. 예를 들어, 시크릿에는 사용자 이름, 비밀번호 등의 자격 증명이 포함될 수 있습니다.

OAuth를 지원하는 외부 네트워크 위치에 액세스하려면 클라이언트 ID, 클라이언트 시크릿, 토큰 엔드포인트 등 OAuth 흐름에 필요한 값이 포함된 보안 통합 에 대한 참조를 시크릿에 포함하는 것이 가장 좋습니다.

시크릿은 다음과 같은 방식으로 사용됩니다.

  • 관리자가 외부 액세스 통합 을 생성할 때 사용합니다.

    통합 생성 시, 관리자는 개발자가 통합을 사용하는 함수나 프로시저를 생성할 때 처리기 코드에서 사용할 수 있는 시크릿을 지정합니다.

  • 개발자가 UDF 또는 프로시저 처리기를 생성할 때 사용합니다.

    개발자는 처리기 코드가 외부 위치에 대한 요청을 할 때 인증하는 데 사용할 수 있는 자격 증명이 포함된 허용된 시크릿을 지정합니다. 처리기를 작성할 때 개발자는 처리기 코드에 자격 증명을 리터럴 값으로 포함하는 대신 Snowflake API를 사용하여 시크릿에 포함된 자격 증명을 검색할 수 있습니다.

참고

새로 고침 토큰이 필요한 OAuth 시크릿의 경우 Snowflake에서 사용 가능한 시스템 함수를 통하는 방법을 포함하여 여러 방법으로 토큰을 얻을 수 있습니다. 예를 보려면 Google Translate API에 액세스하기 를 참조하십시오.

액세스 제어

보안을 위해 Snowflake에서는 시크릿을 생성할 때 다음을 보유한 역할을 사용해야 합니다.

  • 시크릿을 보유할 스키마에 대한 CREATE SECRET 권한.

다음 예시의 코드는 OAuth를 사용하여 인증하는 데 필요한 값이 포함된 보안 통합(google_translate_oauth 로 표시됨)을 지정하는 oauth_token 이라는 시크릿을 생성합니다.

보안 통합 생성을 위한 코드를 포함한 더 완전한 예는 외부 네트워크 액세스 예시 섹션을 참조하십시오.

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

이 미리 보기에서는 API 키를 자격 증명으로만 사용하려는 경우 TYPEGENERIC_STRING 으로 지정할 수 있습니다.

CREATE OR REPLACE SECRET bp_maps_api
  TYPE = GENERIC_STRING
  SECRET_STRING = 'replace-with-your-api-key';
Copy

외부 액세스 통합 만들기

CREATE EXTERNAL ACCESS INTEGRATION 명령을 사용하여 UDF 및 프로시저와 함께 사용하도록 허용된 네트워크 규칙(외부 네트워크 위치를 나타냄)과 허용된 시크릿(인증을 위한 자격 증명을 나타냄)을 집계하는 외부 액세스 통합을 생성할 수 있습니다.

특히, 외부 액세스 통합은 통합을 참조하는 UDF 및 프로시저가 사용할 수 있는 네트워크 규칙과 시크릿을 지정합니다.

외부 액세스 통합은 관리자가 UDF와 프로시저에서 외부 네트워크 위치에 대한 액세스를 관리하는 데 사용됩니다. 통합은 통합을 참조하는 UDF와 프로시저에서 사용하도록 허용된 위치와 자격 증명만 지정합니다. 관리자는 외부 위치에 대한 액세스를 관리하기 위해 통합을 활성화하거나 비활성화할 수도 있습니다.

액세스 제어

보안을 위해 Snowflake에서는 외부 액세스 통합을 생성할 때 다음을 보유한 역할을 사용해야 합니다.

  • 계정에 대한 CREATE INTEGRATION 권한.

  • 통합에서 사용하는 모든 시크릿에 대한 USAGE 권한과 시크릿의 스키마에 대한 USAGE 권한.

다음 예시의 코드는 google_apis_access_integration 이라는 외부 액세스 통합을 만듭니다. 통합은 google_apis_network_rule 네트워크 규칙(네트워크 위치를 나타냄)과 oauth_token 시크릿(자격 증명을 나타냄)을 지정합니다.

이 규칙과 시크릿에 대한 자세한 내용은 외부 네트워크 위치를 나타내는 네트워크 규칙 만들기자격 증명을 나타내는 시크릿 만들기 섹션을 참조하십시오.

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

함수 또는 프로시저에서 외부 액세스 통합 사용하기

CREATE FUNCTION 또는 CREATE PROCEDURE 명령을 사용하여 UDF 또는 프로시저를 생성할 때 다음과 같이 외부 네트워크 위치에 대한 액세스를 활성화할 수 있습니다.

  • EXTERNAL_ACCESS_INTEGRATIONS 매개 변수의 값을 하나 이상의 통합으로 설정하여 이 매개 변수를 포함합니다.

    여기서 지정하는 각 통합은 통합이 지정하는 외부 네트워크 위치와 시크릿에 대한 액세스를 허용합니다.

  • SECRETS 매개 변수의 값을 하나 이상의 시크릿과 처리기 코드에서 액세스하는 데 사용할 이름으로 설정하여 이 매개 변수를 포함합니다.

    값으로 지정하는 시크릿은 외부 액세스 통합에서도 지정해야 합니다.

  • 처리기 코드에서 시크릿에 액세스하여 외부 네트워크 위치로 인증하기 위한 자격 증명을 불러옵니다.

참고

코드에 자격 증명을 리터럴 값으로 포함하는 대신 항상 자격 증명을 나타내는 Snowflake 시크릿을 사용하십시오. 자격 증명을 보호하는 것 외에도, 시크릿을 사용하면 시크릿에 대한 READ 권한이 부여된 사용자만 UDF 또는 프로시저에 이 권한이 포함된 통합을 사용할 수 있으므로 자격 증명 사용을 감사하고 관리할 수 있습니다.

Snowflake는 특정 UDF에서 만들 수 있는 총 연결 수를 제한합니다. 리소스 고갈 문제가 발생하지 않도록 하려면 연결을 최대한 많이 재사용하십시오. UDF 초기화 중에 TCP 클라이언트 또는 세션을 한 번 만든 다음 나머지 쿼리에 대해 UDF 처리기에서 클라이언트나 세션을 사용하면 최대한 많이 재사용할 수 있습니다.

액세스 제어

보안을 위해 Snowflake에서는 UDF 또는 프로시저를 생성할 때 다음을 보유한 역할을 사용해야 합니다.

  • 참조하는 모든 시크릿에 대한 READ 권한과 시크릿의 스키마에 대한 USAGE 권한.

  • 참조하는 모든 통합에 대한 USAGE 권한.

이러한 권한을 요구함으로써 관리자가 외부 액세스를 활성화할 수 있는 사용자로 구성된 세트를 관리할 수 있습니다. 자세한 내용은 GRANT <권한>액세스 제어 권한 섹션을 참조하십시오.

다음 예시의 코드는 google_apis_access_integration 이라는 외부 액세스 통합을 지정하여 google_translate_python 이라는 UDF를 생성합니다(자세한 내용은 외부 액세스 통합 만들기 참조). 통합은 통합을 참조하는 UDF에서 사용하도록 허용된 네트워크 규칙(외부 네트워크 위치를 나타냄)과 시크릿(자격 증명을 나타냄)을 지정합니다. 이 규칙과 시크릿에 대한 자세한 내용은 외부 네트워크 위치를 나타내는 네트워크 규칙 만들기자격 증명을 나타내는 시크릿 만들기 섹션을 참조하십시오.

Python 처리기 코드는 _snowflake.get_oauth_access_token 함수를 사용하여 시크릿에서 OAuth 토큰을 불러온 다음 그 토큰을 사용해 외부 위치로 인증합니다. 처리기 코드는 지정된 URL에 요청할 수 있는데, URL의 호스트가 통합에서 지정한 네트워크 규칙에 나열되어 있기 때문입니다.

CREATE OR REPLACE FUNCTION google_translate_python(sentence STRING, language STRING)
RETURNS STRING
LANGUAGE PYTHON
RUNTIME_VERSION = 3.8
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