Condividi tramite

Usare i proxy legacy

  • Articolo

Importante

Funzioni di Azure proxy è una funzionalità legacy per le versioni 1.x e 3.x del runtime di Funzioni di Azure. È possibile abilitare nuovamente il supporto per i proxy nella versione 4.x per aggiornare correttamente le app per le funzioni alla versione di runtime più recente. Non appena possibile, è necessario passare all'integrazione delle app per le funzioni con Azure Gestione API. Gestione API consente di sfruttare un set di funzionalità più completo per definire, proteggere, gestire e monetizzare le API basate su Funzioni. Per altre informazioni, vedere integrazione Gestione API.

Per informazioni su come abilitare nuovamente il supporto dei proxy in Funzioni versione 4.x, vedere Riabilitare i proxy in Funzioni v4.x.

Per semplificare la migrazione da implemetazioni proxy esistenti, questo articolo collega a contenuto equivalente Gestione API, quando disponibile.

Questo articolo illustra come configurare e usare i proxy in Funzioni di Azure. Questa funzionalità consente di specificare gli endpoint nell'app per le funzioni implementati da un'altra risorsa. È 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.

Si applicano le tariffe standard per Funzioni quando vengono eseguiti i proxy. Per altre informazioni, vedere Prezzi di Funzioni.

Riabilitare i proxy in Funzioni v4.x

Dopo aver eseguito la migrazione dell'app per le funzioni alla versione 4.x del runtime di Funzioni, sarà necessario ripristinare in modo specifico i proxy. È comunque consigliabile passare all'integrazione delle app per le funzioni con Azure Gestione API il prima possibile e non solo affidarsi ai proxy.

È necessario abilitare nuovamente i proxy per impostare un flag nell'impostazione dell'applicazione AzureWebJobsFeatureFlags in uno dei modi seguenti:

  • Se l'impostazione non esiste già, aggiungere questa impostazione all'app per le AzureWebJobsFeatureFlags funzioni con un valore di EnableProxies.

  • Se questa impostazione esiste già, aggiungere ,EnableProxies alla fine del valore esistente.

AzureWebJobsFeatureFlags è una matrice delimitata da virgole di flag usati per abilitare l'anteprima e altre funzionalità temporanee. Per altre informazioni su come creare e modificare le impostazioni dell'applicazione, vedere Usare le impostazioni dell'applicazione.

Nota

Anche quando si abilita di nuovo usando il EnableProxies flag, non è possibile usare i proxy nella portale di Azure. È invece necessario usare direttamente il file proxies.json per l'app per le funzioni. Per altre informazioni, vedere Configurazione avanzata.

Creare un proxy

Importante

Per contenuto equivalente usando Gestione API, vedere Esporre API serverless da endpoint HTTP tramite Azure Gestione API.

I proxy vengono definiti nel file proxies.json nella radice dell'app per le funzioni. I passaggi descritti in questa sezione illustrano come usare la portale di Azure per creare questo file nell'app per le funzioni. Non tutte le lingue e le combinazioni del sistema operativo supportano la modifica nel portale. Se non è possibile modificare i file dell'app per le funzioni nel portale, è invece possibile creare e distribuire il file equivalente proxies.json dalla radice della cartella del progetto locale. Per altre informazioni sul supporto per la modifica del portale, vedere Informazioni dettagliate sul supporto linguistico.

  1. Aprire il Portale di Azure e passare all'app per le funzioni.
  2. Nel riquadro sinistro selezionare Proxy e quindi +Aggiungi.
  3. Dare un nome al proxy.
  4. Configurare l'endpoint esposto in questa app per le funzioni, specificando il Modello di route e i Metodi HTTP. Questi parametri si comportano in base alle regole dei trigger HTTP.
  5. Impostare l'URL di back-end su un altro endpoint. Questo endpoint potrebbe essere una funzione in un'altra app per le funzioni oppure di qualsiasi altra API. Il valore non deve essere statico e può fare riferimento alle impostazioni e ai parametri dell'applicazione dalla richiesta client originale.
  6. Selezionare Crea.

Il proxy è ora presente come un nuovo endpoint sull'app per le funzioni. Dal punto di vista del client, è uguale a un HttpTrigger in Funzioni. È possibile provare il nuovo proxy copiando l'URL proxy e testandolo con il client HTTP preferito.

Modificare richieste e risposte

Importante

Gestione API consente di modificare il comportamento dell'API tramite la configurazione usando i criteri. I criteri sono una raccolta di istruzioni eseguite in sequenza nella richiesta o nella risposta di un'API. Per altre informazioni sui criteri di Gestione API, vedere Criteri in Azure Gestione API.

Con i proxy è possibile modificare le richieste e le risposte dal back-end. Queste trasformazioni possono usare le variabili come definito in Usare le variabili.

Modificare la richiesta al back-end

