Vous consultez la documentation sur Apigee Edge.
Consultez la documentation sur Apigee X.
En tant que développeur travaillant avec Apigee Edge, vos principales activités de développement impliquent la configuration de proxys d'API qui fonctionnent comme des proxys pour les API ou les services de backend. Ce document fait référence à tous les éléments de configuration disponibles lors de la création de proxys d'API.
Si vous apprenez à créer des proxys d'API, nous vous recommandons de commencer par le sujet Créer un proxy d'API simple.
Voici les méthodes les plus courantes pour modifier des configurations de proxy:
- Utilisation de l'éditeur XML dans l'interface utilisateur Edge
- Téléchargez la configuration et modifiez-la localement, comme décrit dans la section Développement local des configurations de proxy.
Développement local des configurations de proxy
Vous pouvez télécharger vos configurations de proxy afin de les modifier sur un ordinateur local. Lorsque vous avez terminé, vous importez les résultats dans Edge. Cette approche vous permet d'intégrer les configurations de proxy dans votre contrôle source, la gestion des versions et d'autres workflows partagés. De plus, en travaillant sur une configuration de proxy localement, vous pouvez utiliser votre propre éditeur XML et vos propres outils de validation.
Cette section explique comment utiliser l'interface utilisateur pour télécharger un proxy proxy existant, le modifier, puis le réimporter dans Edge pour le déployer. Vous pouvez également utiliser apigeetool pour télécharger et déployer une nouvelle configuration de proxy (à l'aide des commandes fetchproxy
et deployproxy
, respectivement).
Pour modifier une configuration de proxy localement à l'aide de l'interface utilisateur :
- Téléchargez la configuration de proxy actuelle dans l'interface utilisateur Edge. Dans la vue Proxys d'API, sélectionnez Project > Download Révision (Projet > Télécharger la révision).
- Sur votre ordinateur local, créez un répertoire et développez-y le fichier ZIP téléchargé.
Pour développer le fichier ZIP, vous pouvez utiliser un utilitaire tel que
unzip
, comme le montre l'exemple suivant :mkdir myappdir
unzip ./my-app_app_rev3_2019_04_20.zip -d myappdir
Le contenu développé du fichier ZIP doit être semblable à la structure décrite dans la structure de proxy de l'API.
- Modifiez les fichiers sources si nécessaire. Pour obtenir une description des fichiers sources d'une configuration de proxy, consultez la section Fichiers de configuration et structure de répertoires d'un proxy d'API.
Par exemple, pour activer la surveillance de l'état dans votre proxy d'API, modifiez le fichier de configuration TargetEndpoint dans le répertoire
/apiproxy/targets/
. Le fichier par défaut dans ce répertoire estdefault.xml
, mais il peut y avoir des fichiers avec des noms différents si vous utilisez des cibles conditionnelles.Dans ce cas, si le fichier de configuration TargetEndpoint et son répertoire n'existent pas, créez-les.
- Une fois les fichiers de configuration du proxy modifiés, veillez à enregistrer vos modifications.
- Accédez au répertoire que vous avez créé lorsque vous avez développé les fichiers ZIP (racine des fichiers de configuration développés).
Par exemple, si vous avez développé les fichiers dans le répertoire
/myappdir
, accédez à ce répertoire, comme le montre l'exemple suivant :cd myappdir
Vous devez passer à ce répertoire avant de réarchiver vos fichiers de configuration de proxy, car vous ne souhaitez pas que le répertoire
/myappdir
soit inclus dans le fichier ZIP. Le répertoire de premier niveau dans le fichier ZIP doit être/apiproxy
. - Réarchivez les fichiers de configuration du proxy, y compris les fichiers nouveaux ou modifiés. Vous pouvez utiliser un utilitaire tel que
zip
, comme le montre l'exemple suivant :zip my-new-proxy.zip -r .
Le répertoire de premier niveau dans le fichier ZIP doit être
/apiproxy
.Le nom du fichier ZIP ne nécessite aucune condition particulière. Par exemple, vous n'avez pas besoin d'incrémenter le numéro de révision ou de spécifier la date dans le nom de fichier, mais cela peut être utile pour le débogage ou le contrôle de la source.
Edge incrémente le numéro de révision de la nouvelle configuration de proxy pour vous lorsque vous l'importez.
- Importez la nouvelle configuration de proxy à l'aide de l'interface utilisateur Edge. Dans la vue API Proxies (Proxys d'API), sélectionnez Project > Upload a New Révision (Projet > Importer une nouvelle révision).
Si vous obtenez une erreur telle que Bundle is invalid. Empty bundle., assurez-vous que le répertoire racine de votre fichier ZIP est
/apiproxy
. Si ce n'est pas le cas, réarchivez vos fichiers de configuration du proxy à partir de la racine du répertoire étendu.Après avoir importé votre nouvelle configuration de proxy, Edge incrémente le numéro de révision et l'affiche dans la vue Résumé de la révision.
Edge ne déploie pas la nouvelle révision pour vous après que vous l'avez importée avec l'interface utilisateur.
- Déployez votre nouvelle révision.
Pour en savoir plus, consultez le tutoriel sur le téléchargement d'un proxy à l'aide de l'interface utilisateur et de l'API de gestion dans la communauté Apigee.
Structure du proxy API
Un proxy d'API comprend la configuration suivante :
Configuration de base | Principaux paramètres de configuration d'un proxy d'API. Consultez la section Configuration de base. |
Configuration de ProxyEndpoint | Paramètres pour la connexion HTTP entrante (de la demande d'applications à Apigee Edge), les flux de requête et de réponse et les pièces jointes aux règles. Consultez la section ProxyEndpoint. |
Configuration de TargetEndpoint | Paramètres pour la connexion HTTP sortante (depuis Apigee Edge vers le service de backend), les flux de requêtes et de réponses et les rattachements de règles. Voir TargetEndpoint. |
Flux | Pipelines de requête et de réponse ProxyEndpoint et TargetEndpoint auxquels les règles peuvent être associées. Consultez la section Flux. |
Règles | Fichiers de configuration au format XML conformes aux schémas des règles Apigee Edge. Consultez la section Règles. |
Ressources | Scripts, fichiers JAR et fichiers XSLT référencés par des règles pour exécuter une logique personnalisée. Accédez aux ressources. |
Structure et contenu du répertoire du proxy API
Les composants du tableau ci-dessus sont définis par des fichiers de configuration dans la structure de répertoires suivante :
Fichiers de configuration et structure de répertoires d'un proxy d'API
Cette section décrit les fichiers de configuration et la structure des répertoires d'un proxy d'API.
Configuration de base
/apiproxy/weatherapi.xml
Configuration de base d'un proxy d'API, qui définit le nom du proxy API. Le nom doit être unique au sein d'une organisation.
Exemple de configuration :
<APIProxy name="weatherapi"> </APIProxy>
Éléments de configuration de base
Nom | Description | Par défaut | nécessaire |
---|---|---|---|
APIProxy |
|||
name |
Nom du proxy d'API, qui doit être unique au sein d'une organisation. Les caractères que vous êtes autorisé à utiliser dans le nom sont limités aux éléments suivants : A-Za-z0-9_- |
N/A | Oui |
revision |
Numéro de révision de la configuration de proxy de l'API. Vous n'avez pas besoin de définir explicitement le numéro de révision, car Apigee Edge suit automatiquement la révision actuelle du proxy d'API. | N/A | Non |
ConfigurationVersion |
Version du schéma de configuration du proxy d'API auquel ce proxy d'API est conforme. La seule valeur actuellement acceptée est majorVersion 4 et minorVersion 0. Ce paramètre pourra être utilisé ultérieurement pour autoriser l'évolution du format de proxy d'API. | 4.0 | Non |
Description |
Description textuelle du proxy d'API. Si elle est fournie, la description s'affichera dans l'interface utilisateur de gestion Edge. | N/A | Non |
DisplayName |
Un nom convivial qui peut être différent de l'attribut name de la configuration du proxy d'API. |
N/A | Non |
Policies |
Liste des règles dans le répertoire /policies de ce proxy d'API. Normalement, cet élément ne s'affiche que lorsque le proxy d'API a été créé à l'aide de l'interface utilisateur de gestion Edge.
Il s'agit simplement d'un paramètre "manifest" conçu pour offrir une visibilité sur le contenu du proxy d'API. |
N/A | Non |
ProxyEndpoints |
Liste des proxysEndpoints dans le répertoire /proxies de ce proxy d'API. Normalement, cet élément ne s'affiche que lorsque le proxy d'API a été créé à l'aide de l'interface utilisateur de gestion Edge. Il s'agit simplement d'un paramètre "manifest", conçu pour fournir une visibilité sur le contenu du proxy d'API. |
N/A | Non |
Resources |
La liste des ressources (JavaScript, Python, Java, XSLT) dans le répertoire /resources de ce proxy d'API. Normalement, cet élément ne s'affiche que lorsque le proxy d'API a été créé à l'aide de l'interface utilisateur de gestion Edge. Il s'agit simplement d'un paramètre "manifest", conçu pour fournir une visibilité sur le contenu du proxy d'API. |
N/A | Non |
Spec |
Identifie la spécification OpenAPI associée au proxy d'API. La valeur est définie sur une URL ou sur un chemin d'accès dans le magasin de spécifications. Remarque: Le magasin de spécifications n'est disponible que dans l'expérience New Edge. Pour en savoir plus sur le magasin de spécifications, consultez Gérer et partager des spécifications. |
N/A | Non |
TargetServers |
Liste des TargetServers référencés dans n'importe quel TargetEndpoints du proxy d'API. Normalement, cet élément ne s'affiche que lorsque le proxy d'API a été créé à l'aide de l'interface utilisateur de gestion Edge. Il s'agit simplement d'un paramètre "manifest" conçu pour offrir une visibilité sur le contenu du proxy d'API. | N/A | Non |
TargetEndpoints |
Liste des TargetEndpoints dans le répertoire /targets de ce proxy d'API. Normalement, cet élément ne s'affiche que lorsque le proxy d'API a été créé à l'aide de l'interface utilisateur de gestion Edge. Il s'agit simplement d'un paramètre "manifest", conçu pour fournir une visibilité sur le contenu du proxy d'API. |
N/A | Non |
ProxyEndpoint
L'image suivante montre le flux de requêtes/réponses :
/apiproxy/proxies/default.xml
La configuration ProxyEndpoint définit l'interface entrante (destinée au client) d'un proxy d'API. Lorsque vous configurez un ProxyEndpoint, vous paramétrez une configuration réseau qui définit la façon dont les applications clientes ("apps") doivent appeler l'API avec proxy.
L'exemple de configuration ProxyEndpoint suivant serait stocké sous /apiproxy/proxies
:
<ProxyEndpoint name="default"> <PreFlow/> <Flows/> <PostFlow/> <HTTPProxyConnection> <BasePath>/weather</BasePath> <VirtualHost>default</VirtualHost> </HTTPProxyConnection> <FaultRules/> <DefaultFaultRule/> <RouteRule name="default"> <TargetEndpoint>default</TargetEndpoint> </RouteRule> </ProxyEndpoint>
Les éléments de configuration requis dans un ProxyEndpoint sont les suivants :
Éléments de configuration ProxyEndpoint
Nom | Description | Par défaut | nécessaire |
---|---|---|---|
ProxyEndpoint |
|||
name |
Nom de ProxyEndpoint. Doit être unique dans la configuration du proxy d'API, lorsque, dans de rares cas, plusieurs points de terminaison Proxy sont définis. Les caractères que vous êtes autorisé à utiliser dans le nom sont limités aux éléments suivants : A-Za-z0-9._\-$ % |
N/A | Oui |
PreFlow |
Définit les règles dans le flux PreFlow d'une requête ou d'une réponse. | N/A | Oui |
Flows |
Définit les stratégies dans les flux conditionnels d'une requête ou d'une réponse.
|
N/A | Oui |
PostFlow |
Définit les stratégies dans le flux PostFlow d'une requête ou d'une réponse.
|
N/A | Oui |
HTTPProxyConnection |
Définit l'adresse réseau et le chemin d'URI associés au proxy d'API | ||
BasePath |
Chaîne obligatoire qui identifie de manière unique le chemin d'URI utilisé par Apigee Edge pour acheminer les messages entrants vers le proxy d'API approprié. BasePath est un fragment d'URI (par exemple, Utiliser un caractère générique dans les chemins de base Vous pouvez utiliser un ou plusieurs caractères génériques "*" dans les chemins d'accès de base du proxy d'API. Par exemple, un chemin de base de Important : Apigee n'accepte PAS le caractère générique "*" en tant que premier élément d'un chemin de base. Par exemple, ceci n'est PAS accepté : |
/ | Oui |
VirtualHost |
Associe un proxy d'API à des URL de base spécifiques à un environnement. Un objet VirtualHost est une configuration nommée qui définit une ou plusieurs URL pour un environnement. Les VirtualHosts nommés définis pour un ProxyEndpoint déterminent les domaines et les ports sur lesquels un proxy d'API est exposé et, par extension, l'URL que les applications utilisent pour appeler un proxy d'API. Par défaut, deux hôtes VirtualHost nommés sont définis pour un environnement : |
par défaut | Non |
Properties |
Un ensemble de paramètres de configuration HTTP facultatifs peut être défini en tant que propriétés d'un objet <ProxyEndpoint> . |
N/A | Non |
FaultRules |
Définit la manière dont le ProxyEndpoint réagit à une erreur. Une règle d'erreur spécifie les deux éléments suivants :
Consultez la page Gérer les erreurs. |
N/A | Non |
DefaultFaultRule |
Gère toutes les erreurs (système, transport, messagerie ou règle) qui ne sont pas explicitement gérées par une autre règle d'erreur. Consultez la page Gérer les erreurs. |
N/A | Non |
RouteRule |
Définit la destination des messages de requête entrants après avoir été traités par le pipeline de requêtes ProxyEndpoint. En général, la règle RouteRule pointe vers une configuration TargetEndpoint nommée, mais elle peut également pointer directement vers une URL. | ||
Name |
Attribut requis, qui fournit un nom pour la règle "RouteRule". Les caractères que vous êtes autorisé à utiliser dans le nom sont limités aux éléments suivants : A-Za-z0-9._\-$ % Par exemple, Cat2 %_ est un nom légal. |
N/A | Oui |
Condition |
Instruction conditionnelle facultative utilisée pour le routage dynamique lors de l'exécution. Les règles de routage conditionnelles sont utiles, par exemple, pour permettre un routage basé sur le contenu afin d'assurer la gestion des versions du backend. | N/A | Non |
TargetEndpoint |
Chaîne facultative qui identifie une configuration TargetEndpoint nommée. Un TargetEndpoint nommé est un objet TargetEndpoint défini dans le même proxy d'API sous le répertoire En nommant un TargetEndpoint, vous spécifiez où les messages de requête doivent être transférés après le traitement par le pipeline de requêtes ProxyEndpoint. Notez qu'il s'agit d'un paramètre facultatif. Un ProxyEndpoint peut appeler directement une URL. Par exemple, une ressource JavaScript ou Java, fonctionnant en tant que client HTTP, peut effectuer la responsabilité de base d'un TargetEndpoint, qui consiste à transférer les requêtes vers un service de backend. |
N/A | Non |
URL | Chaîne facultative qui définit une adresse réseau sortante appelée par l'objet ProxyEndpoint, en ignorant les configurations TargetEndpoint susceptibles d'être stockées sous /targets |
ND | Non |
Comment configurer des règles de routage
Un objet TargetEndpoint nommé fait référence à un fichier de configuration sous /apiproxy/targets
, dans lequel la règle RouteRule transfère une requête après le traitement par ProxyEndpoint.
Par exemple, la règle RouteRule suivante fait référence à la configuration /apiproxy/targets/myTarget.xml
:
<RouteRule name="default"> <TargetEndpoint>myTarget</TargetEndpoint> </RouteRule>
Appel direct d'URL
Un ProxyEndpoint peut également appeler directement un service de backend. L'appel direct d'URL contourne toute configuration TargetEndpoints nommée sous /apiproxy/targets
. Pour cette raison, TargetEndpoint est une configuration facultative de proxy d'API, bien qu'en pratique, l'appel direct à partir du ProxyEndpoint ne soit pas recommandé.
Par exemple, la règle RouteRule suivante envoie un appel HTTP à http://api.mycompany.com/v2
.
<RouteRule name="default"> <URL>http://api.mycompany.com/v2</URL> </RouteRule>
Routes conditionnelles
Les règles RouteRules peuvent être associées pour accepter le routage dynamique lors de l'exécution. Les requêtes entrantes peuvent être acheminées vers des configurations TargetEndpoint nommées, directement vers des URL ou une combinaison des deux, en fonction des en-têtes HTTP, du contenu du message, des paramètres de requête ou des informations contextuelles telles que l'heure, paramètres régionaux, etc.
Les règles de routage conditionnelles fonctionnent comme les autres instructions conditionnelles sur Apigee Edge. Consultez les sections Conditions de référence et Variables.
Par exemple, la combinaison RouteRule suivante permet d'évaluer d'abord la requête entrante pour vérifier la valeur d'un en-tête HTTP. Si l'en-tête HTTP routeTo
comporte la valeur TargetEndpoint1
, la requête est transmise au TargetEndpoint nommé TargetEndpoint1
. Si ce n'est pas le cas, la requête entrante est transmise à http://api.mycompany.com/v2
.
<RouteRule name="MyRoute"> <Condition>request.header.routeTo = "TargetEndpoint1"</Condition> <TargetEndpoint>TargetEndpoint1</TargetEndpoint> </RouteRule> <RouteRule name="default"> <URL>http://api.mycompany.com/v2</URL> </RouteRule>
Routes Null
Une valeur RouteRule nulle peut être définie pour accepter des scénarios dans lesquels le message de requête n'a pas besoin d'être transmis au TargetEndpoint. Cela s'avère utile lorsque ProxyEndpoint effectue tous les traitements nécessaires, par exemple en utilisant JavaScript pour appeler un service externe ou récupérer des données à partir d'une recherche dans le magasin de clés/valeurs des services d'API.
Par exemple, ce qui suit définit une route nulle :
<RouteRule name="GoNowhere"/>
Les routes conditionnelles nulles peuvent être utiles. Dans l'exemple suivant, une route nulle est configurée pour s'exécuter lorsqu'un en-tête HTTP request.header.X-DoNothing
possède une valeur autre que null
.
<RouteRule name="DoNothingOnDemand"> <Condition>request.header.X-DoNothing != null</Condition> </RouteRule>
Rappelez-vous : les routesRules peuvent être enchaînées. Par conséquent, une route conditionnelle nulle est généralement un composant d'un ensemble de règles de route conçues pour prendre en charge le routage conditionnel.
Une route conditionnelle nulle peut être utile pour la compatibilité de la mise en cache. En utilisant la valeur de la variable définie par la stratégie de mise en cache, vous pouvez configurer un proxy d'API pour qu'il exécute la route nulle lorsqu'une entrée est diffusée à partir du cache.
<RouteRule name="DoNothingUnlessTheCacheIsStale"> <Condition>lookupcache.LookupCache-1.cachehit is true</Condition> </RouteRule>
Point de terminaison cible
Un TargetEndpoint est l'équivalent sortant d'un ProxyEndpoint. Un TargetEndpoint fonctionne en tant que client vers une API ou un service de backend : il envoie des requêtes et reçoit des réponses.
Un proxy d'API n'a pas besoin de TargetEndpoints. ProxyEndpoints peut être configuré pour appeler directement les URL. Un proxy d'API sans TargetEndpoints contient généralement un ProxyEndpoint qui appelle directement un service de backend, ou est configuré pour appeler un service à l'aide de Java ou de JavaScript.
Configuration de TargetEndpoint
/targets/default.xml
Le point de terminaison cible définit la connexion sortante depuis Apigee Edge vers un autre service ou une autre ressource.
Voici un exemple de configuration TargetEndpoint :
<TargetEndpoint name="default"> <PreFlow/> <Flows/> <PostFlow/> <HTTPTargetConnection> <URL>http://mocktarget.apigee.net</URL> <SSLInfo/> </HTTPTargetConnection> <FaultRules/> <DefaultFaultRule/> <ScriptTarget/> <LocalTargetConnection/> </TargetEndpoint>
Éléments de configuration TargetEndpoint
Un TargetEndpoint peut appeler une cible de l'une des manières suivantes :
- HTTPTargetConnection pour les appels HTTP(S)
- LocalTargetConnection pour le chaînage local de proxy à proxy
- ScriptTarget pour les appels à un script Node.js hébergé en périphérie
Configurez un seul de ces éléments dans un TargetEndpoint.
Nom | Description | Par défaut | nécessaire |
---|---|---|---|
TargetEndpoint |
|||
name |
Nom de TargetEndpoint, qui doit être unique dans la configuration du proxy d'API. Le nom de TargetEndPoint est utilisé dans la règle de routage ProxyEndpoint pour diriger les requêtes en vue d'un traitement sortant. Les caractères que vous êtes autorisé à utiliser dans le nom sont limités aux éléments suivants : A-Za-z0-9._\-$ % |
N/A | Oui |
PreFlow |
Définit les règles dans le flux PreFlow d'une requête ou d'une réponse. | N/A | Oui |
Flows |
Définit les stratégies dans les flux conditionnels d'une requête ou d'une réponse.
|
N/A | Oui |
PostFlow |
Définit les stratégies dans le flux PostFlow d'une requête ou d'une réponse.
|
N/A | Oui |
HTTPTargetConnection |
Avec ses éléments enfants, spécifie une portée de ressources de backend via HTTP. Si vous utilisez HTTPTargetConnection, ne configurez pas d'autres types de connexions cibles (ScriptTarget ou LocalTargetConnection). |
||
URL |
Définit l'adresse réseau du service de backend vers lequel le TargetEndpoint transmet les messages de requête. | N/A | Non |
LoadBalancer |
Définit une ou plusieurs configurations TargetServer nommées. Les configurations TargetServer nommées peuvent servir à l'équilibrage de charge définissant deux ou plusieurs connexions de configuration de point de terminaison. Vous pouvez également utiliser TargetServers pour dissocier les configurations de proxy d'API des URL concrètes de points de terminaison du service de backend. Consultez la section Équilibrage de charge sur les serveurs backend. |
N/A | Non |
Properties |
Un ensemble de paramètres de configuration HTTP facultatifs peut être défini en tant que propriétés d'un objet <TargetEndpoint> . |
N/A | Non |
SSLInfo |
Vous pouvez éventuellement définir des paramètres TLS/SSL sur un TargetEndpoint pour contrôler la connexion TLS/SSL entre le proxy d'API et le service cible. Consultez la page Configuration TLS/SSL TargetEndpoint. | N/A | Non |
LocalTargetConnection |
Avec ses éléments enfants, spécifie une ressource à atteindre localement, en contournant les caractéristiques réseau telles que l'équilibrage de charge et les processeurs de messages.
Pour spécifier la ressource cible, incluez soit l'élément enfant APIProxy (avec l'élément ProxyEndpoint), soit l'élément enfant Path. Pour plus d'informations, consultez la section Chaîner des proxys d'API. Si vous utilisez LocalTargetConnection, ne configurez pas d'autres types de connexions cibles (HTTPTargetConnection ou ScriptTarget). |
||
APIProxy |
Spécifie le nom d'un proxy API à utiliser comme cible pour les requêtes. Le proxy cible doit appartenir à la même organisation et à l'environnement que le proxy qui envoie les requêtes. Ceci constitue une alternative à l'utilisation de l'élément Path. | N/A | Non |
ProxyEndpoint |
Utilisé avec APIProxy pour spécifier le nom de l'objet ProxyEndpoint du proxy cible. | N/A | Non |
Path |
Spécifie le chemin d'accès au point de terminaison d'un proxy d'API à utiliser comme cible pour les requêtes. Le proxy cible doit appartenir à la même organisation et à l'environnement que le proxy qui envoie les requêtes. Il s'agit d'une alternative à l'utilisation d'APIProxy. | N/A | Non |
FaultRules |
Définit la manière dont le TargetEndpoint réagit à une erreur. Une règle d'erreur spécifie les deux éléments suivants :
Consultez la page Gérer les erreurs. |
N/A | Non |
DefaultFaultRule |
Gère toutes les erreurs (système, transport, messagerie ou règle) qui ne sont pas explicitement gérées par une autre règle FaultRule. Consultez la page Gérer les erreurs. |
N/A | Non |
ScriptTarget |
|||
ResourceURL |
Définit le type de ressource (nœud) et le nom du script Node.js principal qui implémente la fonctionnalité TargetEndpoint.
Le script doit être inclus dans les fichiers de ressources du proxy API. Consultez la section Ajouter Node.js à un proxy d'API existant. Si vous utilisez ScriptTarget, ne configurez pas d'autres types de connexions cibles (HTTPTargetConnection ou LocalTargetConnection). |
N/A | Oui |
EnvironmentVariable |
Vous pouvez éventuellement transmettre des variables d'environnement au script Node.js principal. Consultez la section Comprendre la compatibilité avec les modules Node.js. |
N/A | Non |
Arguments |
Vous pouvez éventuellement transmettre des arguments au script Node.js principal. Consultez la section Comprendre la compatibilité avec les modules Node.js. |
N/A | Non |
Configuration de TLS/SLL TargetEndpoint
TargetEndpoints doit souvent gérer les connexions HTTPS avec une infrastructure de backend hétérogène. C'est la raison pour laquelle un certain nombre de paramètres de configuration TLS/SSL sont acceptés.
Éléments de configuration TargetEndpoint TLS/SSL
Nom | Description | Par défaut | nécessaire |
---|---|---|---|
SSLInfo |
|||
Enabled |
Indique si TLS/SSL est activé pour le point de terminaison.
La valeur par défaut est true si <URL> spécifie le protocole HTTPS et false si <URL> spécifie HTTP. |
La valeur est définie sur "true" si <URL> spécifie le protocole HTTPS. |
Non |
TrustStore |
Un keystore contenant des certificats de serveur approuvés | N/A | Non |
ClientAuthEnabled |
Paramètre qui active l'authentification du client sortant (protocoles TLS/SSL bidirectionnels) | faux | Non |
KeyStore |
Magasin de clés contenant des clés privées utilisées pour l'authentification du client sortant | N/A | Oui (si ClientAuthEnabled est défini sur "true") |
KeyAlias |
Alias de la clé privée utilisée pour l'authentification du client sortant | N/A | Oui (si ClientAuthEnabled est défini sur "true") |
Ciphers |
Algorithmes de chiffrement compatibles avec TLS/SSL sortant Si aucun algorithme n'est spécifié, tous les algorithmes de chiffrement disponibles pour la JVM sont autorisés. Pour limiter les algorithmes de chiffrement, ajoutez les éléments suivants, répertoriant les algorithmes de chiffrement compatibles : <Ciphers> <Cipher>TLS_RSA_WITH_3DES_EDE_CBC_SHA</Cipher> <Cipher>TLS_RSA_WITH_DES_CBC_SHA</Cipher> </Ciphers> |
N/A | Non |
Protocols |
Protocoles compatibles pour le protocole TLS/SSL sortant Si aucun protocole n'est spécifié, tous les protocoles disponibles pour la JVM seront autorisés. Pour restreindre les protocoles, ajoutez les éléments suivants qui répertorient les protocoles acceptés : <Protocols> <Protocol>TLSv1.1</Protocol> <Protocol>TLSv1.2</Protocol> </Protocols> |
N/A | Non |
Exemple de TargetEndpoint avec l'authentification du client sortant activée
<TargetEndpoint name="default"> <HttpTargetConnection> <URL>https://myservice.com</URL> <SSLInfo> <Enabled>true</Enabled> <ClientAuthEnabled>true</ClientAuthEnabled> <KeyStore>myKeystore</KeyStore> <KeyAlias>myKey</KeyAlias> <TrustStore>myTruststore</TrustStore> </SSLInfo> </HttpTargetConnection> </TargetEndpoint>
Pour obtenir des instructions détaillées, consultez la section Configurer le protocole TLS depuis le backend vers le backend (Cloud et cloud privé).
Utiliser des variables de flux pour définir des valeurs TLS/SSL de manière dynamique
Vous pouvez également définir de manière dynamique les détails TLS/SSL pour répondre aux exigences d'exécution flexible. Par exemple, si votre proxy se connecte à deux cibles potentiellement différentes (une cible de test et une cible de production), vous pouvez configurer votre proxy d'API de manière automatisée pour déterminer quel environnement est appelé et définir de manière dynamique des références au keystore et au truststore appropriés. L'article suivant de la communauté Apigee explique plus en détail ce scénario et fournit des exemples de proxy d'API déployables : https://community.apigee.com/articles/21424/dynamic-sslinfo-for-targetendpoint-using-variable.html.
Dans l'exemple suivant, la valeur de la balise <SSLInfo>
est définie dans une configuration TargetEndpoint, les valeurs peuvent être fournies lors de l'exécution, par exemple dans un appel Java, une stratégie JavaScript ou un message d'attribution. Utilisez les variables de message qui contiennent les valeurs que vous souhaitez définir.
Les variables ne sont autorisées que dans les éléments suivants.
<SSLInfo> <Enabled>{myvars.ssl.enabled}</Enabled> <ClientAuthEnabled>{myvars.ssl.client.auth.enabled}</ClientAuthEnabled> <KeyStore>{myvars.ssl.keystore}</KeyStore> <KeyAlias>{myvars.ssl.keyAlias}</KeyAlias> <TrustStore>{myvars.ssl.trustStore}</TrustStore> </SSLInfo>
Utiliser des références pour définir les valeurs TLS/SSL de manière dynamique
Lorsque vous configurez un TargetEndpoint utilisant HTTPS, vous devez prendre en compte le cas où le certificat TLS/SSL expire, ou lorsqu'une modification de la configuration du système nécessite la mise à jour du certificat. Dans une installation Edge pour le cloud privé, lorsque vous configurez TLS/SSL à l'aide de valeurs statiques ou de variables de flux, vous devrez peut-être redémarrer les processeurs de messages.
Pour en savoir plus, consultez la page Mettre à jour un certificat TLS.
Cependant, vous pouvez éventuellement configurer le TargetEndpoint pour utiliser une référence au keystore ou au truststore à la place. L'avantage d'utiliser une référence est que vous pouvez mettre à jour la référence pour qu'elle pointe vers un autre keystore ou truststore afin de mettre à jour le certificat TLS/SSL sans avoir à redémarrer les processeurs de message.
Par exemple, vous trouverez ci-dessous un TargetEndpoint qui utilise une référence au magasin de clés :
<SSLInfo> <Enabled>true</Enabled> <ClientAuthEnabled>false</ClientAuthEnabled> <KeyStore>ref://keystoreref</KeyStore> <KeyAlias>myKeyAlias</KeyAlias> </SSLInfo>
Utilisez l'appel d'API POST suivant pour créer la référence nommée keystoreref :
curl -X POST -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \ -d '<ResourceReference name="keystoreref"> <Refers>myTestKeystore</Refers> <ResourceType>KeyStore</ResourceType> </ResourceReference>' -u email:password
La référence spécifie le nom du magasin de clés et son type.
Utilisez l'appel d'API GET suivant pour afficher la référence :
curl -X GET https://api.enterprise.apigee.com/v1/o/[org_name}/e/{env_name}/references/keystoreref -u uname:password
Pour modifier ultérieurement la référence afin qu'elle pointe vers un magasin de clés différent, assurez-vous que l'alias porte le même nom, utilisez l'appel PUT suivant :
curl -X PUT -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references/keystoreref \ -d '<ResourceReference name="keystoreref"> <Refers>myNewKeystore</Refers> <ResourceType>KeyStore</ResourceType> </ResourceReference>' -u email:password
TargetEndpoint avec un équilibrage de charge cible
TargetEndpoints accepte l'équilibrage de charge sur plusieurs TargetServers nommés à l'aide de trois algorithmes d'équilibrage de charge de type.
Pour obtenir des instructions détaillées, reportez-vous à la section Équilibrage de charge sur les serveurs backend.
Stratégies
Le répertoire /policies
d'un proxy d'API contient toutes les stratégies pouvant être associées aux flux dans le proxy d'API.
Éléments de configuration de la stratégie
Nom | Description | Par défaut | nécessaire |
---|---|---|---|
Policy |
|||
name |
Nom interne de la règle. Les caractères que vous pouvez utiliser dans le nom se limitent à : Vous pouvez également utiliser l'élément |
N/A | Oui |
enabled |
Définissez sur Définissez la valeur sur |
true | Non |
continueOnError |
Définissez sur Définissez la valeur sur |
faux | Non |
async |
Remarque : Cet attribut n'applique pas la règle de manière asynchrone.
Dans la plupart des cas, conservez la valeur par défaut suivante : Si défini sur Pour utiliser un comportement asynchrone dans des proxys d'API, consultez la page Modèle d'objet JavaScript. |
faux | Non |
Rattachement de stratégie
L'image suivante montre la séquence d'exécution des flux de proxy d'API :
Comme indiqué ci-dessus :
Les règles sont associées en tant qu'étapes de traitement aux Flux. Le nom de la règle est utilisé pour référencer la stratégie à appliquer en tant qu'étape de traitement. Le format d'un rattachement de stratégies est le suivant :
<Step><Name>MyPolicy</Name></Step>
Les stratégies sont appliquées dans l'ordre dans lequel elles sont associées à un flux. Exemple :
<Step><Name>FirstPolicy</Name></Step> <Step><Name>SecondPolicy</Name></Step>
Éléments de configuration de rattachement de stratégie
Nom | Description | Par défaut | nécessaire |
---|---|---|---|
Step |
|||
Name |
Nom de la stratégie à exécuter par cette définition d'étape. | N/A | Oui |
Condition |
Instruction conditionnelle déterminant si la stratégie est appliquée ou non. Si une stratégie est associée à une condition, elle ne s'exécute que si l'instruction conditionnelle est définie sur "true". | N/A | Non |
Flux
ProxyEndpoint et TargetEndpoint définissent un pipeline pour le traitement des messages de requête et de réponse. Un pipeline de traitement se compose d'un flux de requête et d'un flux de réponse. Chaque flux de requêtes et chaque flux de réponses sont subdivisés en flux PreFlow, un ou plusieurs flux "conditionnels" ou "nommés" facultatifs, et un postFlow.
- PreFlow : s'exécute toujours. S'exécute avant les flux conditionnels, le cas échéant.
- PostFlow : s'exécute toujours. S'exécute après les flux conditionnels, le cas échéant.
En outre, vous pouvez ajouter un PostClientFlow au ProxyEndpoint, qui s'exécute une fois la réponse renvoyée à l'application cliente à l'origine de la requête. Seules la règle MessageLogging et l'extension Google Stackdriver Logging peuvent être associées à ce flux. PostClientFlow réduit la latence du proxy d'API et met les informations à disposition pour la journalisation ne faisant pas l'objet de calculs avant que la réponse ne soit renvoyée au client, comme client.sent.start.timestamp
et client.sent.end.timestamp
. Le flux est utilisé principalement pour mesurer l'intervalle de temps entre les horodatages de début et de fin du message de réponse.
Regarder une courte vidéo de démonstration
Vidéo : Regardez cette courte vidéo sur l'utilisation d'un journal de journalisation dans PostClientFlow.
Voici un exemple de flux PostClientFlow avec une stratégie de journalisation des messages.
... <PostFlow name="PostFlow"> <Request/> <Response/> </PostFlow> <PostClientFlow> <Request/> <Response> <Step> <Name>Message-Logging-1</Name> </Step> </Response> </PostClientFlow> ...
Le pipeline de traitement proxy de l'API exécute les flux dans l'ordre suivant :
Pipeline des requêtes :
- PreFlow de requête de proxy
- Flux conditionnels de requête de proxy (facultatif)
- Post-flux de requête de proxy
- PreFlow de requête cible
- Flux conditionnels de requête cible (facultatif)
- Post-flux de requête cible
Pipeline de réponse :
- PreFlow de réponse cible
- Flux conditionnels des réponses cibles (facultatif)
- Post-flux de réponse cible
- PreFlow de réponse proxy
- Flux conditionnels de réponse proxy (facultatif)
- Post-flux de réponse proxy
- Requête post-flux client (facultatif)
Seuls les flux avec des rattachements de stratégies doivent être configurés dans les configurations ProxyEndpoint ou TargetEndpoint. Les flux PreFlow et PostFlow ne doivent être spécifiés que dans une configuration ProxyEndpoint ou TargetEndpoint lorsqu'une stratégie doit être appliquée lors du traitement de PreFlow ou PostFlow.
Contrairement aux flux conditionnels, l'ordre des éléments PreFlow et PostFlow n'est pas important. Le proxy d'API exécute toujours chaque élément au moment approprié dans le pipeline, quel que soit leur emplacement dans la configuration du point de terminaison.
Flux conditionnels
Les ProxyEndpoints et TargetEndpoints sont compatibles avec un nombre illimité de flux conditionnels (également appelés "flux nommés").
Le proxy d'API teste la condition spécifiée dans le flux conditionnel et, si la condition est remplie, les étapes de traitement du flux conditionnel sont exécutées par le proxy d'API. Si la condition n'est pas remplie, les étapes de traitement du flux conditionnel sont ignorées. Les flux conditionnels sont évalués dans l'ordre défini dans le proxy de l'API et le premier dont la condition est remplie est exécutée.
En définissant des flux conditionnels, vous pouvez appliquer des étapes de traitement dans un proxy d'API en fonction des éléments suivants :
- URI de la requête
- Verbe HTTP (GET/PUT/POST/DELETE)
- Valeur d'un paramètre de requête, d'un en-tête et d'un paramètre de formulaire
- De nombreux autres types de conditions
Par exemple, le flux conditionnel suivant spécifie qu'il n'est exécuté que lorsque le chemin de la ressource de requête est /accesstoken
. Toute requête entrante avec le chemin /accesstoken
entraîne l'exécution de ce flux, ainsi que toutes les règles associées au flux. Si le chemin de la requête n'inclut pas le suffixe /accesstoken
, le flux ne s'exécute pas (même si un autre flux conditionnel peut être utilisé).
<Flows> <Flow name="TokenEndpoint"> <Condition>proxy.pathsuffix MatchesPath "/accesstoken"</Condition> <Request> <Step> <Name>GenerateAccessToken</Name> </Step> </Request> </Flow> </Flows>
Éléments de configuration de flux
Nom | Description | Par défaut | nécessaire |
---|---|---|---|
Flow |
Pipeline de traitement de requête ou de réponse défini par un ProxyEndpoint ou TargetEndpoint | ||
Name |
Nom unique du flux. | N/A | Oui |
Condition |
Instruction conditionnelle qui évalue une ou plusieurs variables à évaluer sur "vrai" ou "faux". Tous les flux autres que les types PreFlow et PostFlow prédéfinis doivent définir une condition pour leur exécution. | N/A | Oui |
Request |
Pipeline associé au processeur des messages de requête | N/A | Non |
Response |
Pipeline associé au processeur des messages de réponse | N/A | Non |
Traitement par étapes
L'ordre séquentiel des flux conditionnels est appliqué par Apigee Edge. Les flux conditionnels s'exécutent de haut en bas. Le premier flux conditionnel dont la condition est évaluée à true
est exécuté, et un seul flux conditionnel est exécuté.
Par exemple, dans la configuration de flux suivante, toute requête entrante qui n'inclut pas le suffixe de chemin /first
ou /second
entraîne l'exécution de la règle ThirdFlow
, en appliquant la règle nommée Return404
.
<Flows> <Flow name="FirstFlow"> <Condition>proxy.pathsuffix MatchesPath "/first"</Condition> <Request> <Step><Name>FirstPolicy</Name></Step> </Request> </Flow> <Flow name="SecondFlow"> <Condition>proxy.pathsuffix MatchesPath "/second"</Condition> <Request> <Step><Name>FirstPolicy</Name></Step> <Step><Name>SecondPolicy</Name></Step> </Request> </Flow> <Flow name="ThirdFlow"> <Request> <Step><Name>Return404</Name></Step> </Request> </Flow> </Flows>
Ressources
Les "ressources" (fichiers de ressources à utiliser dans les proxys d'API) sont des scripts, du code et des transformations XSL pouvant être associés aux flux à l'aide de règles. Ils apparaissent dans la section "Scripts" de l'éditeur de proxy d'API de l'UI de gestion.
Consultez la section Fichiers de ressources pour connaître les types de ressources compatibles.
Les ressources peuvent être stockées dans un proxy d'API, un environnement ou une organisation. Dans chaque cas, une ressource est référencée par son nom dans une stratégie. Les services d'API résolvent le nom en passant du proxy d'API à l'environnement, au niveau de l'organisation.
Une ressource stockée au niveau de l'organisation peut être référencée par des stratégies dans n'importe quel environnement. Une ressource stockée au niveau de l'environnement peut être référencée par des stratégies dans cet environnement. Une ressource stockée au niveau du proxy d'API ne peut être référencée que par des règles dans ce proxy d'API.