레거시 프록시 작업

아티클
06/01/2023

Important

Azure Functions 프록시는 Azure Functions 런타임 버전 1.x~3.x의 레거시 함수입니다. 함수 앱을 최신 런타임 버전으로 업그레이드할 수 있도록 버전 4.x에서 함수 프록시에 대한 지원을 다시 사용하도록 설정할 수 있습니다. 가능한 한 빨리 함수 앱을 Azure API Management와 통합하도록 전환해야 합니다. API Management를 사용하면 Functions 기반 API를 정의, 보호, 관리 및 수익화하기 위한 보다 완전한 기능 집합을 활용할 수 있습니다. 자세한 내용은 API Management 통합을 참조하세요.

Functions 버전 4.x에서 프록시 지원을 다시 사용하도록 설정하는 방법을 알아보려면 Functions v4.x에서 프록시 다시 사용하도록 설정를 참조하세요.

이 문서에서는 기존 프록시 오류에서 보다 쉽게 마이그레이션할 수 있도록 해당 API Management 콘텐츠(사용 가능한 경우)에 연결합니다.

이 문서에서는 Azure Functions 프록시를 구성하고 사용하는 방법을 설명합니다. 이 기능을 사용하면 다른 리소스에서 구현되는 함수 앱에 엔드포인트를 지정할 수 있습니다. 이러한 프록시를 사용하면 클라이언트에 대해 단일 API 화면을 계속 제공하면서 큰 API를 여러 개의 함수 앱으로 나눌 수 있습니다(마이크로 서비스 아키텍처 참조).

표준 함수 청구는 프록시 실행에 적용됩니다. 자세한 내용은 Azure Functions 가격 책정을 참조하세요.

Functions v4.x에서 프록시 다시 사용

함수 앱을 Functions 런타임 버전 4.x로 마이그레이션한 후에는 특별히 다시 활성화할 수 있는 프록시가 필요합니다. 프록시만 사용하는 것이 아니라 가능한 한 빨리 함수 앱을 Azure API Management와 통합하는 것으로 전환해야 합니다.

프록시를 다시 사용하도록 설정하려면 다음 방법 중 하나로 애플리케이션 설정에서 AzureWebJobsFeatureFlags 플래그를 설정해야 합니다.

설정이 AzureWebJobsFeatureFlags 아직 없는 경우 값 EnableProxies이 있는 함수 앱에 이 설정을 추가합니다.
이 설정이 이미 있는 경우 기존 값의 끝에 추가 ,EnableProxies 합니다.

AzureWebJobsFeatureFlags 는 미리 보기 및 기타 임시 기능을 사용하도록 설정하는 데 사용되는 쉼표로 구분된 플래그 배열입니다. 애플리케이션 설정을 만들고 수정하는 방법에 대한 자세한 내용은 애플리케이션 설정 작업을 참조 하세요.

참고 항목

플래그를 사용하여 EnableProxies 다시 사용하도록 설정한 경우에도 Azure Portal에서 프록시를 사용할 수 없습니다. 대신 함수 앱에 대한 proxies.json 파일로 직접 작업해야 합니다. 자세한 내용은 고급 구성을 참조하세요.

프록시 만들기

Important

API Management를 사용하는 동등한 콘텐츠는 Azure API Management를 사용하여 HTTP 엔드포인트에서 서버리스 API 노출을 참조하세요.

프록시는 함수 앱의 루트에 있는 proxies.json 파일에 정의되어 있습니다. 이 섹션의 단계에서는 Azure Portal을 사용하여 함수 앱에서 이 파일을 만드는 방법을 보여 줍니다. 모든 언어 및 운영 체제 조합이 포털 내 편집을 지원하는 것은 아닙니다. 포털에서 함수 앱 파일을 수정할 수 없는 경우 로컬 프로젝트 폴더의 루트에서 해당 proxies.json 파일을 만들고 배포할 수 있습니다. 포털 편집 지원에 대한 자세한 내용은 언어 지원 세부 정보를 참조하세요.

