Azure Functions 프록시 사용Work with Azure Functions Proxies

이 문서에서는 Azure Functions 프록시를 구성하고 사용하는 방법을 설명합니다.This article explains how to configure and work with Azure Functions Proxies. 이 기능을 사용하면 다른 리소스에서 구현된 함수 앱에 엔드포인트를 지정할 수 있습니다.With this feature, you can specify endpoints on your function app that are implemented by another resource. 이러한 프록시를 사용하면 클라이언트에 대해 단일 API 화면을 계속 제공하면서 큰 API를 여러 개의 함수 앱으로 나눌 수 있습니다(마이크로 서비스 아키텍처 참조).You can use these proxies to break a large API into multiple function apps (as in a microservice architecture), while still presenting a single API surface for clients.

이는 Azure Functions 개발자에 대한 참조 정보입니다.This is reference information for Azure Functions developers. Azure Functions를 처음 접하는 경우 다음 리소스부터 시작합니다.If you're new to Azure Functions, start with the following resources:

참고

프록시 실행에는 표준 함수 요금이 적용됩니다.Standard Functions billing applies to proxy executions. 자세한 내용은 Azure Functions 가격 책정을 참조하세요.For more information, see Azure Functions pricing.

프록시 만들기Create a proxy

이 섹션에서는 함수 포털에서 프록시를 만드는 방법을 보여 줍니다.This section shows you how to create a proxy in the Functions portal.

  1. Azure Portal을 열고 함수 앱으로 이동합니다.Open the Azure portal, and then go to your function app.
  2. 왼쪽 창에서 새 프록시 를 선택합니다.In the left pane, select New proxy.
  3. 프록시의 이름을 제공합니다.Provide a name for your proxy.
  4. 경로 템플릿HTTP 메서드 를 지정하여 이 함수 앱에 노출되는 엔드포인트를 구성합니다.Configure the endpoint that's exposed on this function app by specifying the route template and HTTP methods. 이러한 매개 변수는 HTTP 트리거에 대한 규칙에 따라 동작합니다.These parameters behave according to the rules for HTTP triggers.
  5. 백 엔드 URL 을 다른 엔드포인트로 설정합니다.Set the backend URL to another endpoint. 이러한 엔드포인트는 다른 함수 앱의 함수이거나 다른 API일 수 있습니다.This endpoint could be a function in another function app, or it could be any other API. 정적 값이 아니어도 되며 [애플리케이션 설정] 및 원래 클라이언트 요청의 매개 변수를 참조할 수 있습니다.The value does not need to be static, and it can reference application settings and parameters from the original client request.
  6. 만들기 를 클릭합니다.Click Create.

이제 프록시는 함수 앱에서 새 엔드포인트로 존재합니다.Your proxy now exists as a new endpoint on your function app. 클라이언트 관점에서 Azure Functions의 HttpTrigger에 같습니다.From a client perspective, it is equivalent to an HttpTrigger in Azure Functions. 프록시 URL을 복사하고 자주 사용하는 HTTP 클라이언트에서 테스트하여 새 프록시를 시험해볼 수 있습니다.You can try out your new proxy by copying the Proxy URL and testing it with your favorite HTTP client.

요청 및 응답 수정Modify requests and responses

Azure Functions 프록시를 사용해서 백 엔드에서 요청 및 응답을 수정할 수 있습니다.With Azure Functions Proxies, you can modify requests to and responses from the back-end. 이러한 변환은 변수 사용에 정의된 대로 변수를 사용할 수 있습니다.These transformations can use variables as defined in Use variables.

백 엔드 요청 수정Modify the back-end request

기본적으로 백 엔드 요청은 원래 요청의 복사본으로 초기화됩니다.By default, the back-end request is initialized as a copy of the original request. 백 엔드 URL을 설정하는 것 외에도 HTTP 메서드, 헤더 및 쿼리 문자열 매개 변수를 변경할 수 있습니다.In addition to setting the back-end URL, you can make changes to the HTTP method, headers, and query string parameters. 수정된 값은 [애플리케이션 설정] 및 원래 클라이언트 요청의 매개 변수를 참조할 수 있습니다.The modified values can reference application settings and parameters from the original client request.

