GCP용 외부 함수 문제 해결하기

GCP용 외부 함수 문제 해결하기 (Troubleshooting external functions for GCP)

GCP용 외부 함수를 만들거나 실행할 때 자주 마주치는 오류와 그 해결 방법을 정리한 문서예요. 원격 서비스가 예상대로 동작하지 않을 때, 데이터 타입이나 JSON 형식, 행(row) 번호 등에서 발생하는 문제를 단계적으로 진단하고 고칠 수 있도록 도와드릴게요.

출처: Snowflake SQL Reference

본문

플랫폼과 무관한 런타임 문제 (Platform-independent Runtime Issues)

반환 데이터 타입이 기대한 값과 일치하지 않을 때

외부 함수로 인자를 주고받을 때 데이터 타입이 적절한지 꼭 확인해야 해요. 보내는 값이 받는 쪽의 데이터 타입에 맞지 않으면, 값이 잘리거나 다른 방식으로 손상될 수 있어요. 자세한 내용은 "외부 함수의 인자가 원격 서비스가 해석하는 인자와 일치하는지 확인하세요" 문서를 참고하세요.

오류: 행 번호 순서가 어긋남 (Row numbers out of order)

가능한 원인: 각 배치(batch)에서 반환하는 행 번호는 0에서 시작하는 단조 증가 정수여야 해요. 입력 행 번호도 같은 규칙을 따라야 하며, 각 출력 행은 대응하는 입력 행과 일치해야 해요. 예를 들어 출력 행 0은 입력 행 0에 대응해야 합니다.

가능한 해결 방법: 반환하는 행 번호가 받은 행 번호와 동일한지, 각 출력 값이 대응하는 입력의 행 번호를 사용하는지 확인하세요. 그래도 안 된다면 입력 행 번호가 올바르지 않거나 행을 올바른 순서로 반환하지 않은 것일 수 있어요. 다음으로 출력 행 번호가 0부터 시작해 1씩 증가하며 순서대로 있는지 확인하세요. 데이터 입출력 형식에 대한 자세한 내용은 "Remote service input and output data formats" 문서를 참고하세요.

오류: "Error parsing JSON: Invalid response"

가능한 원인: 가장 흔한 원인은 원격 서비스(예: AWS Lambda 함수)가 반환하는 JSON이 올바르게 구성되지 않은 경우예요.

가능한 해결 방법: 외부 함수가 배열의 배열(array of arrays)을 반환하고, 받은 입력 행마다 내부 배열을 하나씩 반환하는지 확인하세요. Snowflake가 받는 데이터 형식(Data format received by Snowflake)에 대한 설명을 다시 확인해 보세요.

오류: 반환된 값의 형식이 JSON이 아님 (Format of the returned value is not JSON)

가능한 원인: 반환 값 안에 큰따옴표(double quote)가 포함돼 있을 수 있어요.

가능한 해결 방법: JSON 문자열은 큰따옴표로 구분되지만, 대부분의 경우 문자열 자체가 따옴표로 시작하거나 끝나서는 안 돼요. 잘못 들어간 큰따옴표가 있다면 제거하세요.

오류: 함수가 받은 것과 다른 개수의 행을 받음 (Function received the wrong number of rows)

가능한 원인: 원격 서비스가 받은 행보다 많거나 적은 행을 반환하려 한 경우예요. 함수는 명목상 스칼라(scalar)지만 event 파라미터의 body 필드에 여러 행을 받을 수 있으므로, 받은 행 수와 정확히 같은 개수의 행을 반환해야 해요.

가능한 해결 방법: 원격 서비스가 받은 각 행마다 하나의 행을 반환하는지 확인하세요.

GCP 전용 문제 (GCP-specific issues)

오류: {"message":"Audiences in jwt are not allowed","code":403}

가능한 원인: API 통합(API integration)의 google_audience 필드 값이 허용되지 않는 값이에요.

가능한 해결 방법:

  • API 통합의 google_audience 값이 여러분 API의 관리 서비스 이름(managed service name)과 일치하는지 확인하세요. 이 값은 추적 워크시트의 Managed Service Identifier 필드에 기록돼 있어야 해요.
  • API 구성 파일의 securityDefinitions 섹션에 x-google-audiences 필드를 추가했다면, x-google-audiences의 값이 API 통합의 google_audience 필드 값과 일치하는지 확인하세요.

Google 인증에 대한 자세한 내용은 Google 서비스 계정 인증(Google service account authentication) 문서를 참고하세요.

오류: {"message":"Jwt is missing","code":401}

가능한 원인:

  • 구성 파일의 securityDefinitions 필드에 있는 x-google-issuer 값이 추적 워크시트에 기록된 API 통합의 API_GCP_SERVICE_ACCOUNT 값과 일치하지 않을 수 있어요.
  • x-google-issuer의 값에 여분의 공백이 포함돼 있을 수 있어요.

가능한 해결 방법:

  • x-google-issuer를 API_GCP_SERVICE_ACCOUNT와 일치하도록 갱신하세요.
  • 불필요한 공백을 제거하세요.

오류: 403 forbidden

가능한 원인: 구성 파일을 사용하는 서비스 계정(service account)이 백엔드(backend)에 적절한 권한을 가지고 있지 않은 경우예요.

가능한 해결 방법: 서비스 계정의 권한을 갱신하세요.

더 알아보기 (Learn more)

  • GCP용 외부 함수 만들기 (external-functions-creating-gcp-ui)
  • 원격 서비스 입출력 데이터 형식 (external-functions-data-format)
  • 외부 함수 구현 (external-functions-implementation)
  • 외부 함수 보안 (external-functions-security)