Azure Portal을 열고 함수 앱으로 이동합니다.
왼쪽 창에서 프록시를 선택한 다음, +추가를 선택하세요.
프록시의 이름을 제공합니다.
경로 템플릿 및 HTTP 메서드를 지정하여 이 함수 앱에 노출되는 엔드포인트를 구성합니다. 이러한 매개 변수는 HTTP 트리거에 대한 규칙에 따라 동작합니다.
백 엔드 URL을 다른 엔드포인트로 설정합니다. 이러한 엔드포인트는 다른 함수 앱의 함수이거나 다른 API일 수 있습니다. 정적 값이 아니어도 되며 애플리케이션 설정 및 원래 클라이언트 요청의 매개 변수를 참조할 수 있습니다.
만들기를 실행합니다.

이제 프록시가 함수 앱에 새 엔드포인트로 존재합니다. 클라이언트 관점에서 볼 때 Functions의 HttpTrigger와 동일합니다. 프록시 URL을 복사하고 자주 사용하는 HTTP 클라이언트에서 테스트하여 새 프록시를 시험해 볼 수 있습니다.

요청 및 응답 수정

Important

API Management를 사용하면 정책을 사용하여 구성을 통해 API 동작을 변경할 수 있습니다. 정책은 API의 요청 또는 응답에 따라 순차적으로 실행되는 명령문의 컬렉션입니다. API Management 정책에 대한 자세한 내용은 Azure API Management의 정책을 참조하세요.

프록시를 사용하여 백 엔드에서 요청 및 응답을 수정할 수 있습니다. 이러한 변환은 변수 사용에서 정의된 대로 변수를 사용할 수 있습니다.

백 엔드 요청 수정

기본적으로 백 엔드 요청은 원래 요청의 복사본으로 초기화됩니다. 백 엔드 URL을 설정하는 것 외에도 HTTP 메서드, 헤더 및 쿼리 문자열 매개 변수를 변경할 수 있습니다. 수정된 값은 애플리케이션 설정 및 원래 클라이언트 요청의 매개 변수를 참조할 수 있습니다.

프록시 세부 정보 페이지의 요청 재정의 섹션을 확장하여 포털에서 백 엔드 요청을 수정할 수 있습니다.

응답 수정

기본적으로 클라이언트 응답은 백 엔드 응답의 복사본으로 초기화됩니다. 응답의 상태 코드, 이유 구문, 헤더 및 본문을 변경할 수 있습니다. 수정된 값은 애플리케이션 설정, 원래 클라이언트 요청의 매개 변수 및 백 엔드 응답의 매개 변수를 참조할 수 있습니다.

프록시 세부 정보 페이지의 응답 재정의 섹션을 확장하여 포털에서 백 엔드 응답을 수정할 수 있습니다.

변수 사용

프록시에 대한 구성은 정적일 필요가 없습니다. 원래 클라이언트 요청, 백 엔드 응답 또는 애플리케이션 설정의 변수를 사용하도록 조건을 지정할 수 있습니다.

로컬 함수 참조

라운드트립 프록시 요청 없이 동일한 함수 앱 내에서 함수를 직접 참조하는 데 사용할 localhost 수 있습니다.

"backendUri": "https://localhost/api/httptriggerC#1" 는 경로에서 로컬 HTTP 트리거 함수를 참조합니다. /api/httptriggerC#1

참고 항목

함수에서 function, admin 또는 sys 권한 부여 수준을 사용하는 경우 원본 함수 URL에 따라 코드 및 clientId를 제공해야 합니다. 이 경우 참조는 다음과 같습니다"backendUri": "https://localhost/api/httptriggerC#1?code=<keyvalue>&clientId=<keyname>". 이러한 키를 애플리케이션 설정에 저장하고 프록시에서 참조하는 것이 좋습니다. 이렇게 하면 소스 코드에 비밀을 저장하지 않습니다.

요청 매개 변수 참조

요청 매개 변수를 백 엔드 URL 속성에 대한 입력 또는 요청 및 응답 수정의 일부로 사용할 수 있습니다. 일부 매개 변수는 기본 프록시 구성에 지정된 경로 템플릿에서 바인딩될 수 있으며, 다른 매개 변수는 들어오는 요청의 속성에서 올 수 있습니다.

