AWS용 외부 함수 문제 해결

AWS용 외부 함수 문제 해결 (Troubleshooting External Functions for AWS)

이 문서는 AWS용 외부 함수를 사용할 때 발생할 수 있는 문제와 해결 방법을 정리해 드려요. 데이터 타입 불일치, 행 번호 순서, JSON 파싱 오류 같은 플랫폼 독립적인 런타임 문제와, API Gateway 502, 역할 가정 오류, 403 인증 오류처럼 AWS에 특화된 문제들을 원인과 해결책으로 나눠 설명해요.

출처: Snowflake SQL Reference

본문

이 문서는 AWS용 외부 함수에 대한 문제 해결 정보를 제공해요.

플랫폼 독립적인 런타임 문제 (Platform-independent Runtime Issues)

데이터 타입 반환 값이 예상 반환 값과 일치하지 않음

외부 함수에 인자를 전달하거나 외부 함수에서 인자를 받을 때, 데이터 타입이 적절한지 확인하세요. 전송된 값이 수신되는 데이터 타입에 맞지 않으면, 값이 잘리거나 다른 방식으로 손상될 수 있어요.

자세한 내용은 외부 함수 인자가 원격 서비스가 파싱하는 인자와 일치하는지 확인 을 참조하세요.

오류: 행 번호가 순서대로가 아님 (Row numbers out of order)

가능한 원인:

각 배치에서 반환하는 행 번호는 0에서 시작하는 단조 증가 정수(monotonically ascending integers)여야 해요. 입력 행 번호도 이 규칙을 따라야 하며, 각 출력 행은 해당 입력 행과 일치해야 해요. 예를 들어 출력 행 0의 출력은 입력 행 0의 입력에 대응해야 해요.

가능한 해결책:

반환하는 행 번호가 받은 행 번호와 같은지, 각 출력 값이 해당 입력의 행 번호를 사용하는지 확인하세요. 이것으로 해결되지 않으면 입력 행 번호가 올바르지 않거나 행을 올바른 순서로 반환하지 않은 것일 수 있어요.

다음으로 출력 행 번호가 0에서 시작하고, 1씩 증가하며, 순서대로인지 확인하세요.

데이터 입출력 형식에 대한 자세한 내용은 원격 서비스 입출력 데이터 형식 을 참조하세요.

오류: "Error parsing JSON: Invalid response"

가능한 원인:

가장 가능성 높은 원인은 원격 서비스(예: AWS Lambda function)가 반환한 JSON이 올바르게 구성되지 않은 것이에요.

가능한 해결책:

외부 함수가 배열의 배열(array of arrays)을 반환하고, 받은 각 입력 행마다 내부 배열 하나를 반환하는지 확인하세요. Snowflake가 받는 데이터 형식 에서 출력 형식 설명을 검토하세요.

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

가능한 원인:

반환 값에 값 안에 큰따옴표가 포함되어 있어요.

가능한 해결책:

JSON 문자열은 큰따옴표로 구분되지만, 문자열 자체는 대부분의 경우 따옴표로 시작하고 끝나지 않아야 해요. 포함된 큰따옴표가 잘못되었다면 제거하세요.

오류: 함수가 잘못된 수의 행을 받음 (Function received the wrong number of rows)

가능한 원인:

원격 서비스가 받은 것보다 많거나 적은 행을 반환하려고 했어요. 함수가 명목상 스칼라(scalar)이지만, event 파라미터의 body 필드에 여러 행을 받을 수 있으며, 받은 만큼 정확히 많은 행을 반환해야 해요.

가능한 해결책:

원격 서비스가 받는 각 행에 대해 하나의 행을 반환하는지 확인하세요.

AWS 특화 문제 (AWS-specific issues)

Lambda 프록시 통합을 사용하는 엔드포인트에서 API Gateway가 오류 502를 반환함

가능한 원인:

Lambda 함수가:

  • 타임아웃됐을 수 있어요.
  • 예외를 던졌을 수 있어요.
  • 다른 방식으로 실패했을 수 있어요.

가능한 해결책:

Lambda 또는 API Gateway 로그를 사용할 수 있다면 그것을 검사해요.

Lambda 함수의 소스 코드를 사용할 수 있다면 Lambda 함수의 코드를 분석하고 디버깅해요. 어떤 경우에는 그 코드의 사본을 더 간단한 컨텍스트(AWS 밖)에서 실행해 디버깅에 도움을 받을 수 있어요.

Lambda 함수로 보낸 데이터가 Lambda 함수가 기대하는 형식인지 확인하세요. 더 작고 단순한 데이터 세트를 보내 성공하는지 시도해 볼 수 있어요.

한 번에 너무 많은 데이터를 보내고 있지 않은지 확인하세요.

어떤 경우에는, 특히 Lambda 함수가 많은 CPU 리소스를 필요로 하거나 Lambda 함수 자체가 다른 원격 서비스를 호출해 더 많은 시간이 필요한 경우, 타임아웃을 늘리는 것이 문제를 해결할 수 있어요.

Amazon AWS Lambda 함수의 HTTP POST 메서드에서 요청 본문을 읽을 수 없음

가능한 원인:

Lambda 프록시 통합을 활성화하지 않았을 수 있어요.

가능한 해결책:

Lambda 프록시 통합을 활성화해요.

자세한 내용은 API Gateway 엔드포인트 만들기 의 단계를 참조하세요.

