Usare i proxy di Funzioni di AzureWork with Azure Functions Proxies

Questo articolo illustra come configurare e usare i proxy in Funzioni di Azure.This article explains how to configure and work with Azure Functions Proxies. Questa funzionalità consente di specificare gli endpoint nell'app per le funzioni implementati da un'altra risorsa.With this feature, you can specify endpoints on your function app that are implemented by another resource. È possibile usare questi proxy per suddividere un'API di grandi dimensioni in più app per le funzioni (come in un'architettura di microservizio), pur continuando a presentare una singola superficie API per i client.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.

Informazioni di riferimento per gli sviluppatori delle Funzioni di Azure.This is reference information for Azure Functions developers. Se non si ha familiarità con le Funzioni di Azure, iniziare con le seguenti risorse:If you're new to Azure Functions, start with the following resources:

Nota

Si applicano le tariffe standard per Funzioni quando vengono eseguiti i proxy.Standard Functions billing applies to proxy executions. Per altre informazioni, vedere Prezzi di Funzioni.For more information, see Azure Functions pricing.

Creare un proxyCreate a proxy

In questa sezione viene descritto come creare un proxy nel portale Funzioni.This section shows you how to create a proxy in the Functions portal.

  1. Aprire il Portale di Azure e passare all'app per le funzioni.Open the Azure portal, and then go to your function app.
  2. Nel riquadro sinistro selezionare Nuovo proxy.In the left pane, select New proxy.
  3. Dare un nome al proxy.Provide a name for your proxy.
  4. Configurare l'endpoint esposto in questa app per le funzioni, specificando il Modello di route e i Metodi HTTP.Configure the endpoint that's exposed on this function app by specifying the route template and HTTP methods. Questi parametri si comportano in base alle regole dei trigger HTTP.These parameters behave according to the rules for HTTP triggers.
  5. Impostare l'URL di back-end su un altro endpoint.Set the backend URL to another endpoint. Questo endpoint potrebbe essere una funzione in un'altra app per le funzioni oppure di qualsiasi altra API.This endpoint could be a function in another function app, or it could be any other API. Il valore non deve essere statico e può fare riferimento alle impostazioni dell'applicazione e ai parametri della richiesta del client originale.The value does not need to be static, and it can reference application settings and parameters from the original client request.
  6. Fare clic su Crea.Click Create.

Il proxy è ora presente come un nuovo endpoint sull'app per le funzioni.Your proxy now exists as a new endpoint on your function app. Dalla prospettiva del client, è equivalente a un HttpTrigger nelle Funzioni di Azure.From a client perspective, it is equivalent to an HttpTrigger in Azure Functions. È possibile provare il nuovo proxy copiando l'URL del proxy ed eseguendo un test con il proprio client HTTP preferito.You can try out your new proxy by copying the Proxy URL and testing it with your favorite HTTP client.

Modificare richieste e risposteModify requests and responses

Proxy di Funzioni di Azure consente di modificare le richieste al back-end e le risposte dal back-end.With Azure Functions Proxies, you can modify requests to and responses from the back-end. Queste trasformazioni possono usare le variabili come definito in Usare le variabili.These transformations can use variables as defined in Use variables.

Modificare la richiesta al back-endModify the back-end request

Per impostazione predefinita, la richiesta al back-end viene inizializzata come una copia della richiesta originale.By default, the back-end request is initialized as a copy of the original request. Oltre a impostare l'URL di back-end, è possibile apportare modifiche ai parametri del metodo HTTP, delle intestazioni e della stringa di query.In addition to setting the back-end URL, you can make changes to the HTTP method, headers, and query string parameters. I valori modificati possono fare riferimento alle impostazioni dell'applicazione e ai parametri della richiesta del client originale.The modified values can reference application settings and parameters from the original client request.

Le richieste di back-end possono essere modificate nel portale espandendo la sezione Override della richiesta nella pagina dei dettagli del proxy.Back-end requests can be modified in the portal by expading the request override section of the proxy detail page.