경로 템플릿 매개 변수

경로 템플릿에서 사용되는 매개 변수는 이름으로 참조할 수 있습니다. 매개 변수 이름은 중괄호({})로 묶입니다.

예를 들어 프록시에 경로 템플릿(예: /pets/{petId}백 엔드 URL)이 있는 경우와 같이 https://<AnotherApp>.azurewebsites.net/api/pets/{petId}백 엔드 URL의 {petId}값을 포함할 수 있습니다. 경로 템플릿이 와일드카드 종료되는 경우 값 /api/{*restOfPath}{restOfPath} 은 들어오는 요청에서 다시 기본 경로 세그먼트의 문자열 표현입니다.

추가 요청 매개 변수

경로 템플릿 매개 변수 외에도 구성 값에 다음 값을 사용할 수 있습니다.

{request.method}: 원래 요청에 사용되는 HTTP 메서드입니다.
{request.headers.<HeaderName>}: 원래 요청에서 읽어올 수 있는 헤더입니다. <HeaderName>을 읽으려는 헤더 이름으로 바꿉니다. 헤더가 요청에 포함되지 않으면 값은 비어 있는 문자열이 됩니다.
{request.querystring.<ParameterName>}: 원래 요청에서 읽어올 수 있는 쿼리 문자열 매개 변수입니다. ParameterName>을 읽으려는 매개 변수의 이름으로 바꿉<습니다. 매개 변수가 요청에 포함되지 않으면 값은 비어 있는 문자열이 됩니다.

참조 백 엔드 응답 매개 변수

응답 매개 변수는 클라이언트에 대한 응답을 수정하는 일부로 사용할 수 있습니다. 구성 값에 다음 값을 사용할 수 있습니다.

{backend.response.statusCode}: 백 엔드 응답에 반환할 HTTP 상태 코드입니다.
{backend.response.statusReason}: 백 엔드 응답에 반환할 HTTP 이유 구문입니다.
{backend.response.headers.<HeaderName>}: 백 엔드 응답에서 읽어올 수 있는 헤더입니다. <HeaderName>을 읽으려는 헤더 이름으로 바꿉니다. 헤더가 응답에 포함되지 않으면 값은 비어 있는 문자열이 됩니다.

참조 애플리케이션 설정

설정 이름을 백분율 기호(%)로 묶어 함수 앱에 대해 정의된 애플리케이션 설정을 참조할 수도 있습니다.

예를 들어 백 엔드 URL의 https://%ORDER_PROCESSING_HOST%/api/orders "%ORDER_PROCESSING_HOST%"가 ORDER_PROCESSING_HOST 설정의 값으로 바뀝니다.

팁

여러 배포 또는 테스트 환경이 있는 경우 백 엔드 호스트에 애플리케이션 설정을 사용합니다. 이렇게 하면 해당 환경에 대해 항상 올바른 백 엔드에 대해 이야기하고 있는지 확인할 수 있습니다.

프록시 문제 해결

"debug":true 플래그를 proxies.json의 프록시에 추가하면 디버그 로깅이 활성화됩니다. 로그는 고급 도구(kudu)를 통해 저장 D:\home\LogFiles\Application\Proxies\DetailedTrace 되고 액세스할 수 있습니다. 모든 HTTP 응답에는 로그 파일에 액세스하기 위한 URL이 있는 헤더도 포함 Proxy-Trace-Location 됩니다.

헤더 집합을 추가하여 클라이언트 쪽에서 프록시를 Proxy-Trace-Enabled 디버그할 수 있습니다 true. 또한 추적을 파일 시스템에 기록하고 추적 URL을 응답의 헤더로 반환합니다.

프록시 추적 차단

보안상의 이유로 서비스를 호출하는 사람이 추적을 생성하도록 허용하지 않을 수 있습니다. 로그인 자격 증명이 없으면 추적 내용에 액세스할 수 없지만 추적을 생성하면 리소스가 소비되고 Function 프록시가 사용되는 것이 노출됩니다.

