Utilisation d’Azure Functions ProxiesWork with Azure Functions Proxies

Cet article vous explique comment configurer et utiliser Azure Functions Proxies.This article explains how to configure and work with Azure Functions Proxies. Cette fonctionnalité vous permet de spécifier des points de terminaison sur votre Function App implémentés par une autre ressource.With this feature, you can specify endpoints on your function app that are implemented by another resource. Vous pouvez utiliser ces proxys pour diviser une API de grande taille en plusieurs applications Function (comme dans une architecture microservice), tout en continuant à présenter une surface API unique aux clients.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.

Il s’agit des informations de référence pour les développeurs Azure Functions.This is reference information for Azure Functions developers. Si vous ne connaissez pas bien Azure Functions, commencez par consulter les ressources suivantes :If you're new to Azure Functions, start with the following resources:

Note

Une facturation standard s’applique à l’exécution des proxys.Standard Functions billing applies to proxy executions. Pour plus d’informations, consultez Tarification d’Azure Functions.For more information, see Azure Functions pricing.

Création d’un proxyCreate a proxy

Cette section vous explique comment créer un proxy dans le portail Functions.This section shows you how to create a proxy in the Functions portal.

  1. Ouvrez le portail Azure et accédez à votre Function App.Open the Azure portal, and then go to your function app.
  2. Dans le volet gauche, sélectionnez Nouveau proxy.In the left pane, select New proxy.
  3. Entrez un nom pour votre proxy.Provide a name for your proxy.
  4. Configurez le point de terminaison exposé sur cette Function App en spécifiant le modèle de routage et les méthodes HTTP.Configure the endpoint that's exposed on this function app by specifying the route template and HTTP methods. Ces paramètres se comportent selon les règles des déclencheurs HTTP.These parameters behave according to the rules for HTTP triggers.
  5. Définissez l’URL principale sur un autre point de terminaison.Set the backend URL to another endpoint. Il peut s’agir d’une fonction dans une autre Function App ou bien de n’importe quelle autre API.This endpoint could be a function in another function app, or it could be any other API. La valeur ne doit pas nécessairement être statique et peut faire référence aux paramètres de l’application et aux paramètres de la demande client d’origine.The value does not need to be static, and it can reference application settings and parameters from the original client request.
  6. Cliquez sur Créer.Click Create.

Votre proxy existe désormais sous la forme d’un nouveau point de terminaison de votre application de fonction.Your proxy now exists as a new endpoint on your function app. Du point de vue du client, cela équivaut à un HttpTrigger dans Azure Functions.From a client perspective, it is equivalent to an HttpTrigger in Azure Functions. Vous pouvez essayer votre nouveau proxy en copiant l’URL de proxy et en le testant avec le client HTTP de votre choix.You can try out your new proxy by copying the Proxy URL and testing it with your favorite HTTP client.

Modification de demandes et de réponsesModify requests and responses

La fonctionnalité Azure Functions Proxies vous permet de modifier les demandes envoyées au backend et les réponses reçues de ce dernier.With Azure Functions Proxies, you can modify requests to and responses from the back-end. Ces transformations peuvent impliquer l’utilisation de variables, comme décrit dans la section Utilisation de variables.These transformations can use variables as defined in Use variables.

Modification de la demande du serveur principalModify the back-end request

Par défaut, la demande du serveur principal est initialisée comme une copie de la demande d’origine.By default, the back-end request is initialized as a copy of the original request. Outre la définition de l’URL du serveur principal, vous pouvez apporter des modifications à la méthode HTTP, aux en-têtes et aux paramètres de chaîne de requête.In addition to setting the back-end URL, you can make changes to the HTTP method, headers, and query string parameters. Les valeurs modifiées peuvent faire référence aux paramètres de l’application et aux paramètres de la demande client d’origine.The modified values can reference application settings and parameters from the original client request.