Modificare la rispostaModify the response

Per impostazione predefinita, la risposta del client viene inizializzata come una copia della risposta back-end.By default, the client response is initialized as a copy of the back-end response. È possibile apportare modifiche al codice di stato, al motivo, alle intestazioni e al corpo della risposta.You can make changes to the response's status code, reason phrase, headers, and body. I valori modificati possono fare riferimento alle impostazioni dell'applicazione, ai parametri della richiesta del client originale e ai paramenti della risposta back-end.The modified values can reference application settings, parameters from the original client request, and parameters from the back-end response.

Le richieste di back-end possono essere modificate nel portale espandendo la sezione Override della risposta nella pagina dei dettagli del proxy.Back-end requests can be modified in the portal by expading the response override section of the proxy detail page.

Usare le variabiliUse variables

La configurazione di un proxy non deve essere statica.The configuration for a proxy does not need to be static. È possibile condizionarla per fare in modo che usi le variabili della richiesta client originale, la risposta back-end o le impostazioni applicazione.You can condition it to use variables from the original client request, the back-end response, or application settings.

Fare riferimento alle funzioni localiReference local functions

È possibile usare localhost per fare direttamente riferimento a una funzione nella stessa app per le funzioni, senza una richiesta del proxy di round trip.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" farà riferimento a una funzione attivata tramite HTTP locale nella route /api/httptriggerC#1"backendurl": "https://localhost/api/httptriggerC#1" will reference a local HTTP triggered function at the route /api/httptriggerC#1

Nota

Se la funzione usa il livello di autorizzazione function, admin o sys, sarà necessario specificare il codice e il clientId in base all'URL della funzione originale.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. In questo caso il riferimento avrebbe un aspetto simile al seguente: "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>"

Parametri di riferimento della richiestaReference request parameters

I parametri della richiesta possono essere usati come input per la proprietà URL di back-end o come parte della modifica di richieste e risposte.You can use request parameters as inputs to the back-end URL property or as part of modifying requests and responses. Alcuni parametri possono essere associati dal modello di route specificato nella configurazione del proxy di base, mentre altri derivano dalle proprietà della richiesta in ingresso.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.

Parametri del modello di routeRoute template parameters

È possibile fare riferimento ai parametri usati nel modello di route in base al nome.Parameters that are used in the route template are available to be referenced by name. I nomi dei parametri sono racchiusi tra parentesi graffe ({}).The parameter names are enclosed in braces ({}).

Ad esempio, se un proxy ha un modello di route come /pets/{petId}, l'URL di back-end può includere il valore {petId}, come in https://<AnotherApp>.azurewebsites.net/api/pets/{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}. Se il modello di route termina con un carattere jolly, ad esempio /api/{*restOfPath}, il valore {restOfPath} è una rappresentazione di stringa dei segmenti del percorso rimanente della richiesta in ingresso.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.

Parametri aggiuntivi della richiestaAdditional request parameters

Oltre ai parametri del modello di route, i valori seguenti possono essere usati nei valori di configurazione:In addition to the route template parameters, the following values can be used in config values:

  • {request.method}: il metodo HTTP usato nella richiesta originale.{request.method}: The HTTP method that's used on the original request.
  • {request.headers.<HeaderName>}: un'intestazione che può essere letta dalla richiesta originale.{request.headers.<HeaderName>}: A header that can be read from the original request. Sostituire <HeaderName> con il nome dell'intestazione che si desidera leggere.Replace <HeaderName> with the name of the header that you want to read. Se l'intestazione non è inclusa nella richiesta, il valore sarà una stringa vuota.If the header is not included on the request, the value will be the empty string.
  • {request.querystring.<ParameterName>}: un parametro di stringa di query che può essere letto dalla richiesta originale.{request.querystring.<ParameterName>}: A query string parameter that can be read from the original request. Sostituire <ParameterName> con il nome del parametro che si desidera leggere.Replace <ParameterName> with the name of the parameter that you want to read. Se il parametro non è incluso nella richiesta, il valore sarà una stringa vuota.If the parameter is not included on the request, the value will be the empty string.

