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

이 문서는 Azure용 외부 함수를 사용할 때 겪을 수 있는 문제와 해결 방법을 정리해요. 플랫폼과 무관한 공통 런타임 문제부터 Azure 특유의 문제까지 단계별로 살펴볼 수 있어요.

출처: Snowflake SQL Reference

본문

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

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

데이터 타입 반환 값이 기대한 반환 값과 일치하지 않는 경우

외부 함수에 인수를 전달하거나 받을 때 데이터 타입이 적절한지 확인해요. 보내는 값이 받는 데이터 타입에 맞지 않으면 값이 잘리거나 어떤 식으로든 손상될 수 있어요.

자세한 내용은 "외부 함수에 전달하는 인수가 원격 서비스가 파싱하는 인수와 대응하는지 확인하기"를 참고해요.

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

가능한 원인: 각 배치 안에서 반환하는 행 번호는 0에서 시작하는 단조 증가 정수여야 해요. 입력 행 번호도 이 규칙을 따라야 하고, 각 출력 행은 대응하는 입력 행과 일치해야 해요. 예를 들어 출력 행 0의 값은 입력 행 0의 값과 대응해야 해요.

가능한 해결책: 반환하는 행 번호가 받은 행 번호와 같고, 각 출력 값이 대응하는 입력의 행 번호를 사용하는지 확인해요. 이렇게 해도 안 된다면 입력 행 번호가 올바르지 않거나 행을 올바른 순서로 반환하지 않은 것일 수 있어요.

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

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

오류: "Error parsing JSON: Invalid response"

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

가능한 해결책: 외부 함수가 배열의 배열을 반환하고, 받은 각 입력 행마다 내부 배열 하나를 반환하는지 확인해요. "Snowflake가 받는 데이터 형식"에서 출력 형식에 대한 설명을 검토해요.

오류: 반환 값의 형식이 JSON이 아님

가능한 원인: 반환 값 안에 큰따옴표가 포함되어 있어요.

가능한 해결책: JSON 문자열은 큰따옴표로 구분되지만, 대부분의 경우 문자열 자체가 따옴표로 시작하고 끝나면 안 돼요. 포함된 큰따옴표가 잘못됐다면 제거해요.

오류: 함수가 잘못된 수의 행을 받음

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

가능한 해결책: 원격 서비스가 받은 각 행에 대해 정확히 한 행을 반환하는지 확인해요.

Azure 특유의 문제 (Azure-specific issues)

Azure 함수 생성 중에 설정을 수정할 수 없는 경우

가능한 원인: Azure Function을 만들 때 Authentication/Authorization 메뉴에서 함수의 설정을 수정하지 못할 수 있어요.

이 문제는 다음 조건이 모두 참일 때 발생할 수 있어요:

Azure Function이 Microsoft Windows가 아니라 Linux에서 실행 중인 경우.
Azure Function에 Azure AD 인증/권한 부여를 사용할 계획인 경우.
Azure의 "consumption" 가격 등급이 아니라 "premium" 가격 등급을 사용하지 않는 경우.

Azure Functions의 Linux Consumption 플랜에서는 Azure AD 인증이 제공되지 않아요. Azure AD로 인증하려면 App Service 플랜이나 Premium 플랜을 사용해야 해요.

가능한 해결책:

Azure Function을 다시 만들고 Linux가 아니라 Microsoft Windows에서 실행되도록 지정해요.
Azure Function에 대한 Azure AD 인증/권한 부여를 건너뛰고 대신 다음 작업을 수행해요:
- 6단계: Portal에서 프록시 서비스용 Azure 보안 정책 만들기에 설명된 대로 API Management 인스턴스에 validate-JWT(JSON Web Token) 정책을 설정해요.
- IP 주소 제한을 사용해서 원격 서비스가 API Management 서비스 인스턴스에서만 연결을 받아들이도록 제한해요.
이 해결책을 선택하면 Azure AD 애플리케이션을 수동으로 만들어야 해요. 자세한 내용은 Microsoft 문서 "app registration"을 참고해요.

Azure AD 애플리케이션을 수동으로 만들었다면 추적 워크시트에 Azure Function AD app registration name과 Azure Function App AD Application ID를 기록해요.
consumption 가격에서 premium 가격으로 전환하거나 App Service 플랜을 사용해요. 자세한 내용은 Microsoft 문서 "configuring an authentication provider"를 참고해요.

외부 함수 시간 초과 (timeout)