Les demandes de serveur principal peuvent être modifiées dans le portail en développant la section remplacement de la requête de la page de détails du proxy.Back-end requests can be modified in the portal by expading the request override section of the proxy detail page.

Modification de la réponseModify the response

Par défaut, la réponse client est initialisée comme une copie de la réponse du serveur principal.By default, the client response is initialized as a copy of the back-end response. Vous pouvez apporter des modifications au code d’état, au motif, aux en-têtes et au corps.You can make changes to the response's status code, reason phrase, headers, and body. Les valeurs modifiées peuvent faire référence aux paramètres de l’application, aux paramètres de la demande client d’origine et aux paramètres de la réponse du serveur principal.The modified values can reference application settings, parameters from the original client request, and parameters from the back-end response.

Les demandes de serveur principal peuvent être modifiées dans le portail en développant la section remplacement de la réponse de la page de détails du proxy.Back-end requests can be modified in the portal by expading the response override section of the proxy detail page.

Utilisation de variablesUse variables

La configuration d’un proxy ne doit pas nécessairement être statique.The configuration for a proxy does not need to be static. Vous pouvez définir comme condition l’utilisation des variables de la demande client d’origine, de la réponse du backend ou des paramètres de l’application.You can condition it to use variables from the original client request, the back-end response, or application settings.

Fonctions locales de référenceReference local functions

Vous pouvez utiliser localhost pour faire référence à une fonction au sein de la même application de fonction directement, sans demande proxy en aller-retour.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" fait référence à une fonction HTTP locale à l’itinéraire /api/httptriggerC#1"backendurl": "https://localhost/api/httptriggerC#1" will reference a local HTTP triggered function at the route /api/httptriggerC#1

Note

Si votre fonction utilise des niveaux d’autorisation de fonction, administrateur ou système, vous devez fournir le code et l’ID client, conformément à l’URL d’origine de la fonction.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. Dans ce cas, la référence doit ressembler à : "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>"

Référencement des paramètres de la demandeReference request parameters

Les paramètres de la demande peuvent être entrés au niveau de la propriété d’URL du serveur principal ou peuvent être utilisés lors de la modification des demandes et des réponses.You can use request parameters as inputs to the back-end URL property or as part of modifying requests and responses. Certains paramètres peuvent être liés à partir du modèle de routage spécifié dans la configuration du proxy de base, alors que d’autres proviennent des propriétés de la demande entrante.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.

Paramètres de modèle de routageRoute template parameters

Les paramètres utilisés dans le modèle de routage peuvent être référencés par nom.Parameters that are used in the route template are available to be referenced by name. Les noms des paramètres sont placés entre accolades ({}).The parameter names are enclosed in braces ({}).

Par exemple, si un proxy dispose d’un modèle de routage du type /pets/{petId}, l’URL du serveur principal peut inclure la valeur de {petId}, comme dans 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}. Si le modèle de routage prend fin dans un caractère générique, tel que /api/{*restOfPath}, la valeur {restOfPath} est une chaîne représentant les autres segments de chemin d’accès de la demande entrante.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.

Paramètres de demande supplémentairesAdditional request parameters

Outre les paramètres de modèle de routage, les valeurs suivantes peuvent être utilisées dans les valeurs de configuration :In addition to the route template parameters, the following values can be used in config values:

  • {request.method} : méthode HTTP utilisée lors de la demande d’origine.{request.method}: The HTTP method that's used on the original request.
  • {request.headers.<HeaderName>} : un en-tête qui peut être lu à partir de la demande d’origine.{request.headers.<HeaderName>}: A header that can be read from the original request. Remplacez <HeaderName> par le nom de l’en-tête que vous souhaitez lire.Replace <HeaderName> with the name of the header that you want to read. Si l’en-tête n’est pas inclus dans la demande, la valeur sera une chaîne vide.If the header is not included on the request, the value will be the empty string.
  • {request.querystring.<ParameterName>} : un paramètre de chaîne de requête qui peut être lu à partir de la demande d’origine.{request.querystring.<ParameterName>}: A query string parameter that can be read from the original request. Remplacez <ParameterName> par le nom de l’en-tête que vous souhaitez lire.Replace <ParameterName> with the name of the parameter that you want to read. Si le paramètre n’est pas inclus dans la demande, la valeur sera une chaîne vide.If the parameter is not included on the request, the value will be the empty string.