Parametri di riferimento della risposta dal back-endReference back-end response parameters

I parametri di risposta possono essere usati come parte della modifica della risposta al client.Response parameters can be used as part of modifying the response to the client. I valori seguenti possono essere usati nei valori di configurazione:The following values can be used in config values:

  • {backend.response.statusCode}: il codice di stato HTTP restituito nella risposta dal back-end.{backend.response.statusCode}: The HTTP status code that's returned on the back-end response.
  • {backend.response.statusReason}: la frase per il motivo HTTP restituita nella risposta dal back-end.{backend.response.statusReason}: The HTTP reason phrase that's returned on the back-end response.
  • {backend.response.headers.<HeaderName>}: un'intestazione che può essere letta dalla risposta dal back-end.{backend.response.headers.<HeaderName>}: A header that can be read from the back-end response. Sostituire <HeaderName> con il nome dell'intestazione che si desidera leggere.Replace <HeaderName> with the name of the header you want to read. Se l'intestazione non è inclusa nella risposta, il valore sarà una stringa vuota.If the header is not included on the response, the value will be the empty string.

Impostazioni di riferimento dell'applicazioneReference application settings

È anche possibile fare riferimento alle impostazioni dell'applicazione definite per l'app per le funzioni racchiudendo il nome dell'impostazione tra i segni di percentuale (%).You can also reference application settings defined for the function app by surrounding the setting name with percent signs (%).

Ad esempio, per un URL di back-end di https://%ORDER_PROCESSING_HOST%/api/orders, "%ORDER_PROCESSING_HOST%" verrà sostituito con il valore dell'impostazione 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.

Suggerimento

Usare le impostazioni dell'applicazione per gli host di back-end quando si dispone di più distribuzioni o ambienti di test.Use application settings for back-end hosts when you have multiple deployments or test environments. In questo modo, è possibile assicurarsi di comunicare sempre con il back-end corretto per quell'ambiente.That way, you can make sure that you are always talking to the right back-end for that environment.

Risolvere i problemi relativi al proxyTroubleshoot Proxies

Aggiungendo il flag "debug":true a un proxy in proxies.json si abiliterà la registrazione del debug.By adding the flag "debug":true to any proxy in your proxies.json you will enable debug logging. I log vengono archiviati in D:\home\LogFiles\Application\Proxies\DetailedTrace e sono accessibili tramite gli strumenti avanzati (Kudu).Logs are stored in D:\home\LogFiles\Application\Proxies\DetailedTrace and accessible through the advanced tools (kudu). Le risposte HTTP conterranno anche un'intestazione Proxy-Trace-Location con un URL per accedere al file di log.Any HTTP responses will also contain a Proxy-Trace-Location header with a URL to access the log file.

È possibile eseguire il debug di un proxy dal lato client aggiungendo un'intestazione Proxy-Trace-Enabled impostata su true.You can debug a proxy from the client side by adding a Proxy-Trace-Enabled header set to true. In questo modo verrà anche registrata una traccia nel file system e l'URL della traccia verrà restituito come intestazione nella risposta.This will also log a trace to the file system, and return the trace URL as a header in the response.

Bloccare le tracce del proxyBlock proxy traces

Per motivi di sicurezza, potrebbe essere necessario impedire a chiunque chiami il servizio di generare una traccia.For security reasons you may not want to allow anyone calling your service to generate a trace. Questi utenti non potranno accedere ai contenuti della traccia senza le credenziali di accesso, ma la generazione della traccia utilizza le risorse e rivela che si sta usando i proxy di funzioni.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.

Disabilitare completamente le tracce aggiungendo "debug":false a proxy specifici in proxies.json.Disable traces altogether by adding "debug":false to any particular proxy in your proxies.json.

