Werken met verouderde proxy's

Artikel
02/28/2024

Belangrijk

Azure Functions-proxy's is een verouderde functie voor versies 1.x tot en met 3.x van de Azure Functions-runtime. Ondersteuning voor proxy's kan opnieuw worden ingeschakeld in versie 4.x, zodat u uw functie-apps kunt upgraden naar de nieuwste runtimeversie. Zo snel mogelijk moet u overschakelen naar de integratie van uw functie-apps met Azure API Management. Met API Management kunt u profiteren van een uitgebreidere set functies voor het definiëren, beveiligen, beheren en geld verdienen met uw op Functions gebaseerde API's. Zie API Management-integratie voor meer informatie.

Zie Proxy's opnieuw inschakelen in Functions versie 4.x voor meer informatie over het opnieuw inschakelen van proxy's in Functions v4.x.

Om het eenvoudiger te maken om te migreren van bestaande proxyimplicaties, wordt in dit artikel een koppeling gemaakt naar equivalente API Management-inhoud, indien beschikbaar.

In dit artikel wordt uitgelegd hoe u Azure Functions-proxy's configureert en gebruikt. Met deze functie kunt u eindpunten opgeven in uw functie-app die door een andere resource worden geïmplementeerd. U kunt deze proxy's gebruiken om een grote API op te splitsen in meerdere functie-apps (zoals in een microservicearchitectuur), terwijl u nog steeds één API-oppervlak voor clients presenteert.

De facturering van Standard Functions is van toepassing op proxyuitvoeringen. Zie Prijzen voor Azure Functions voor meer informatie.

Proxy's opnieuw inschakelen in Functions v4.x

Nadat u uw functie-app hebt gemigreerd naar versie 4.x van de Functions-runtime, moet u specifiek proxy's opnieuw inschakelen. U moet nog steeds zo snel mogelijk overschakelen naar de integratie van uw functie-apps met Azure API Management en niet alleen afhankelijk zijn van proxy's.

Voor het opnieuw inschakelen van proxy's moet u een vlag instellen in de AzureWebJobsFeatureFlags toepassingsinstelling op een van de volgende manieren:

Als de AzureWebJobsFeatureFlags instelling nog niet bestaat, voegt u deze instelling toe aan uw functie-app met een waarde van EnableProxies.
Als deze instelling al bestaat, voegt u deze toe ,EnableProxies aan het einde van de bestaande waarde.

AzureWebJobsFeatureFlags is een door komma's gescheiden matrix met vlaggen die worden gebruikt om preview en andere tijdelijke functies in te schakelen. Zie Werken met toepassingsinstellingen voor meer informatie over het maken en wijzigen van toepassingsinstellingen.

Notitie

Zelfs wanneer de vlag opnieuw wordt ingeschakeld EnableProxies , kunt u niet werken met proxy's in Azure Portal. In plaats daarvan moet u rechtstreeks met het proxies.json-bestand voor uw functie-app werken. Zie Geavanceerde configuratie voor meer informatie.

Een proxy maken

Belangrijk

Zie Serverloze API's beschikbaar maken van HTTP-eindpunten met behulp van Azure API Management voor gelijkwaardige inhoud met API Management.

Proxy's worden gedefinieerd in het proxies.json-bestand in de hoofdmap van uw functie-app. In de stappen in deze sectie ziet u hoe u Azure Portal gebruikt om dit bestand te maken in uw functie-app. Niet alle talen en combinaties van besturingssystemen ondersteunen bewerken in de portal. Als u uw functie-app-bestanden niet kunt wijzigen in de portal, kunt u in plaats daarvan het equivalente proxies.json bestand maken en implementeren vanuit de hoofdmap van uw lokale projectmap. Zie Taalondersteuning voor meer informatie over ondersteuning voor portalbewerkingen.

Open Azure Portal en ga vervolgens naar uw functie-app.
Selecteer proxy's in het linkerdeelvenster en selecteer vervolgens +Toevoegen.
Geef een naam op voor uw proxy.
Configureer het eindpunt dat beschikbaar is in deze functie-app door de routesjabloon en HTTP-methoden op te geven. Deze parameters gedragen zich volgens de regels voor HTTP-triggers.
Stel de back-end-URL in op een ander eindpunt. Dit eindpunt kan een functie zijn in een andere functie-app of een andere API. De waarde hoeft niet statisch te zijn en kan verwijzen naar toepassingsinstellingen en -parameters van de oorspronkelijke clientaanvraag.
Selecteer Maken.

Uw proxy bestaat nu als een nieuw eindpunt in uw functie-app. Vanuit het perspectief van een client is dit hetzelfde als een HttpTrigger in Functions. U kunt uw nieuwe proxy uitproberen door de proxy-URL te kopiëren en deze te testen met uw favoriete HTTP-client.