Référencement des paramètres de réponse du serveur principalReference back-end response parameters

Les paramètres de réponse peuvent être utilisés lors de la modification de la réponse au client.Response parameters can be used as part of modifying the response to the client. Les valeurs suivantes peuvent être utilisées dans la configuration :The following values can be used in config values:

  • {backend.response.statusCode} : code d’état HTTP renvoyé dans la réponse du serveur principal.{backend.response.statusCode}: The HTTP status code that's returned on the back-end response.
  • {backend.response.statusReason} : motif HTTP renvoyé dans la réponse du serveur principal.{backend.response.statusReason}: The HTTP reason phrase that's returned on the back-end response.
  • {backend.response.headers.<HeaderName>} : en-tête pouvant être lu à partir de la réponse du serveur principal.{backend.response.headers.<HeaderName>}: A header that can be read from the back-end response. Remplacez <HeaderName> par le nom de l’en-tête que vous souhaitez lire.Replace <HeaderName> with the name of the header you want to read. Si l’en-tête n’est pas inclus dans la réponse, la valeur sera une chaîne vide.If the header is not included on the response, the value will be the empty string.

Référencement des paramètres de l’applicationReference application settings

Vous pouvez également référencer les paramètres de l’application définis pour la Function App en mettant le nom du paramètre entre signes de pourcentage (%).You can also reference application settings defined for the function app by surrounding the setting name with percent signs (%).

Par exemple, dans une URL de serveur principal de https://%ORDER_PROCESSING_HOST%/api/orders, « %ORDER_PROCESSING_HOST% » sera remplacé par la valeur du paramètre 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.

Conseil

Utilisez des paramètres d’application pour les hôtes de serveur principal lorsque vous avez plusieurs déploiements ou environnements de test.Use application settings for back-end hosts when you have multiple deployments or test environments. De cette façon, vous avez l’assurance de toujours parler au backend adapté à cet environnement.That way, you can make sure that you are always talking to the right back-end for that environment.

Résolution des problèmes de proxyTroubleshoot Proxies

En ajoutant l’indicateur "debug":true à tout proxy de votre instance proxies.json, vous activez la journalisation du débogage.By adding the flag "debug":true to any proxy in your proxies.json you will enable debug logging. Les journaux sont stockés dans D:\home\LogFiles\Application\Proxies\DetailedTrace et accessibles via les outils avancés (kudu).Logs are stored in D:\home\LogFiles\Application\Proxies\DetailedTrace and accessible through the advanced tools (kudu). Toute réponse HTTP comporte également un en-tête Proxy-Trace-Location avec une URL dirigeant vers le fichier journal.Any HTTP responses will also contain a Proxy-Trace-Location header with a URL to access the log file.

Pour déboguer un proxy du côté client, ajoutez un jeu d’en-têtes Proxy-Trace-Enabled à true.You can debug a proxy from the client side by adding a Proxy-Trace-Enabled header set to true. Ce faisant, vous enregistrez également une trace sur le système de fichiers et renvoyez l’URL de suivi en tant qu’en-tête dans la réponse.This will also log a trace to the file system, and return the trace URL as a header in the response.

Bloquer les traces de proxyBlock proxy traces

Pour des raisons de sécurité, vous pouvez interdire tout appel à votre service et ainsi éviter toute génération de trace.For security reasons you may not want to allow anyone calling your service to generate a trace. Le cas échéant, les utilisateurs ne pourront pas accéder aux contenu de suivi sans vos informations de connexion. Notez toutefois que la génération de trace consomme des ressources et expose votre utilisation des proxys de fonction.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.