Configurazione avanzataAdvanced configuration

I proxy configurati vengono archiviati in un file proxies.json, situato nella radice di una directory dell'app per le funzioni.The proxies that you configure are stored in a proxies.json file, which is located in the root of a function app directory. È possibile modificare manualmente questo file e distribuirlo come parte dell'app quando si usa uno dei metodi di distribuzione supportati da Funzioni.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.

Suggerimento

Se non è stato configurato uno dei metodi di distribuzione, è anche possibile usare il file proxies.json nel portale.If you have not set up one of the deployment methods, you can also work with the proxies.json file in the portal. Passare all'app per le funzioni e selezionare Funzionalità della piattaforma ed Editor del servizio app.Go to your function app, select Platform features, and then select App Service Editor. Questo consentirà di visualizzare la struttura dell'intero file dell'app per le funzioni e di apportare modifiche.By doing so, you can view the entire file structure of your function app and then make changes.

Il file proxies.json è definito da un oggetto proxy, composto da proxy denominati e dalle relative definizioni.Proxies.json is defined by a proxies object, which is composed of named proxies and their definitions. È facoltativamente possibile fare riferimento a uno schema JSON per il completamento del codice se l'editor lo supporta.Optionally, if your editor supports it, you can reference a JSON schema for code completion. Un esempio di file apparirà come segue: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>"
        }
    }
}

Ogni proxy ha un nome descrittivo, come proxy1 nell'esempio precedente.Each proxy has a friendly name, such as proxy1 in the preceding example. L'oggetto di definizione del proxy corrispondente viene definito dalle proprietà seguenti:The corresponding proxy definition object is defined by the following properties:

  • matchCondition: obbligatorio, un oggetto che definisce le richieste che attivano l'esecuzione di questo proxy.matchCondition: Required--an object defining the requests that trigger the execution of this proxy. Contiene due proprietà condivise con i trigger HTTP:It contains two properties that are shared with HTTP triggers:
    • methods: una matrice di metodi HTTP a cui il proxy risponde.methods: An array of the HTTP methods that the proxy responds to. Se non viene specificata, il proxy risponderà a tutti i metodi HTTP nel route.If it is not specified, the proxy responds to all HTTP methods on the route.
    • route: obbligatorio, definisce il modello di route, controllando a quali URL delle richieste il proxy risponde.route: Required--defines the route template, controlling which request URLs your proxy responds to. A differenza dei trigger HTTP, non vi è alcun valore predefinito.Unlike in HTTP triggers, there is no default value.
  • backendUri: l'URL della risorsa di back-end a cui la richiesta deve essere trasmessa tramite proxy.backendUri: The URL of the back-end resource to which the request should be proxied. Questo valore può fare riferimento alle impostazioni dell'applicazione e ai parametri della richiesta del client originale.This value can reference application settings and parameters from the original client request. Se questa proprietà non è inclusa, Funzioni di Azure risponde con un HTTP 200 OK.If this property is not included, Azure Functions responds with an HTTP 200 OK.
  • requestOverrides: un oggetto che definisce le trasformazioni alla richiesta al back-end.requestOverrides: An object that defines transformations to the back-end request. Vedere Definire un oggetto requestOverrides.See Define a requestOverrides object.
  • responseOverrides: un oggetto che definisce le trasformazioni alla risposta del client.responseOverrides: An object that defines transformations to the client response. Vedere Definire un oggetto responseOverrides.See Define a responseOverrides object.

Nota

La proprietà route in Proxy di Funzioni di Azure non rispetta la proprietà routePrefix della configurazione host dell'app per le funzioni.The route property in Azure Functions Proxies does not honor the routePrefix property of the Function App host configuration. Per includere un prefisso, ad esempio /api, deve essere incluso nella proprietà route.If you want to include a prefix such as /api, it must be included in the route property.

Disabilitare i singoli proxyDisable individual proxies