AWS_ROLE 가정 오류 (Error assuming AWS_ROLE)

메시지의 전체 텍스트는 다음과 같아요:

SQL execution error: Error assuming AWS_ROLE. Please verify the role and externalId are
configured correctly in your AWS policy.

가능한 원인:

  • 역할에 대한 AWS 신뢰 관계 정책(Trust Relationship Policy)에서 AWS ARN이 잘못됐어요. 가능한 원인은 다음과 같아요:

    • 설정하지 않았어요.
    • 설정했지만 Snowflake에서 DESCRIBE INTEGRATION 명령으로 볼 수 있는 사용자 ARN 대신 AWS 역할의 ARN(잘못됨)을 사용했어요. 워크시트의 API_AWS_IAM_USER_ARN 필드 값이 아니라 "API_AWS_ROLE_ARN" 필드의 값을 사용하지 않도록 주의하세요.

  • AWS 신뢰 관계 정책에서 std:ExternalId 가 잘못됐어요. 가능한 원인은 다음과 같아요:

    • 설정하지 않았어요.
    • API 통합 객체를 다시 만들었어요. API 객체를 다시 만들면 그 외부 ID가 바뀌어요.

오류: 403 '{“Message”:”User: is not authorized to perform: execute-api:Invoke”}'

메시지의 전체 텍스트는 다음과 같아요:

Request failed for external function <function_name>.
Error: 403 '{"Message":"User: <ARN> is not authorized to perform: execute-api:Invoke on resource: <MethodRequestARN>"}'

가능한 원인:

  • API Gateway 리소스 정책에:

    • 잘못된 IAM Role ARN이 있어요.
    • 잘못된 assumed role이 있어요.
    • 잘못된 Method Request ARN이 있어요.

  • IAM 역할에 올바른 정책이 연결되어 있지 않아요.

가능한 해결책:

  • Amazon API Gateway 엔드포인트 보안 의 리소스 정책 템플릿을 따랐는지 확인하세요. 구체적으로 리소스 정책이:

    • < 12-digit number> 를 Your AWS account ID 라는 워크시트 필드의 값으로 바꿨는지.
    • < external_function_role> 을 워크시트의 New IAM Role Name 필드의 값으로 바꿨는지.
    • Resource 필드의 method_request_ARN 을 워크시트의 Method Request ARN 필드의 값으로 바꿨는지. 끝에 슬래시가 없는지 확인하세요.

  • IAM 역할에 올바른 권한 정책이 연결되어 있는지 확인하려면 다음 단계로 역할의 권한 정책 목록을 찾을 수 있어요:

    1. AWS에서 Identity and Access Management(IAM)로 이동해 역할을 선택해요.
    2. 역할의 Summary 를 봐요.
    3. Permissions 탭을 클릭해요.
    4. 필요한 정책이 Permissions policies 목록에 있는지 확인해요.

  • 호출되는 엔드포인트가 API Gateway에 설정된 리소스(resource)인지 스테이지(stage)가 아닌지 확인하세요.

오류: 403 '{“Message”:”User: anonymous is not authorized to perform: execute-api:Invoke”}'

메시지의 전체 텍스트는 다음과 같아요:

Request failed for external function <function_name>.
Error: 403 '{"Message":"User: anonymous is not authorized to perform: execute-api:Invoke on resource: <MethodRequestARN>"}'

가능한 원인:

한 가지 가능한 원인은 API Gateway에 대한 인증을 구성할 때, 리소스에 대해 Method Request 가 AWS_IAM 인증을 요구한다는 것을 지정하지 않았을 수 있다는 것이에요.

가능한 해결책:

Amazon API Gateway 보안 의 지침을 따르지 않았다면, 지금 따라 AWS_IAM 인증을 지정하세요.

JSON 응답 파싱 오류 … 오류: 최상위 JSON 객체가 "data" JSON 배열 요소를 포함해야 함

메시지의 전체 텍스트는 다음과 같아요:

Error parsing JSON response for external function ... Error: top-level JSON object must contain "data" JSON array element

가능한 원인:

  • API Gateway 리소스의 POST 명령에 Lambda 프록시 통합을 지정하지 않았을 수 있어요.

가능한 해결책:

  • API Gateway 리소스에 Lambda 프록시 통합을 지정해요.

Lambda 프록시 통합에 대한 자세한 내용은 API Gateway 엔드포인트 만들기 의 단계를 참조하세요.

원격 서비스 오류로 외부 함수 EXT_FUNC에 대한 요청 실패: 403 '{“message”:”Forbidden”}'

가능한 원인:

프록시 서비스가 보통 인증이나 청구(billing)를 위해 API 키 를 요구했어요. API 키가 없거나 잘못됐어요.

가능한 해결책:

ALTER API INTEGRATION 명령을 사용해 올바른 API 키를 지정하세요.

CloudFormation 스택 생성 실패

이 오류는 AWS CloudFormation 템플릿을 사용해 외부 함수를 만들 때 발생할 수 있어요.

가능한 원인:

CloudFormation 템플릿에 지정된 리소스를 만들기 위한 필수 권한이 없어요.

가능한 해결책:

스택의 Events 탭을 확인해 오류 세부 사항을 봐요.

추가 문제 해결 팁은 AWS 외부 함수 문제 해결 페이지도 살펴보세요.

더 알아보기 (Learn more)