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

Con il proxy di funzioni di Azure, è possibile modificare le richieste di e le risposte del server 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].

Attualmente non esiste un'esperienza del portale per la modifica delle richieste al back-end.Currently, there is no portal experience for modifying back-end requests. Per informazioni su come applicare questa funzionalità proxies.json, vedere definire un oggetto requestOverrides.To learn how to apply this capability from proxies.json, see [Define a requestOverrides object].

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].

Attualmente non esiste un'esperienza del portale per la modifica delle risposte del back-end.Currently, there is no portal experience for modifying responses. Per informazioni su come applicare questa funzionalità proxies.json, vedere definire un oggetto responseOverrides.To learn how to apply this capability from proxies.json, see [Define a responseOverrides object].

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 condizione per utilizzare le variabili di richiesta del client originale, la risposta di back-end o le impostazioni dell'applicazione.You can condition it to use variables from the original client request, the back-end response, or application settings.

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 è incluso 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 l'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 che si sono sempre parlando destra back-end per tale ambiente.That way, you can make sure that you are always talking to the right back-end for that environment.

Configurazione avanzataAdvanced configuration

I proxy configurate vengono archiviati in un proxies.json file, che si trova nella radice di una directory di app di funzione.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. La funzionalità proxy di funzioni di Azure deve essere abilitato per il file da elaborare.The Azure Functions Proxies feature must be enabled for the file to be processed.

Suggerimento

Se non impostati uno dei metodi di distribuzione, è inoltre possibile utilizzare con il proxies.json file 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.

Proxies.JSON è definito da un oggetto proxy, che è costituito da un proxy denominato e le 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

Il route proprietà in Azure funzioni proxy non rispetta il routePrefix proprietà della configurazione degli host funzione App.The route property in Azure Functions Proxies does not honor the routePrefix property of the Function App host configuration. Se si desidera includere un prefisso, ad esempio /api, deve essere incluso nel route proprietà.If you want to include a prefix such as /api, it must be included in the route property.

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 utilizzato per chiamare 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 è possibile impostare 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, pertanto non backendUri proprietà necessaria.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.

Abilitare i proxy di Funzioni di AzureEnable Azure Functions Proxies

I proxy sono ora abilitati per impostazione predefinita.Proxies are now enabled by default! Se si usa una versione precedente dell'anteprima dei proxy e i proxy sono disattivati, è necessario attivarli manualmente una sola volta per eseguirli.If you were using an older version of the proxies preview and disabled proxies, you will need to manually enable proxies once in order for proxies to execute.

  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. Selezionare Impostazioni dell'app per le funzioni.Select Function app settings.
  3. Impostare Abilita Proxy di Funzioni di Azure (anteprima) su On.Switch Enable Azure Functions Proxies (preview) to On.

È inoltre possibile ritornare qui per aggiornare il runtime del proxy man mano che le nuove funzioni diventano disponibili.You can also return here to update the proxy runtime as new features become available.