프록시 세부 정보 페이지의 요청 재정의 섹션을 확장하여 포털에서 백 엔드 요청을 수정할 수 있습니다.Back-end requests can be modified in the portal by expanding the request override section of the proxy detail page.

응답 수정Modify the response

기본적으로 클라이언트 요청은 원래 응답의 복사본으로 초기화됩니다.By default, the client response is initialized as a copy of the back-end response. 응답의 상태 코드, 이유 구문, 헤더 및 본문을 변경할 수 있습니다.You can make changes to the response's status code, reason phrase, headers, and body. 수정 된 값은 응용 프로그램 설정, 원래 클라이언트 요청의 매개 변수백 엔드 응답의 매개 변수를 참조할 수 있습니다.The modified values can reference application settings, parameters from the original client request, and parameters from the back-end response.

프록시 세부 정보 페이지의 응답 재정의 섹션을 확장하여 포털에서 백 엔드 응답을 수정할 수 있습니다.Back-end requests can be modified in the portal by expanding the response override section of the proxy detail page.

변수 사용Use variables

프록시에 대한 구성은 정적일 필요가 없습니다.The configuration for a proxy does not need to be static. 원래 클라이언트 요청, 백 엔드 응답 또는 애플리케이션 설정의 변수를 사용하도록 조건을 지정할 수 있습니다.You can condition it to use variables from the original client request, the back-end response, or application settings.

로컬 함수 참조Reference local functions

localhost를 사용하면 왕복 프록시 요청없이 동일한 함수 앱 내에 있는 함수를 직접 참조할 수 있습니다.You can use localhost to reference a function inside the same function app directly, without a roundtrip proxy request.

"backendurl": "https://localhost/api/httptriggerC#1"/api/httptriggerC#1 경로의 로컬 HTTP 트리거 함수를 참조합니다."backendurl": "https://localhost/api/httptriggerC#1" will reference a local HTTP triggered function at the route /api/httptriggerC#1

참고

함수에서 function, admin 또는 sys 권한 부여 수준을 사용하는 경우 원본 함수 URL에 따라 코드 및 clientId를 제공해야 합니다.If your function uses function, admin or sys authorization levels, you will need to provide the code and clientId, as per the original function URL. 이 경우 참조는 다음과 같습니다. "backendurl": "https://localhost/api/httptriggerC#1?code=<keyvalue>&clientId=<keyname>" 이러한 키를 응용 프로그램 설정 에 저장 하 고 프록시에서 해당 키를 참조 하는 것이 좋습니다.In this case the reference would look like: "backendurl": "https://localhost/api/httptriggerC#1?code=<keyvalue>&clientId=<keyname>" We recommend storing these keys in application settings and referencing those in your proxies. 이렇게 하면 소스 코드에 비밀을 저장 하지 않습니다.This avoids storing secrets in your source code.

요청 매개 변수 참조Reference request parameters

요청 매개 변수는 백 엔드 URL 속성에 대한 입력 또는 요청 및 응답을 수정하는 일부로 사용할 수 있습니다.You can use request parameters as inputs to the back-end URL property or as part of modifying requests and responses. 기본 프록시 구성에 지정된 경로 템플릿에서 제한할 수 있는 매개 변수도 있고 들어오는 요청의 속성에서 가져올 수 있는 매개 변수도 있습니다.Some parameters can be bound from the route template that's specified in the base proxy configuration, and others can come from properties of the incoming request.

경로 템플릿 매개 변수Route template parameters

경로 템플릿에 사용된 매개 변수는 이름으로 참조할 수 있습니다.Parameters that are used in the route template are available to be referenced by name. 이러한 매개 변수 이름은 중괄호({})로 묶습니다.The parameter names are enclosed in braces ({}).