가능한 원인: 시간 초과에는 많은 원인이 있을 수 있어요. Azure에서는 그중 하나로 Azure Functions 앱이 제대로 확장되지 않도록 작성된 경우가 있어요.

가능한 해결책: Azure의 확장 가능한 함수 작성 지침을 따르고 있는지 확인해요: https://docs.microsoft.com/en-us/azure/azure-functions/functions-best-practices#scalability-best-practices

확장성·성능 문제 해결에 대한 자세한 내용은 "확장성·성능 문제 해결"을 참고해요.

오류: Azure Active Directory 액세스 토큰을 얻지 못함 (Failed to obtain Azure active directory access token)

가능한 해결책: 다음 단계를 시도해요.

Snowflake 서비스 주체가 Azure AD 테넌트에 접근 권한이 있는지 확인해요.
테넌트 ID와 Azure AD 애플리케이션 ID가 올바른지 확인해요. ID 필드에서는 공백(앞·뒤 공백, 예: 빈칸)도 의미가 있어요. 잘못된 앞·뒤 공백이 있는지 확인해요.

오류: 401 '{ "statusCode": 401, "message": "Access denied due to missing subscription key..." }'

전체 오류 메시지:

Request failed for external function . Error: 401 '{ "statusCode": 401, "message":
"Access denied due to missing subscription key. Make sure to include subscription key when making requests to an API." }'

가능한 원인: API Management 서비스의 구독 요구 사항이 켜져 있을 수 있어요.

가능한 해결책: API Management 서비스의 구독 요구 사항을 꺼야 할 수 있어요.

오류: 401 '{ "statusCode": 401, "message": "Access denied due to missing subscription key." }'

가능한 원인: 프록시 서비스는 보통 인증이나 요금 청구를 위해 API 키(별칭 "subscription key")를 요구해요. 그런데 CREATE API INTEGRATION 명령의 API_KEY 절에 API 키가 제공되지 않았어요.

가능한 해결책: ALTER API INTEGRATION 명령을 사용해 유효한 API 키로 API 통합을 업데이트해요.

오류: 401 '{ "statusCode": 401, "message": "Access denied due to invalid subscription key." }'

가능한 원인: 프록시 서비스는 보통 인증이나 요금 청구를 위해 API 키(별칭 "subscription key")를 요구해요. 그런데 CREATE API INTEGRATION 명령의 API_KEY 절에 제공된 API 키가 유효하지 않았어요.

가능한 해결책: ALTER API INTEGRATION 명령을 사용해 유효한 API 키로 API 통합을 업데이트해요.

오류: 401 '{ "statusCode": 401, "message": "Invalid JWT." }'

전체 오류 메시지:

Request failed for external function . Error: 401 '{ "statusCode": 401, "message": "Invalid JWT." }'

가능한 원인:

Azure API Management 서비스의 보안 정책 설정을 끝내지 않았을 수 있어요. 예를 들어:
- JWT(JSON Web Token)를 만들기만 하고 편집하지 않았을 수 있어요.
필요한 claim/값을 하나 이상 빠뜨렸을 수 있어요. 예를 들어 Snowflake용 claim을 지정했지만 원격 서비스(Azure Function)용 claim을 지정하지 않았거나 그 반대일 수 있어요.
유효하지 않은 open ID URL을 사용했을 수 있어요.

가능한 해결책:

Azure API Management 서비스의 보안 정책 설정을 끝내요. 예를 들어 JWT를 검토하고 Snowflake용 claim과 원격 서비스(Azure Function)용 claim을 포함해 필요한 claim/값을 포함했는지 확인해요.
유효한 open ID URL을 사용했는지 확인해요.

오류(원격 서비스): 401 '{ "statusCode": 401, "message": "Invalid JWT." }'

전체 오류 메시지:

Request failed for external function  with remote service error: 401 '{ "statusCode": 401, "message": "Invalid JWT." }'

가능한 원인: ARM 템플릿을 사용했다면 템플릿이 만들어 준 JWT(JSON Web Token)를 업데이트하지 않았을 수 있어요.

가능한 해결책: 6단계: Portal에서 프록시 서비스용 Azure 보안 정책 업데이트하기에 설명된 대로 JWT를 업데이트해요.

오류: 500 …

가능한 원인: Azure AD 앱에 대해 잘못된 옵션을 선택했을 수 있어요.

잘못된 옵션: Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)
올바른 옵션: Accounts in this organizational directory only (Default Directory only - Single tenant)

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