2단계: 콘솔에서 프록시 서비스(Google Cloud API Gateway) 만들기

2단계: 콘솔에서 프록시 서비스(Google Cloud API Gateway) 만들기 (Step 2: Create the proxy service)

Snowflake는 데이터(HTTP POST 요청)를 원격 서비스에 직접 보내지 않아요. 대신 Snowflake는 프록시 서비스(proxy service)에 데이터를 보내고, 프록시 서비스가 데이터를 원격 서비스(즉 GCP Cloud Function)로 중계했다가 다시 받아 돌려주는 구조예요. 이 문서는 외부 함수의 프록시 서비스로 사용할 Google Cloud API Gateway를 만들고 구성하는 방법을 안내합니다.

출처: Snowflake SQL Reference

본문

이전 단계

1단계: 콘솔에서 원격 서비스(Google Cloud Function)를 만듭니다.

관련 Google 문서 링크

이 문서에서 설명하는 작업을 Google Cloud Console로 수행하는 방법에 대한 더 자세한 내용은 "Quickstart for Deploying an API/API Gateway using the Google Cloud Console"의 다음 섹션을 참고하세요:

  • API 정의 만들기 (Creating an API definition)
  • 게이트웨이 만들기 (Creating a gateway)

Google Cloud Console 대신 명령줄을 사용하고 싶다면 "Quickstart for Deploying an API/API Gateway using gcloud"의 다음 섹션을 참고하세요:

  • API 만들기 (Creating an API)
  • API 구성 만들기 (Creating an API config)
  • 게이트웨이에 API 배포하기 (Deploy an API to a gateway)

Google 문서를 사용할 때는 필요한 정보(예: Gateway URL)를 반드시 추적 워크시트에 복사해 두세요.

API 정의 만들기 (Create an API definition)

로컬 파일 시스템에, 만드는 API를 지정하는 YAML 형식의 구성 파일을 만들고 사용자에 맞게 수정하세요. 파일 확장자는 .yaml 또는 .yml이어야 해요.

구성 파일 템플릿:

swagger: '2.0'
info:
 title: API Gateway config for Snowflake external function.
 description: This configuration file connects the API Gateway resource to the remote service (Cloud Function).
 version: 1.0.0
schemes:
 - https
produces:
 - application/json
paths:
 /:
 post:
 summary: Echo the input.
 operationId: echo
 x-google-backend:
 address: 
 protocol: h2
 responses:
 '200':
 description: 
 schema:
 type: string

다음 필드를 채우거나 갱신하세요:

  • 를 고유한 이름으로 바꾸세요. 이 값은 URL에 포함되므로 URL에서 유효한 문자만 사용해야 해요. 예를 들어 `demo-func-resource`라고 입력합니다. 이 구성 파일의 다른 필드와 달리 값은 콜론 뒤가 아니라 콜론 앞에 입력한다는 점에 주의하세요. 예를 들어 다음과 같이 입력하면 올바릅니다:
paths:
 /demo-func-resource:

경로 이름에는 경로 파라미터(path parameter)를 포함하면 안 돼요. Google은 URL로 경로를 설정할 때 경로 파라미터를 지원하지만, Snowflake는 CREATE EXTERNAL FUNCTION 문에서 지정하는 해당 URL의 경로 파라미터를 지원하지 않아요.

  • 바로 앞 단계에서 복사한 경로(예: demo-func-resource)를 추적 워크시트의 Path Suffix 필드에 기록하세요.

  • x-google-backend 필드 아래의 address 필드를 찾아서, ``를 추적 워크시트의 Cloud Function Trigger URL 필드 값으로 바꾸세요. 결과는 대략 다음과 같아야 해요:

x-google-backend:
 address: https:// ...

URL은 따옴표로 묶지 않아야 해요. URL이 Google이 호스팅하는 엔드포인트일 필요는 없으며, 모든 HTTP 엔드포인트의 경로여도 괜찮아요. Step 1(콘솔에서 원격 서비스(Google Cloud Function) 만들기)에서 Require HTTPS를 선택했다면 address 필드에 입력하는 URL이 https로 시작하는지 확인하세요.

  • 선택적으로 다음 값 중 일부를 갱신할 수 있어요:

    • info 섹션의 title
    • info 섹션의 description
    • paths 섹션 post 하위 섹션의 operationId
    • paths 섹션 post 하위 섹션의 summary

  • 샘플 구성 파일을 검토하세요. 대략 다음과 같아야 해요:

swagger: '2.0'
info:
 title: "API Gateway config for Snowflake external function"
 description: "This configuration file connects the API Gateway resource to the remote service (Cloud Function)."
 version: 1.0.0
schemes:
 - https
produces:
 - application/json
paths:
 /demo-func-resource:
 post:
 summary: "echo the input"
 operationId: echo
 x-google-backend:
 address: https://my_dev.cloudfunctions.net/demo-cloud-function-01
 protocol: h2
 responses:
 '200':
 description: echo result
 schema:
 type: string

참고: 이 구성은 이 튜토리얼의 Step 5(콘솔에서 프록시 서비스용 GCP 보안 정책 만들기)에서 보안을 설정하기 전까지 여러분의 게이트웨이를 공개(public) 상태로 열어 두게 해요.

  • 선택적으로, 그 사이에 아무도 여러분의 게이트웨이를 사용하지 못하게 하려면 구성 파일에 임시의 유효하지 않은 서비스 계정 이름(google_service_account)을 사용한 보안 정의를 아래의 선택 단계 설명대로 추가할 수 있어요. 이 단계에서 보안 정의를 추가하면, Step 5(콘솔에서 프록시 서비스용 GCP 보안 정책 만들기)에서 보안 구성을 마칠 때까지 외부 함수를 테스트할 수 없어요. 특히 Step 4(Snowflake에서 GCP용 외부 함수 만들기)에서 외부 함수를 테스트하라는 지시가 아직은 동작하지 않아요.