예를 들어 프록시에 /pets/{petId}와 같은 경로 템플릿이 있는 경우 백 엔드 URL은 https://<AnotherApp>.azurewebsites.net/api/pets/{petId}와 같이 {petId} 값을 포함할 수 있습니다.For example, if a proxy has a route template, such as /pets/{petId}, the back-end URL can include the value of {petId}, as in https://<AnotherApp>.azurewebsites.net/api/pets/{petId}. 경로 템플릿이 와일드카드로 끝나면(예: /api/{*restOfPath}) 값 {restOfPath}는 들어오는 요청의 나머지 경로 세그먼트에 대한 문자열 표현이 됩니다.If the route template terminates in a wildcard, such as /api/{*restOfPath}, the value {restOfPath} is a string representation of the remaining path segments from the incoming request.

추가 요청 매개 변수Additional request parameters

경로 템플릿 매개 변수 외에도 구성 값에 다음 값을 사용할 수 있습니다.In addition to the route template parameters, the following values can be used in config values:

  • {request.method} : 원래 요청에 사용된 HTTP 메서드입니다.{request.method}: The HTTP method that's used on the original request.
  • {headers. <HeaderName> }: 원래 요청에서 읽을 수 있는 헤더입니다.{request.headers.<HeaderName>}: A header that can be read from the original request. <HeaderName> 읽으려는 헤더의 이름으로 대체 합니다.Replace <HeaderName> with the name of the header that you want to read. 헤더가 요청에 포함되지 않으면 값은 비어 있는 문자열이 됩니다.If the header is not included on the request, the value will be the empty string.
  • {request. querystring. <ParameterName> }: 원래 요청에서 읽을 수 있는 쿼리 문자열 매개 변수입니다.{request.querystring.<ParameterName>}: A query string parameter that can be read from the original request. <ParameterName> 읽으려는 매개 변수 이름으로 대체 합니다.Replace <ParameterName> with the name of the parameter that you want to read. 매개 변수가 요청에 포함되지 않으면 값은 비어 있는 문자열이 됩니다.If the parameter is not included on the request, the value will be the empty string.

백 엔드 응답 매개 변수 참조Reference back-end response parameters

응답 매개 변수는 클라이언트에 대한 응답을 수정하는 일부로 사용할 수 있습니다.Response parameters can be used as part of modifying the response to the client. 구성 값에 다음 값을 사용할 수 있습니다.The following values can be used in config values:

  • {backend.response.statusCode}: 백 엔드 응답에 반환할 HTTP 상태 코드입니다.{backend.response.statusCode}: The HTTP status code that's returned on the back-end response.
  • {backend.response.statusReason}: 백 엔드 응답에 반환할 HTTP 이유 구문입니다.{backend.response.statusReason}: The HTTP reason phrase that's returned on the back-end response.
  • {백엔드. 헤더. <HeaderName> }: 백 엔드 응답에서 읽을 수 있는 헤더입니다.{backend.response.headers.<HeaderName>}: A header that can be read from the back-end response. <HeaderName> 읽으려는 헤더의 이름으로 대체 합니다.Replace <HeaderName> with the name of the header you want to read. 헤더가 응답에 포함되지 않으면 값은 비어 있는 문자열이 됩니다.If the header is not included on the response, the value will be the empty string.

애플리케이션 설정 참조Reference application settings

또한 설정 이름을 백분율 기호 (%)로 묶어 함수 앱에 대해 정의 된 응용 프로그램 설정을 참조할 수 있습니다.You can also reference application settings defined for the function app by surrounding the setting name with percent signs (%).