Per impostazione predefinita, la richiesta al back-end viene inizializzata come una copia della richiesta originale. Oltre a impostare l'URL di back-end, è possibile apportare modifiche ai parametri del metodo HTTP, delle intestazioni e della stringa di query. I valori modificati possono fare riferimento alle impostazioni dell'applicazione e ai parametri della richiesta del client originale.

Le richieste di back-end possono essere modificate nel portale espandendo la sezione Override della richiesta nella pagina dei dettagli del proxy.

Modificare la risposta

Per impostazione predefinita, la risposta del client viene inizializzata come una copia della risposta back-end. È possibile apportare modifiche al codice di stato, al motivo, alle intestazioni e al corpo della risposta. I valori modificati possono fare riferimento alle impostazioni dell'applicazione, ai parametri della richiesta del client originale e ai paramenti della risposta back-end.

Le risposte back-end possono essere modificate nel portale espandendo la sezione override della risposta della pagina dei dettagli del proxy.

Usare le variabili

La configurazione per un proxy non deve essere statica. È possibile condizionarla per fare in modo che usi le variabili della richiesta client originale, la risposta back-end o le impostazioni applicazione.

Fare riferimento alle funzioni locali

È possibile usare localhost per fare direttamente riferimento a una funzione nella stessa app per le funzioni, senza una richiesta del proxy di round trip.

"backendUri": "https://localhost/api/httptriggerC#1" farà riferimento a una funzione attivata tramite HTTP locale nella 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. In questo caso, il riferimento sarà simile al seguente: "backendUri": "https://localhost/api/httptriggerC#1?code=<keyvalue>&clientId=<keyname>" è consigliabile archiviare queste chiavi nelle impostazioni dell'applicazione e fare riferimento a quelli nei proxy. Ciò consente di evitare di archiviare segreti nel codice sorgente.

Parametri di riferimento della richiesta

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

Parametri del modello di route

È possibile fare riferimento ai parametri usati nel modello di route in base al nome. I nomi dei parametri sono racchiusi tra parentesi graffe ({}).

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

Parametri aggiuntivi della richiesta

Oltre ai parametri del modello di route, i valori seguenti possono essere usati nei valori di configurazione:

  • {request.method}: il metodo HTTP usato nella richiesta originale.
  • {request.headers.<HeaderName>}: un'intestazione che può essere letta dalla richiesta originale. Sostituire <HeaderName> con il nome dell'intestazione da leggere. Se l'intestazione non è inclusa nella richiesta, il valore sarà la stringa vuota.
  • {request.querystring.<ParameterName>}: un parametro di stringa di query che può essere letto dalla richiesta originale. Sostituire <ParameterName> con il nome del parametro da leggere. Se il parametro non è incluso nella richiesta, il valore sarà la stringa vuota.

Parametri di riferimento della risposta dal back-end

I parametri di risposta possono essere usati come parte della modifica della risposta al client. I valori seguenti possono essere usati nei valori di configurazione:

  • {backend.response.statusCode}: il codice di stato HTTP restituito nella risposta dal back-end.
  • {backend.response.statusReason}: la frase per il motivo HTTP restituita nella risposta dal back-end.
  • {backend.response.headers.<HeaderName>}: un'intestazione che può essere letta dalla risposta dal back-end. Sostituire <HeaderName> con il nome dell'intestazione da leggere. Se l'intestazione non è inclusa nella risposta, il valore sarà la stringa vuota.

Impostazioni di riferimento dell'applicazione

È 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 (%).

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.

Suggerimento

Usare le impostazioni dell'applicazione per gli host di back-end quando si dispone di più distribuzioni o ambienti di test. In questo modo, è possibile assicurarsi di comunicare sempre con il back-end corretto per quell'ambiente.

Risolvere i problemi relativi al proxy

Aggiungendo il flag "debug":true a qualsiasi proxy in proxies.json, si abiliterà la registrazione di debug. I log vengono archiviati in D:\home\LogFiles\Application\Proxies\DetailedTrace e sono accessibili tramite gli strumenti avanzati (Kudu). Le risposte HTTP conterranno anche un'intestazione Proxy-Trace-Location con un URL per accedere al file di log.

È possibile eseguire il debug di un proxy dal lato client aggiungendo un'intestazione Proxy-Trace-Enabled impostata su true. In questo modo verrà anche registrata una traccia nel file system e l'URL della traccia verrà restituito come intestazione nella risposta.

Bloccare le tracce del proxy

Per motivi di sicurezza, potrebbe essere necessario impedire a chiunque chiami il servizio di generare una traccia. Non saranno in grado di accedere al contenuto della traccia senza le credenziali di accesso, ma la generazione della traccia usa le risorse ed espone i proxy di funzione.

Disabilitare completamente le tracce aggiungendo "debug":false a proxy specifici in proxies.json.

Configurazione avanzata

I proxy configurati vengono archiviati in un file proxies.json, situato nella radice di una directory dell'app per le funzioni. È possibile modificare manualmente questo file e distribuirlo come parte dell'app quando si usa uno dei metodi di distribuzione supportati da Funzioni.