proxies.json의 특정 프록시에 "debug":false를 추가하면 추적을 완전히 사용하지 않도록 설정됩니다.

고급 구성

구성하는 프록시는 함수 앱 디렉터리의 루트에 있는 proxies.json 파일에 저장됩니다. 이 파일을 수동으로 편집하고 함수가 지원하는 배포 방법 중 하나를 사용하여 앱의 일부로 배포할 수 있습니다.

팁

배포 방법 중 하나를 설정하지 않은 경우 포털에서 proxies.json 파일로 작업할 수도 있습니다. 함수 앱으로 이동하여 플랫폼 기능을 선택한 다음, App Service 편집기를 선택합니다. 이렇게 하여 함수 앱의 전체 파일 구조를 보고 변경할 수 있습니다.

Proxies.json은 명명된 프록시 및 해당 정의로 구성된 프록시 개체로 정의됩니다. 필요에 따라 편집기에서 지원하는 경우 코드 완성을 위해 JSON 스키마를 참조할 수 있습니다. 예제 파일은 다음과 같을 수 있습니다.

{
    "$schema": "http://json.schemastore.org/proxies",
    "proxies": {
        "proxy1": {
            "matchCondition": {
                "methods": [ "GET" ],
                "route": "/api/{test}"
            },
            "backendUri": "https://<AnotherApp>.azurewebsites.net/api/<FunctionName>"
        }
    }
}

각 프록시에는 앞의 예제에서 proxy1과 같은 친숙한 이름이 있습니다. 해당 프록시 정의 개체는 다음 속성에 의해 정의됩니다.

matchCondition: 필수- 이 프록시의 실행을 트리거하는 요청을 정의하는 개체입니다. HTTP 트리거와 공유되는 두 가지 속성이 포함되어 있습니다.
- 메서드: 프록시가 응답하는 HTTP 메서드의 배열입니다. 이 속성을 지정하지 않으면 프록시는 경로의 모든 HTTP 메서드에 응답합니다.
- route: 필수--경로 템플릿을 정의하여 프록시가 응답하는 요청 URL을 제어합니다. HTTP 트리거와 달리 기본값이 없습니다.
backendUri: 요청을 프록시해야 하는 백 엔드 리소스의 URL입니다. 이 값은 애플리케이션 설정 및 원래 클라이언트 요청의 매개 변수를 참조할 수 있습니다. 이 속성을 포함하지 않으면 Azure Functions는 HTTP 200 OK로 응답합니다.
requestOverrides: 백 엔드 요청에 대한 변환을 정의하는 개체입니다. requestOverrides 개체 정의를 참조하세요.
responseOverrides: 클라이언트 응답에 대한 변환을 정의하는 개체입니다. responseOverrides 개체 정의를 참조하세요.

참고 항목

Azure Functions 프록시의 route 속성은 함수 앱 호스트 구성의 routePrefix 속성을 유지하지 않습니다. 같은 /api접두사를 포함하려면 경로 속성에 포함되어야 합니다.

개별 프록시 사용 안 함

proxies.json 파일의 프록시에 "disabled": true를 추가하면 개별 프록시를 사용하지 않도록 설정할 수 있습니다. 이렇게 하면 matchCondition을 충족하는 모든 요청이 404를 반환합니다.

{
    "$schema": "http://json.schemastore.org/proxies",
    "proxies": {
        "Root": {
            "disabled":true,
            "matchCondition": {
                "route": "/example"
            },
            "backendUri": "https://<AnotherApp>.azurewebsites.net/api/<FunctionName>"
        }
    }
}

애플리케이션 설정

프록시 동작은 여러 앱 설정으로 제어할 수 있습니다. 함수 앱 설정 참조에 모두 설명되어 있습니다.

예약 문자(문자열 서식 지정)

프록시는 \를 이스케이프 기호로 사용하여 JSON 파일에서 모든 문자열을 읽습니다. 프록시는 중괄호도 해석합니다. 아래 예제의 전체 집합을 참조하세요.