예를 들어의 백 엔드 URL은 https://%ORDER_PROCESSING_HOST%/api/orders "% ORDER_PROCESSING_HOST%"을 (를) ORDER_PROCESSING_HOST 설정 값으로 바꿉니다.For example, a back-end URL of https://%ORDER_PROCESSING_HOST%/api/orders would have "%ORDER_PROCESSING_HOST%" replaced with the value of the ORDER_PROCESSING_HOST setting.

배포 또는 테스트 환경이 여러 개 있는 경우 백 엔드 호스트에 대해 애플리케이션 설정을 사용하세요.Use application settings for back-end hosts when you have multiple deployments or test environments. 이러한 방식으로 항상 해당 환경에 적합한 백 엔드에 정보를 전달할 수 있습니다.That way, you can make sure that you are always talking to the right back-end for that environment.

프록시 문제 해결Troubleshoot Proxies

"debug":true 플래그를 proxies.json의 프록시에 추가하면 디버그 로깅을 사용하도록 설정됩니다.By adding the flag "debug":true to any proxy in your proxies.json you will enable debug logging. 로그는 D:\home\LogFiles\Application\Proxies\DetailedTrace에 저장되며 고급 도구(kudu)를 통해 액세스할 수 있습니다.Logs are stored in D:\home\LogFiles\Application\Proxies\DetailedTrace and accessible through the advanced tools (kudu). 모든 HTTP 응답에는 로그 파일에 액세스할 수 있는 URL이 포함된 Proxy-Trace-Location 헤더도 포함됩니다.Any HTTP responses will also contain a Proxy-Trace-Location header with a URL to access the log file.

true로 설정된 Proxy-Trace-Enabled 헤더를 추가하면 클라이언트 쪽에서 프록시를 디버그할 수 있습니다.You can debug a proxy from the client side by adding a Proxy-Trace-Enabled header set to true. 또한 파일 시스템에 추적을 기록하며 추적 URL을 응답의 헤더로 반환합니다.This will also log a trace to the file system, and return the trace URL as a header in the response.

프록시 추적 차단Block proxy traces

보안상의 이유로 서비스 호출자가 추적을 생성하도록 허용하지 않을 수 있습니다.For security reasons you may not want to allow anyone calling your service to generate a trace. 로그인 자격 증명이 없으면 추적 내용에 액세스할 수 없지만 추적을 생성하면 리소스가 소비되고 Function 프록시가 사용되는 것이 노출됩니다.They will not be able to access the trace contents without your login credentials, but generating the trace consumes resources and exposes that you are using Function Proxies.

proxies.json의 특정 프록시에 "debug":false를 추가하면 추적을 완전히 사용하지 않도록 설정됩니다.Disable traces altogether by adding "debug":false to any particular proxy in your proxies.json.

고급 구성Advanced configuration

구성하는 프록시는 함수 앱 디렉터리의 루트에 있는 proxies.json 파일에 저장됩니다.The proxies that you configure are stored in a proxies.json file, which is located in the root of a function app directory. 이 파일을 수동으로 편집하고 함수가 지원하는 배포 방법 중 하나를 사용하여 앱의 일부로 배포할 수 있습니다.You can manually edit this file and deploy it as part of your app when you use any of the deployment methods that Functions supports.

배포 방법 중 하나를 설정하지 않은 경우 포털에서 proxies.json 파일로 작업할 수도 있습니다.If you have not set up one of the deployment methods, you can also work with the proxies.json file in the portal. 함수 앱으로 이동하여 플랫폼 기능 을 선택한 후 App Service 편집기 를 선택합니다.Go to your function app, select Platform features, and then select App Service Editor. 이렇게 하여 함수 앱의 전체 파일 구조를 보고 변경할 수 있습니다.By doing so, you can view the entire file structure of your function app and then make changes.

Proxies.json 은 명명된 프록시 및 해당 정의로 구성된 프록시 개체로 정의됩니다.Proxies.json is defined by a proxies object, which is composed of named proxies and their definitions. 편집기에서 코드 완성을 지원하는 경우 필요에 따라 JSON 스키마를 참조할 수 있습니다.Optionally, if your editor supports it, you can reference a JSON schema for code completion. 예제 파일은 다음과 유사할 수 있습니다.An example file might look like the following:

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