Aanvragen en antwoorden wijzigen

Belangrijk

Met API Management kunt u het API-gedrag wijzigen via configuratie met behulp van beleid. Beleidsregels zijn een verzameling instructies die sequentieel worden uitgevoerd op de aanvraag of het antwoord van een API. Zie Beleid in Azure API Management voor meer informatie over API Management-beleid.

Met proxy's kunt u aanvragen wijzigen naar en antwoorden van de back-end. Deze transformaties kunnen variabelen gebruiken zoals gedefinieerd in Variabelen gebruiken.

De back-endaanvraag wijzigen

De back-endaanvraag wordt standaard geïnitialiseerd als een kopie van de oorspronkelijke aanvraag. Naast het instellen van de back-end-URL kunt u wijzigingen aanbrengen in de HTTP-methode, headers en queryreeksparameters. De gewijzigde waarden kunnen verwijzen naar toepassingsinstellingen en -parameters uit de oorspronkelijke clientaanvraag.

Back-endaanvragen kunnen worden gewijzigd in de portal door de sectie voor het overschrijven van aanvragen van de pagina met proxydetails uit te vouwen.

Het antwoord wijzigen

Standaard wordt het clientantwoord geïnitialiseerd als een kopie van het back-endantwoord. U kunt wijzigingen aanbrengen in de statuscode van het antwoord, de redengroep, headers en de hoofdtekst. De gewijzigde waarden kunnen verwijzen naar toepassingsinstellingen, parameters uit de oorspronkelijke clientaanvraag en parameters uit het back-endantwoord.

Back-endantwoorden kunnen worden gewijzigd in de portal door de sectie antwoordoverschrijven van de pagina met proxydetails uit te vouwen.

Variabelen gebruiken

De configuratie voor een proxy hoeft niet statisch te zijn. U kunt deze voorwaarde stellen voor het gebruik van variabelen uit de oorspronkelijke clientaanvraag, het back-endantwoord of toepassingsinstellingen.

Naslaginformatie over lokale functies

U kunt localhost rechtstreeks verwijzen naar een functie in dezelfde functie-app, zonder een retourproxyaanvraag.

"backendUri": "https://localhost/api/httptriggerC#1" verwijst naar een lokale door HTTP geactiveerde functie op de route /api/httptriggerC#1

Notitie

Als uw functie gebruikmaakt van functie-, beheerder- of sys-autorisatieniveaus , moet u de code en clientId opgeven op basis van de oorspronkelijke functie-URL. In dit geval zou de verwijzing er als volgt uitzien: "backendUri": "https://localhost/api/httptriggerC#1?code=<keyvalue>&clientId=<keyname>" we raden u aan deze sleutels op te slaan in toepassingsinstellingen en te verwijzen naar de sleutels in uw proxy's. Hiermee voorkomt u dat geheimen in uw broncode worden opgeslagen.

Referentieaanvraagparameters

U kunt aanvraagparameters gebruiken als invoer voor de eigenschap back-end-URL of als onderdeel van het wijzigen van aanvragen en antwoorden. Sommige parameters kunnen worden gebonden aan de routesjabloon die is opgegeven in de basisproxyconfiguratie en andere parameters kunnen afkomstig zijn van eigenschappen van de binnenkomende aanvraag.

Parameters voor routesjabloon

Parameters die in de routesjabloon worden gebruikt, kunnen op naam worden verwezen. De parameternamen staan tussen accolades ({}).

Als een proxy bijvoorbeeld een routesjabloon heeft, zoals /pets/{petId}de back-end-URL, kan de waarde van {petId}, zoals in https://<AnotherApp>.azurewebsites.net/api/pets/{petId}. Als de routesjabloon wordt beëindigd in een jokerteken, zoals /api/{*restOfPath}, is de waarde {restOfPath} een tekenreeksweergave van de resterende padsegmenten van de binnenkomende aanvraag.

Aanvullende aanvraagparameters

Naast de parameters van de routesjabloon kunnen de volgende waarden worden gebruikt in configuratiewaarden:

{request.method}: de HTTP-methode die wordt gebruikt voor de oorspronkelijke aanvraag.
{request.headers.<HeaderName>}: een header die kan worden gelezen uit de oorspronkelijke aanvraag. Vervang <HeaderName> door de naam van de header die u wilt lezen. Als de header niet is opgenomen in de aanvraag, is de waarde de lege tekenreeks.
{request.querystring.<ParameterName>}: een queryreeksparameter die kan worden gelezen uit de oorspronkelijke aanvraag. Vervang <ParameterName> door de naam van de parameter die u wilt lezen. Als de parameter niet is opgenomen in de aanvraag, is de waarde de lege tekenreeks.