구성 파일의 schemes 섹션 바로 위, 같은 들여쓰기 수준에 다음 securityDefinitions 섹션을 추가하세요:

securityDefinitions:
 :
 authorizationUrl: ""
 flow: "implicit"
 type: "oauth2"
 x-google-issuer: "google_service_account"
 x-google-jwks_uri: "https://www.googleapis.com/robot/v1/metadata/x509/google_service_account"

``를 고유한 보안 정의 이름(예: snowflakeAccess01)으로 바꾸세요.

  • 이 이름을 추적 워크시트의 Security Definition Name 필드에 기록하세요.

  • 구성 파일의 post: 섹션을 갱신해서 위에서 만든 보안 정의를 참조하게 하세요. operationId 필드 아래에 다음을 추가합니다:

security:
 - : []

operationId 필드와 같은 들여쓰기 수준으로 맞춰야 해요.

  • ``를 추적 워크시트의 Security Definition Name 필드 값으로 바꾸세요.
  • 보안 정의 이름 앞에 위 예시처럼 하이픈(-)과 공백을 반드시 포함하세요.
  • 콜론 뒤에 빈 대괄호([])를 반드시 포함하세요.

예를 들어:

paths:
 /demo-func-resource:
 post:
summary: "echo the input"
operationId: echo
security:
 - snowflakeAccess01: []
x-google-backend:
 address: https://my_dev.cloudfunctions.net/demo-cloud-function-01
 protocol: h2
  • 구성 파일을 저장하세요.
  • 파일 경로와 이름을 추적 워크시트의 Configuration File Name 필드에 기록하세요.

API 구성 파일에 대해 더 알아보려면 다음 GCP 문서를 참고하세요:

  • OpenAPI 개요 (OpenAPI overview)
  • API 정의 만들기 (Create an API definition)

API Gateway 만들기 (Create an API Gateway)

API Gateway를 만들려면 다음을 수행하세요:

  • GCP API를 만듭니다.
  • API Config를 만듭니다.
  • API Config로 Gateway를 만듭니다.

GCP API 만들기 (Create a GCP API)

이 단계는 하나 이상의 API Gateway와 하나 이상의 구성 파일을 담을 수 있는 컨테이너인 GCP API를 만듭니다:

  • 아직 하지 않았다면 GCP 메뉴에서 API Gateway를 선택해 Google Cloud API Gateway 화면으로 이동하세요.
  • CREATE GATEWAY를 클릭하세요.
  • 표시 이름(Display Name)과 API ID를 입력하세요(예: demo-api-display-name-for-external-function1, demo-api-id-for-external-function1). 이 값들은 나중에 외부 함수를 만들 때 다시 입력할 필요가 없으므로 추적 워크시트에 기록할 필요는 없어요. 다만 나중에 삭제할 수 있도록 API ID는 기록해 두는 게 좋을 수 있어요.

API 구성 만들기 (Create an API config)

구성 파일을 콘솔에 업로드하면 API Config가 만들어집니다.

  • 화면의 API Config 섹션으로 스크롤하세요.
  • Upload an API Spec이 포함된 필드를 찾으세요. BROWSE를 클릭하고 구성 파일을 선택하세요. 구성 파일의 이름은 추적 워크시트의 Configuration File Name 필드에 기록해 두었어요.
  • Display Name이 포함된 필드에 표시 이름을 입력하세요.
  • 서비스 계정(service account)을 선택하세요. 샘플 함수를 만들었다면 Select a Service Account 필드에서 App Engine default service account를 선택하세요. 프로덕션에서 사용할 함수를 만드는 경우(샘플이 아닌 경우) 다른 서비스 계정을 선택해도 돼요. 선택한 서비스 계정은 Cloud Function을 호출할 권한을 포함한 적절한 권한을 가져야 해요.

API 구성으로 게이트웨이 만들기 (Create a gateway with the API config)

  • 화면의 Gateway details 섹션으로 스크롤하세요.
  • 새 API Gateway의 표시 이름(Display Name)을 입력하세요.
  • Location 필드를 클릭하고 적절한 지역(예: us-central1)을 선택하세요.
  • CREATE GATEWAY를 클릭하세요. 그러면 APIs 화면으로 이동해 여러분의 API 목록이 표시돼요. 새 API가 바로 보이지 않으면 몇 분 기다린 뒤 Refresh 버튼을 클릭하세요.
  • API의 Managed Service 값을 추적 워크시트의 Managed Service Identifier 필드에 복사하세요.
  • 이 시점에 여전히 API 목록이 보일 거예요. API 이름을 클릭하세요. OVERVIEW, DETAILS, CONFIGS, GATEWAYS 네 개의 탭이 보일 거예요.
  • GATEWAYS 탭을 클릭하세요.
  • Gateway URL을 추적 워크시트의 Gateway Base URL 필드에 복사하세요.

다음 단계

3단계: Snowflake에서 GCP용 API 통합을 만듭니다.

더 알아보기 (Learn more)

  • 1단계: 원격 서비스 만들기 (external-functions-creating-gcp-ui-remote-service)
  • 3단계: GCP용 API 통합 만들기 (external-functions-creating-gcp-ui)
  • GCP용 외부 함수 만들기 (external-functions-creating-gcp-ui)
  • GCP용 외부 함수 계획하기 (external-functions-creating-gcp-planning)