각 프록시에는 위의 코드 예제의 proxy1 과 같은 이름이 지정됩니다.Each proxy has a friendly name, such as proxy1 in the preceding example. 해당하는 프록시 정의 개체는 다음과 같은 속성으로 정의됩니다.The corresponding proxy definition object is defined by the following properties:

  • matchCondition: 필수--이 프록시의 실행을 트리거하는 요청을 정의하는 개체입니다.matchCondition: Required--an object defining the requests that trigger the execution of this proxy. HTTP 트리거와 공유되는 두 가지 속성이 포함되어 있습니다.It contains two properties that are shared with HTTP triggers:
    • 메서드: 프록시가 응답하는 HTTP 메서드의 배열입니다.methods: An array of the HTTP methods that the proxy responds to. 이 속성을 지정하지 않으면 프록시는 경로의 모든 HTTP 메서드에 응답합니다.If it is not specified, the proxy responds to all HTTP methods on the route.
    • route: 필수--경로 템플릿을 정의하여 프록시에서 응답할 요청 URL을 제어합니다.route: Required--defines the route template, controlling which request URLs your proxy responds to. HTTP 트리거와 달리 기본값이 없습니다.Unlike in HTTP triggers, there is no default value.
  • backendUri: 요청이 프록시되어야 하는 백 엔드 리소스의 URL입니다.backendUri: The URL of the back-end resource to which the request should be proxied. 이 값은 애플리케이션 설정 및 원래 클라이언트 요청의 매개 변수를 참조할 수 있습니다.This value can reference application settings and parameters from the original client request. 이 속성을 포함하지 않으면 Azure Functions는 HTTP 200 OK로 응답합니다.If this property is not included, Azure Functions responds with an HTTP 200 OK.
  • requestOverrides: 변환을 백 엔드 요청으로 정의하는 개체입니다.requestOverrides: An object that defines transformations to the back-end request. requestOverrides 개체 정의를 참조하세요.See Define a requestOverrides object.
  • responseOverrides: 클라이언트 응답으로 변환을 정의하는 개체입니다.responseOverrides: An object that defines transformations to the client response. responseOverrides 개체 정의를 참조하세요.See Define a responseOverrides object.

참고

Azure Functions 프록시의 route 속성은 함수 앱 호스트 구성의 routePrefix 속성을 유지하지 않습니다.The route property in Azure Functions Proxies does not honor the routePrefix property of the Function App host configuration. /api 같은 접두사를 포함하려는 경우 route 속성에 포함해야 합니다.If you want to include a prefix such as /api, it must be included in the route property.

개별 프록시 사용 안 함Disable individual proxies

proxies.json 파일의 프록시에 "disabled": true를 추가하면 개별 프록시를 사용하지 않도록 설정할 수 있습니다.You can disable individual proxies by adding "disabled": true to the proxy in the proxies.json file. 이렇게 하면 matchCondition을 충족하는 모든 요청이 404를 반환합니다.This will cause any requests meeting the matchCondition to return 404.

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

응용 프로그램 설정Application Settings

여러 앱 설정에 따라 프록시 동작을 제어할 수 있습니다.The proxy behavior can be controlled by several app settings. 함수 앱 설정 참조에 모두 설명되어 있습니다.They are all outlined in the Functions App Settings reference

예약된 문자(문자열 형식)Reserved Characters (string formatting)

프록시는 \를 이스케이프 기호로 사용하여 JSON 파일에서 모든 문자열을 읽습니다.Proxies read all strings out of a JSON file, using \ as an escape symbol. 프록시는 또한 중괄호를 해석합니다.Proxies also interpret curly braces. 아래 예제 전체를 참조하세요.See a full set of examples below.