Antwoordparameters voor back-endverwijzingen

Antwoordparameters kunnen worden gebruikt als onderdeel van het wijzigen van het antwoord op de client. De volgende waarden kunnen worden gebruikt in configuratiewaarden:

{backend.response.statusCode}: de HTTP-statuscode die wordt geretourneerd in het back-endantwoord.
{backend.response.statusReason}: de HTTP-redenzin die wordt geretourneerd in het back-endantwoord.
{backend.response.headers.<HeaderName>}: een header die kan worden gelezen vanuit het back-endantwoord. Vervang <HeaderName> door de naam van de koptekst die u wilt lezen. Als de header niet is opgenomen in het antwoord, is de waarde de lege tekenreeks.

Referentietoepassingsinstellingen

U kunt ook verwijzen naar toepassingsinstellingen die zijn gedefinieerd voor de functie-app door de naam van de instelling te omringen met procenttekens (%).

Een back-end-URL van https://%ORDER_PROCESSING_HOST%/api/orders '%ORDER_PROCESSING_HOST%' wordt bijvoorbeeld vervangen door de waarde van de ORDER_PROCESSING_HOST-instelling.

Tip

Gebruik toepassingsinstellingen voor back-endhosts wanneer u meerdere implementaties of testomgevingen hebt. Op die manier kunt u ervoor zorgen dat u altijd met de juiste back-end voor die omgeving praat.

Problemen met proxy's oplossen

Door de vlag "debug":true toe te voegen aan een proxy in uw proxies.jsonproxy, schakelt u logboekregistratie voor foutopsporing in. Logboeken worden opgeslagen in D:\home\LogFiles\Application\Proxies\DetailedTrace en toegankelijk via de geavanceerde hulpprogramma's (kudu). HTTP-antwoorden bevatten ook een Proxy-Trace-Location header met een URL voor toegang tot het logboekbestand.

U kunt fouten opsporen in een proxy van de client door een Proxy-Trace-Enabled headerset toe te voegen aan true. Hiermee wordt ook een tracering naar het bestandssysteem vastgelegd en wordt de tracerings-URL als header in het antwoord geretourneerd.

Proxytraceringen blokkeren

Om veiligheidsredenen wilt u mogelijk niet toestaan dat iemand die uw service aanroept, een trace genereert. Ze hebben geen toegang tot de traceringsinhoud zonder uw aanmeldingsreferenties, maar het genereren van de tracering verbruikt resources en stelt dat u functieproxy's gebruikt.

Schakel traceringen helemaal uit door toe te voegen "debug":false aan een bepaalde proxy in uw proxies.json.

Geavanceerde configuratie

De proxy's die u configureert, worden opgeslagen in een proxies.json-bestand , dat zich in de hoofdmap van een functie-app-map bevindt. U kunt dit bestand handmatig bewerken en implementeren als onderdeel van uw app wanneer u een van de implementatiemethoden gebruikt die door Functions worden ondersteund.

Tip

Als u geen van de implementatiemethoden hebt ingesteld, kunt u ook werken met het proxies.json-bestand in de portal. Ga naar uw functie-app, selecteer Platformfuncties en selecteer vervolgens App Service Editor. Hierdoor kunt u de volledige bestandsstructuur van uw functie-app bekijken en vervolgens wijzigingen aanbrengen.

Proxies.json wordt gedefinieerd door een proxyobject, dat bestaat uit benoemde proxy's en de bijbehorende definities. Als uw editor dit ondersteunt, kunt u desgewenst verwijzen naar een JSON-schema voor het voltooien van de code. Een voorbeeldbestand kan er als volgt uitzien:

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

Elke proxy heeft een beschrijvende naam, zoals proxy1 in het voorgaande voorbeeld. Het bijbehorende proxydefinitieobject wordt gedefinieerd door de volgende eigenschappen:

matchCondition: vereist: een object dat de aanvragen definieert die de uitvoering van deze proxy activeren. Het bevat twee eigenschappen die worden gedeeld met HTTP-triggers:
- methoden: Een matrix van de HTTP-methoden waarop de proxy reageert. Als deze niet is opgegeven, reageert de proxy op alle HTTP-methoden op de route.
- route: Vereist: definieert de routesjabloon, waarmee wordt bepaald op welke aanvraag-URL's uw proxy reageert. In tegenstelling tot HTTP-triggers is er geen standaardwaarde.
backendUri: de URL van de back-endresource waarnaar de aanvraag moet worden geproxied. Deze waarde kan verwijzen naar toepassingsinstellingen en -parameters van de oorspronkelijke clientaanvraag. Als deze eigenschap niet is opgenomen, reageert Azure Functions met een HTTP 200 OK.
requestOverrides: een object dat transformaties naar de back-endaanvraag definieert. Zie Een requestOverrides-object definiëren.
responseOverrides: een object dat transformaties naar het clientantwoord definieert. Zie Een responseOverrides-object definiëren.