È possibile disabilitare un singolo proxy aggiungendo "disabled": true al proxy nel file proxies.json.You can disable individual proxies by adding "disabled": true to the proxy in the proxies.json file. In questo modo le richieste che soddisfano matchCondidtion restituiranno 404.This will cause any requests meeting the matchCondidtion to return 404.

{
    "$schema": "http://json.schemastore.org/proxies",
    "proxies": {
        "Root": {
            "disabled":true,
            "matchCondition": {
                "route": "/example"
            },
            "backendUri": "www.example.com"
        }
    }
}

Definire un oggetto requestOverridesDefine a requestOverrides object

L'oggetto requestOverrides definisce le modifiche apportate alla richiesta quando viene chiamata la risorsa back-end.The requestOverrides object defines changes made to the request when the back-end resource is called. L'oggetto viene definito dalle proprietà seguenti:The object is defined by the following properties:

  • backend.request.method: il metodo HTTP usato per chiamare il back-end.backend.request.method: The HTTP method that's used to call the back-end.
  • backend.request.querystring.<ParameterName>: un parametro di stringa di query che può essere impostato per la chiamata al back-end.backend.request.querystring.<ParameterName>: A query string parameter that can be set for the call to the back-end. Sostituire <ParameterName> con il nome del parametro che si desidera impostare.Replace <ParameterName> with the name of the parameter that you want to set. Se viene generata una stringa vuota, il parametro non viene incluso nella richiesta al back-end.If the empty string is provided, the parameter is not included on the back-end request.
  • backend.request.headers.<HeaderName>: un'intestazione che può essere impostata per la chiamata al back-end.backend.request.headers.<HeaderName>: A header that can be set for the call to the back-end. Sostituire <HeaderName> con il nome dell'intestazione che si desidera impostare.Replace <HeaderName> with the name of the header that you want to set. Se viene fornita una stringa vuota, il parametro non viene incluso nella richiesta al back-end.If you provide the empty string, the header is not included on the back-end request.

I valori possono fare riferimento alle impostazioni dell'applicazione e ai parametri della richiesta del client originale.Values can reference application settings and parameters from the original client request.

Un esempio di configurazione apparirà come segue: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%"
            }
        }
    }
}

Definire un oggetto responseOverridesDefine a responseOverrides object

L'oggetto responseOverrides definisce le modifiche apportate alla risposta passata al client.The requestOverrides object defines changes that are made to the response that's passed back to the client. L'oggetto viene definito dalle proprietà seguenti:The object is defined by the following properties:

  • response.statusCode: il codice di stato HTTP da restituire al client.response.statusCode: The HTTP status code to be returned to the client.
  • response.statusReason: la frase del motivo HTTP da restituire al client.response.statusReason: The HTTP reason phrase to be returned to the client.
  • response.body: la rappresentazione di stringa del corpo da restituire al client.response.body: The string representation of the body to be returned to the client.
  • response.headers.<HeaderName>: un'intestazione che può essere impostata per la risposta al client.response.headers.<HeaderName>: A header that can be set for the response to the client. Sostituire <HeaderName> con il nome dell'intestazione che si desidera impostare.Replace <HeaderName> with the name of the header that you want to set. Se viene fornita una stringa vuota, l'intestazione non viene inclusa nella richiesta al back-end.If you provide the empty string, the header is not included on the response.

I valori possono fare riferimento alle impostazioni dell'applicazione, ai parametri della richiesta del client originale e ai paramenti della risposta back-end.Values can reference application settings, parameters from the original client request, and parameters from the back-end response.

Un esempio di configurazione apparirà come segue: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"
            }
        }
    }
}

Nota

In questo esempio il corpo della risposta viene impostato direttamente, quindi non sono necessarie proprietà backendUri.In this example, the response body is set directly, so no backendUri property is needed. L'esempio illustra come usare i proxy di Funzioni di Azure per le API di simulazione.The example shows how you might use Azure Functions Proxies for mocking APIs.