캐릭터	이스케이프된 문자	예시
{ 또는 }	{{ 또는 }}	`{{ example }}` -->`{ example }`
\	\\	`example.com\\text.html` -->`example.com\text.html`
"	\"	`\"example\"` -->`"example"`

requestOverrides 개체 정의

requestOverrides 개체는 백 엔드 리소스가 호출되는 경우 요청에 대한 변경 내용을 정의합니다. 개체는 다음 속성으로 정의됩니다.

backend.request.method: 백 엔드를 호출하는 데 사용될 HTTP 메서드입니다.
backend.request.querystring.<ParameterName>: 백 엔드 호출에 대해 설정할 수 있는 쿼리 문자열 매개 변수입니다. ParameterName>을 설정하려는 매개 변수의 이름으로 바꿉<습니다. 빈 문자열이 제공되면 매개 변수는 백 엔드 요청에 계속 포함됩니다.
backend.request.headers.<HeaderName>: 백 엔드 호출에 대해 설정할 수 있는 헤더입니다. HeaderName>을 설정하려는 헤더의 이름으로 바꿉<다. 빈 문자열이 제공되면 매개 변수는 백 엔드 요청에 계속 포함됩니다.

값은 원래 클라이언트 요청에서 애플리케이션 설정 및 매개 변수를 참조할 수 있습니다.

예제 구성은 다음과 같을 수 있습니다.

{
    "$schema": "http://json.schemastore.org/proxies",
    "proxies": {
        "proxy1": {
            "matchCondition": {
                "methods": [ "GET" ],
                "route": "/api/{test}"
            },
            "backendUri": "https://<AnotherApp>.azurewebsites.net/api/<FunctionName>",
            "requestOverrides": {
                "backend.request.headers.Accept": "application/xml",
                "backend.request.headers.x-functions-key": "%ANOTHERAPP_API_KEY%"
            }
        }
    }
}

responseOverrides 개체 정의

requestOverrides 개체는 클라이언트에 다시 전달되는 응답에 대한 변경 내용을 정의합니다. 개체는 다음 속성으로 정의됩니다.

response.statusCode: 클라이언트에 반환할 HTTP 상태 코드입니다.
response.statusReason: 클라이언트에 반환할 HTTP 이유 구문입니다.
response.body: 클라이언트에 반환할 본문의 문자열 표현입니다.
response.headers.<HeaderName>: 클라이언트에 대한 응답에 대해 설정할 수 있는 헤더입니다. HeaderName>을 설정하려는 헤더의 이름으로 바꿉<다. 빈 문자열을 제공하면 헤더는 응답에 포함되지 않습니다.

값은 애플리케이션 설정, 원래 클라이언트 요청의 매개 변수 및 백 엔드 응답의 매개 변수를 참조할 수 있습니다.

예제 구성은 다음과 같을 수 있습니다.

{
    "$schema": "http://json.schemastore.org/proxies",
    "proxies": {
        "proxy1": {
            "matchCondition": {
                "methods": [ "GET" ],
                "route": "/api/{test}"
            },
            "responseOverrides": {
                "response.body": "Hello, {test}",
                "response.headers.Content-Type": "text/plain"
            }
        }
    }
}

참고 항목

이 예제에서는 응답 본문이 직접 설정되므로 속성이 필요하지 않습니다 backendUri . 이 예제에서는 모의 API에 Azure Functions 프록시를 사용하는 방법을 보여 줍니다.

레거시 프록시 작업

Functions v4.x에서 프록시 다시 사용

프록시 만들기

요청 및 응답 수정

백 엔드 요청 수정

응답 수정

변수 사용

로컬 함수 참조

요청 매개 변수 참조

경로 템플릿 매개 변수

추가 요청 매개 변수

참조 백 엔드 응답 매개 변수

참조 애플리케이션 설정

프록시 문제 해결

프록시 추적 차단

고급 구성

개별 프록시 사용 안 함

애플리케이션 설정

예약 문자(문자열 서식 지정)

requestOverrides 개체 정의

responseOverrides 개체 정의

추가 리소스