Notitie

De route-eigenschap in Azure Functions-proxy's voldoet niet aan de eigenschap routePrefix van de configuratie van de functie-app-host. Als u een voorvoegsel wilt opnemen, zoals /api, moet dit worden opgenomen in de route-eigenschap .

Afzonderlijke proxy's uitschakelen

U kunt afzonderlijke proxy's uitschakelen door deze toe te voegen aan "disabled": true de proxy in het proxies.json bestand. Dit zorgt ervoor dat alle verzoeken die voldoen aan de matchCondition, 404 retourneren.

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

Toepassingsinstellingen

Het proxygedrag kan worden beheerd door verschillende app-instellingen. Ze worden allemaal beschreven in de naslaginformatie voor de Functions-app Instellingen

Gereserveerde tekens (tekenreeksopmaak)

Proxy's lezen alle tekenreeksen uit een JSON-bestand, met \als escape-symbool. Proxy's interpreteren ook accolades. Bekijk hieronder een volledige set voorbeelden.

Teken	Escape-teken	Opmerking
{ of }	{{ of }}	`{{ example }}` -->`{ example }`
\	\\	`example.com\\text.html` -->`example.com\text.html`
"	\"	`\"example\"` -->`"example"`

Een requestOverrides-object definiëren

Het object requestOverrides definieert wijzigingen in de aanvraag wanneer de back-endresource wordt aangeroepen. Het object wordt gedefinieerd door de volgende eigenschappen:

backend.request.method: de HTTP-methode die wordt gebruikt om de back-end aan te roepen.
backend.request.querystring.<ParameterName>: een queryreeksparameter die kan worden ingesteld voor de aanroep naar de back-end. Vervang <ParameterName> door de naam van de parameter die u wilt instellen. Als er een lege tekenreeks wordt opgegeven, wordt de parameter nog steeds opgenomen in de back-endaanvraag.
backend.request.headers.<HeaderName>: een header die kan worden ingesteld voor de aanroep naar de back-end. Vervang <HeaderName> door de naam van de header die u wilt instellen. Als er een lege tekenreeks wordt opgegeven, wordt de parameter nog steeds opgenomen in de back-endaanvraag.

Waarden kunnen verwijzen naar toepassingsinstellingen en -parameters uit de oorspronkelijke clientaanvraag.

Een voorbeeldconfiguratie kan er als volgt uitzien:

{
    "$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%"
            }
        }
    }
}

Een responseOverrides-object definiëren

Het object requestOverrides definieert wijzigingen die worden aangebracht in het antwoord dat aan de client wordt doorgegeven. Het object wordt gedefinieerd door de volgende eigenschappen:

response.statusCode: de HTTP-statuscode die moet worden geretourneerd naar de client.
response.statusReason: De HTTP-redenzin die moet worden geretourneerd naar de client.
response.body: De tekenreeksweergave van de hoofdtekst die moet worden geretourneerd aan de client.
response.headers.<HeaderName>: een header die kan worden ingesteld voor het antwoord op de client. Vervang <HeaderName> door de naam van de header die u wilt instellen. Als u de lege tekenreeks opgeeft, wordt de header niet opgenomen in het antwoord.

Waarden kunnen verwijzen naar toepassingsinstellingen, parameters van de oorspronkelijke clientaanvraag en parameters uit het back-endantwoord.

Een voorbeeldconfiguratie kan er als volgt uitzien:

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

Notitie

In dit voorbeeld wordt de hoofdtekst van het antwoord rechtstreeks ingesteld, dus er is geen backendUri eigenschap nodig. In het voorbeeld ziet u hoe u Azure Functions-proxy's kunt gebruiken voor het mocken van API's.

Werken met verouderde proxy's

Proxy's opnieuw inschakelen in Functions v4.x

Een proxy maken

Aanvragen en antwoorden wijzigen

De back-endaanvraag wijzigen

Het antwoord wijzigen

Variabelen gebruiken

Naslaginformatie over lokale functies

Referentieaanvraagparameters

Parameters voor routesjabloon

Aanvullende aanvraagparameters

Antwoordparameters voor back-endverwijzingen

Referentietoepassingsinstellingen

Problemen met proxy's oplossen

Proxytraceringen blokkeren

Geavanceerde configuratie

Afzonderlijke proxy's uitschakelen

Toepassingsinstellingen

Gereserveerde tekens (tekenreeksopmaak)

Een requestOverrides-object definiëren

Een responseOverrides-object definiëren

Aanvullende resources