Désactivez les traces en ajoutant "debug":false à tout proxy de votre instance proxies.json.Disable traces altogether by adding "debug":false to any particular proxy in your proxies.json.

Configuration avancéeAdvanced configuration

Les serveurs proxy que vous configurez sont stockés dans un fichier proxies.json situé à la racine d’un répertoire de Function App.The proxies that you configure are stored in a proxies.json file, which is located in the root of a function app directory. Vous pouvez modifier manuellement ce fichier et le déployer dans le cadre de votre application lors de l’utilisation de l’une des méthodes de déploiement prises en charge par Functions.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.

Conseil

Si vous n’avez pas configuré l’une des méthodes de déploiement, vous pouvez également utiliser le fichier proxies.json dans le portail.If you have not set up one of the deployment methods, you can also work with the proxies.json file in the portal. Accédez à votre Function App et sélectionnez Fonctionnalités de la plateforme, puis Éditeur App Service.Go to your function app, select Platform features, and then select App Service Editor. Cela vous permettra d’afficher l’ensemble de la structure de fichiers de votre Function App et d’y apporter des modifications.By doing so, you can view the entire file structure of your function app and then make changes.

Proxies.json est défini par un objet proxy, composé de proxys nommés et de leurs définitions.Proxies.json is defined by a proxies object, which is composed of named proxies and their definitions. Vous pouvez éventuellement référencer un schéma JSON de complétion de code si votre éditeur est compatible.Optionally, if your editor supports it, you can reference a JSON schema for code completion. Voici un exemple de fichier :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>"
        }
    }
}

Chaque proxy a un nom convivial, tel que proxy1 dans l’exemple ci-dessus.Each proxy has a friendly name, such as proxy1 in the preceding example. L’objet de définition de proxy correspondant est défini par les propriétés suivantes :The corresponding proxy definition object is defined by the following properties:

  • matchCondition : Obligatoire - un objet définissant les demandes qui déclenchent l’exécution de ce proxy.matchCondition: Required--an object defining the requests that trigger the execution of this proxy. Il contient deux propriétés partagées avec les déclencheurs HTTP :It contains two properties that are shared with HTTP triggers:
    • méthodes : un tableau des méthodes HTTP auxquelles le proxy répond.methods: An array of the HTTP methods that the proxy responds to. À défaut de spécification, le proxy répond à toutes les méthodes HTTP sur le routage.If it is not specified, the proxy responds to all HTTP methods on the route.
    • route : Obligatoire - définit le modèle de routage, en contrôlant les URL de demande auxquelles votre proxy répond.route: Required--defines the route template, controlling which request URLs your proxy responds to. Contrairement aux déclencheurs HTTP, il n’y a pas de valeur par défaut.Unlike in HTTP triggers, there is no default value.
  • backendUri : l’URL de la ressource principale à laquelle la demande doit être transmise par proxy.backendUri: The URL of the back-end resource to which the request should be proxied. Cette valeur peut faire référence aux paramètres de l’application et à ceux de la demande client d’origine.This value can reference application settings and parameters from the original client request. Si cette propriété n’est pas incluse, Azure Functions répond avec un message HTTP 200 OK.If this property is not included, Azure Functions responds with an HTTP 200 OK.
  • requestOverrides : un objet définissant les transformations apportées à la demande du serveur principal.requestOverrides: An object that defines transformations to the back-end request. Consultez la section Définition d’un objet requestOverrides.See Define a requestOverrides object.
  • responseOverrides : un objet définissant les transformations apportées à la réponse client.responseOverrides: An object that defines transformations to the client response. Consultez la section Définition d’un objet responseOverrides.See Define a responseOverrides object.

Note