문자Character 이스케이프된 문자Escaped Character 예제Example
{ 또는 }{ or } {{ 또는 }}{{ or }} {{ example }} --> { example }
\ \\ example.com\\text.html --> example.com\text.html
"" \" \"example\" --> "example"

requestOverrides 개체 정의Define a requestOverrides object

requestOverrides 개체는 백 엔드 리소스가 호출될 때 요청에 대한 변경 내용을 정의합니다.The requestOverrides object defines changes made to the request when the back-end resource is called. 개체는 다음 속성으로 정의됩니다.The object is defined by the following properties:

  • backend.request.method: 백 엔드를 호출하는 데 사용될 HTTP 메서드입니다.backend.request.method: The HTTP method that's used to call the back-end.
  • 백 엔드. querystring <ParameterName>.: 백 엔드에 대 한 호출에 설정할 수 있는 쿼리 문자열 매개 변수입니다.backend.request.querystring.<ParameterName>: A query string parameter that can be set for the call to the back-end. <ParameterName> 설정 하려는 매개 변수의 이름으로 대체 합니다.Replace <ParameterName> with the name of the parameter that you want to set. 빈 문자열이 제공 되 면 매개 변수는 백 엔드 요청에 계속 포함 됩니다.Note that if an empty string is provided, the parameter is still included on the back-end request.
  • 백 엔드. headers.: <HeaderName> 백 엔드에 대 한 호출에 설정할 수 있는 헤더입니다.backend.request.headers.<HeaderName>: A header that can be set for the call to the back-end. <HeaderName> 설정 하려는 헤더의 이름으로 대체 합니다.Replace <HeaderName> with the name of the header that you want to set. 빈 문자열이 제공 되 면 매개 변수는 백 엔드 요청에 계속 포함 됩니다.Note that if an empty string is provided, the parameter is still included on the back-end request.

값은 애플리케이션 설정 및 원래 클라이언트 요청의 매개 변수를 참조할 수 있습니다.Values can reference application settings and parameters from the original client request.

예제 구성은 다음과 유사할 수 있습니다.An example configuration might look like the following:

{
    "$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 개체 정의Define a responseOverrides object

requestOverrides 개체는 클라이언트에 다시 전달된 응답에 대한 변경 내용을 정의합니다.The requestOverrides object defines changes that are made to the response that's passed back to the client. 개체는 다음 속성으로 정의됩니다.The object is defined by the following properties:

  • response.statusCode: 클라이언트에 반환할 HTTP 상태 코드입니다.response.statusCode: The HTTP status code to be returned to the client.
  • response.statusReason: 클라이언트에 반환할 HTTP 이유 구문입니다.response.statusReason: The HTTP reason phrase to be returned to the client.
  • response.body: 클라이언트에 반환할 본문의 문자열 표현입니다.response.body: The string representation of the body to be returned to the client.
  • response. 헤더 <HeaderName>: 클라이언트에 대 한 응답에 설정할 수 있는 헤더입니다.response.headers.<HeaderName>: A header that can be set for the response to the client. <HeaderName> 설정 하려는 헤더의 이름으로 대체 합니다.Replace <HeaderName> with the name of the header that you want to set. 빈 문자열을 제공하면 헤더는 응답에 포함되지 않습니다.If you provide the empty string, the header is not included on the response.

값은 애플리케이션 설정, 원래 클라이언트 요청의 매개 변수 및 백 엔드 응답의 매개 변수를 참조할 수 있습니다.Values can reference application settings, parameters from the original client request, and parameters from the back-end response.

예제 구성은 다음과 유사할 수 있습니다.An example configuration might look like the following:

{
    "$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 속성이 필요하지 않습니다.In this example, the response body is set directly, so no backendUri property is needed. 다음 예제에서는 모의 API에 Azure Functions 프록시를 어떻게 사용할 수 있는지를 보여 줍니다.The example shows how you might use Azure Functions Proxies for mocking APIs.