Suggerimento

Se non è stato configurato uno dei metodi di distribuzione, è anche possibile usare il file proxies.json nel portale. Passare all'app per le funzioni e selezionare Funzionalità della piattaforma ed Editor del servizio app. Questo consentirà di visualizzare la struttura dell'intero file dell'app per le funzioni e di apportare modifiche.

Il file proxies.json è definito da un oggetto proxy, composto da proxy denominati e dalle relative definizioni. È facoltativamente possibile fare riferimento a uno schema JSON per il completamento del codice se l'editor lo supporta. Un esempio di file apparirà come segue:

{
    "$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. L'oggetto di definizione del proxy corrispondente viene definito dalle proprietà seguenti:

  • matchCondition: obbligatorio, un oggetto che definisce le richieste che attivano l'esecuzione di questo proxy. Contiene due proprietà condivise con i trigger HTTP:
    • methods: una matrice di metodi HTTP a cui il proxy risponde. Se non viene specificato, il proxy risponde a tutti i metodi HTTP nella route.
    • route: obbligatorio, definisce il modello di route, controllando a quali URL delle richieste il proxy risponde. A differenza dei trigger HTTP, non esiste alcun valore predefinito.
  • backendUri: l'URL della risorsa di back-end a cui la richiesta deve essere trasmessa tramite proxy. Questo valore può fare riferimento alle impostazioni dell'applicazione e ai parametri della richiesta del client originale. Se questa proprietà non è inclusa, Funzioni di Azure risponde con HTTP 200 OK.
  • requestOverrides: un oggetto che definisce le trasformazioni alla richiesta al back-end. Vedere Definire un oggetto requestOverrides.
  • responseOverrides: un oggetto che definisce le trasformazioni alla risposta del client. Vedere Definire un oggetto responseOverrides.

Nota

La proprietà route in Proxy di Funzioni di Azure non rispetta la proprietà routePrefix della configurazione host dell'app per le funzioni. Per includere un prefisso, ad esempio /api, deve essere incluso nella proprietà route.

Disabilitare i singoli proxy

È possibile disabilitare un singolo proxy aggiungendo "disabled": true al proxy nel file proxies.json. In questo modo le richieste che soddisfano matchCondidtion restituiranno 404.

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

Impostazioni dell'applicazione

Il comportamento del proxy può essere controllato da diverse impostazioni dell'app. Sono tutti descritti nel riferimento alle impostazioni dell'app per le funzioni

Caratteri riservati (formattazione della stringa)

I proxy leggono tutte le stringhe all'esterno di un file JSON, utilizzando \ come carattere di escape. I proxy interpretano anche le parentesi graffe. Di seguito è riportata una serie completa di esempi.

Carattere Carattere di escape Esempio
{ or } {{ or }} {{ example }} -->{ example }
\ \\ example.com\\text.html -->example.com\text.html
" \" \"example\" -->"example"

Definire un oggetto requestOverrides

L'oggetto requestOverrides definisce le modifiche apportate alla richiesta quando viene chiamata la risorsa back-end. L'oggetto viene definito dalle proprietà seguenti:

  • backend.request.method: il metodo HTTP usato per chiamare il back-end.
  • backend.request.querystring.<ParameterName>: un parametro di stringa di query che può essere impostato per la chiamata al back-end. Sostituire <ParameterName> con il nome del parametro che si desidera impostare. Se viene specificata una stringa vuota, il parametro è ancora incluso nella richiesta back-end.
  • backend.request.headers.<HeaderName>: un'intestazione che può essere impostata per la chiamata al back-end. Sostituire <HeaderName> con il nome dell'intestazione che si desidera impostare. Se viene specificata una stringa vuota, il parametro è ancora incluso nella richiesta back-end.

I valori possono fare riferimento alle impostazioni dell'applicazione e ai parametri della richiesta del client originale.

Un esempio di configurazione apparirà come segue:

{
    "$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 responseOverrides

L'oggetto responseOverrides definisce le modifiche apportate alla risposta passata al client. L'oggetto viene definito dalle proprietà seguenti:

  • response.statusCode: il codice di stato HTTP da restituire al client.
  • response.statusReason: la frase del motivo HTTP da restituire al client.
  • response.body: la rappresentazione di stringa del corpo da restituire al client.
  • response.headers.<HeaderName>: un'intestazione che può essere impostata per la risposta al client. Sostituire <HeaderName> con il nome dell'intestazione che si desidera impostare. Se si specifica la stringa vuota, l'intestazione non viene inclusa nella risposta.

I valori possono fare riferimento alle impostazioni dell'applicazione, ai parametri della richiesta del client originale e ai paramenti della risposta back-end.

Un esempio di configurazione apparirà come segue:

{
    "$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. L'esempio illustra come usare i proxy di Funzioni di Azure per le API di simulazione.