La propriété route dans Azure Functions Proxies n’honore pas la propriété routePrefix de la configuration d’hôte Function App.The route property in Azure Functions Proxies does not honor the routePrefix property of the Function App host configuration. Si vous souhaitez inclure un préfixe tel que /api, il doit être inclus dans la propriété route.If you want to include a prefix such as /api, it must be included in the route property.

Désactiver des proxys individuelsDisable individual proxies

Pour désactivez des proxys individuels, ajoutez "disabled": true au proxy considéré dans le fichier proxies.json.You can disable individual proxies by adding "disabled": true to the proxy in the proxies.json file. Ainsi, toute requête correspondant à matchCondition renverra une erreur 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"
        }
    }
}

Définition d’un objet requestOverridesDefine a requestOverrides object

L’objet requestOverrides définit les modifications apportées à la demande lors de l’appel de la ressource du serveur principal.The requestOverrides object defines changes made to the request when the back-end resource is called. L’objet est défini par les propriétés suivantes :The object is defined by the following properties:

  • backend.request.method : méthode HTTP utilisée pour appeler le backend.backend.request.method: The HTTP method that's used to call the back-end.
  • backend.request.querystring.<ParameterName> : paramètre de chaîne de requête pouvant être défini pour l’appel au backend.backend.request.querystring.<ParameterName>: A query string parameter that can be set for the call to the back-end. Remplacez <ParameterName> par le nom de l’en-tête que vous souhaitez définir.Replace <ParameterName> with the name of the parameter that you want to set. Si une chaîne vide est fournie, le paramètre n’est pas inclus dans la demande du serveur principal.If the empty string is provided, the parameter is not included on the back-end request.
  • backend.request.headers.<HeaderName> : en-tête qui peut être défini pour l’appel au backend.backend.request.headers.<HeaderName>: A header that can be set for the call to the back-end. Remplacez <HeaderName> par le nom de l’en-tête que vous souhaitez définir.Replace <HeaderName> with the name of the header that you want to set. Si vous fournissez une chaîne vide, l’en-tête n’est pas inclus dans la demande du serveur principal.If you provide the empty string, the header is not included on the back-end request.

Les valeurs peuvent faire référence aux paramètres de l’application et aux paramètres de la demande client d’origine.Values can reference application settings and parameters from the original client request.

Voici un exemple de configuration :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%"
            }
        }
    }
}

Définition d’un objet responseOverridesDefine a responseOverrides object

L’objet requestOverrides définit les modifications apportées à la réponse retransmise au client.The requestOverrides object defines changes that are made to the response that's passed back to the client. L’objet est défini par les propriétés suivantes :The object is defined by the following properties:

  • response.statusCode : code d’état HTTP à renvoyer au client.response.statusCode: The HTTP status code to be returned to the client.
  • response.statusReason : motif HTTP à renvoyer au client.response.statusReason: The HTTP reason phrase to be returned to the client.
  • response.body : la représentation sous forme de chaîne du corps à renvoyer au client.response.body: The string representation of the body to be returned to the client.
  • response.headers.<HeaderName> : un en-tête pouvant être défini pour la réponse au client.response.headers.<HeaderName>: A header that can be set for the response to the client. Remplacez <HeaderName> par le nom de l’en-tête que vous souhaitez définir.Replace <HeaderName> with the name of the header that you want to set. Si vous fournissez une chaîne vide, l’en-tête n’est pas inclus dans la réponse.If you provide the empty string, the header is not included on the response.

Les valeurs peuvent faire référence aux paramètres de l’application, aux paramètres de la demande client d’origine et aux paramètres de la réponse du serveur principal.Values can reference application settings, parameters from the original client request, and parameters from the back-end response.

Voici un exemple de configuration :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"
            }
        }
    }
}

Note

Dans cet exemple, le corps de la réponse est défini directement. Aucune propriété backendUri n’est nécessaire.In this example, the response body is set directly, so no backendUri property is needed. Cet exemple illustre comment utiliser les Proxys Azure Functions pour simuler des API.The example shows how you might use Azure Functions Proxies for mocking APIs.