Comprendre la compatibilité d'Edge avec les modules Node.js

Vous consultez la documentation d'Apigee Edge.
Consultez la documentation Apigee X.
en savoir plus

Quelle version de Node.js est compatible avec Apigee Edge ?

Edge est actuellement compatible avec Node.js 0.10.32.

Quels modules Node.js standards sont compatibles avec Edge ?

Utilisez le tableau suivant pour déterminer les modules Node.js standards inclus dans Edge. Dans certains cas, les modules inclus ne sont que partiellement compatibles. Il s'agit de modules intégrés à Node.js.

Module État Remarques
assert Compatible
buffer Compatible
child_process Limité Une exception sera générée si vous tentez de générer un sous-processus. Cependant, "fork" est pris en charge pour générer des indices.
cluster Désactivé La méthode cluster.isMaster renvoie toujours la valeur "true", et les autres méthodes ne sont pas implémentées. Une copie de chaque script Node.js est déployée sur chaque processeur de messages Edge.
crypto Compatible
dns Compatible
domain Compatible
dgram Limité Les applications Node.js de l'environnement Apigee ne pourront pas accéder aux services sur Internet via UDP en raison de notre architecture réseau.
events Compatible
fs Limité L'accès au système de fichiers est limité au répertoire dans lequel le script a été lancé: le répertoire /resources/node. Les scripts Node.js peuvent lire et écrire des fichiers dans ce répertoire, par exemple en tant que zone de travail temporaire, mais il n'y a aucune garantie quant à la durée de conservation des fichiers.
http Compatible L'hôte virtuel et le chemin d'accès des requêtes entrantes sont spécifiés dans le proxy d'API, et non par le module HTTP. Pour en savoir plus, consultez la section Comprendre la prise en charge des modules HTTP et HTTPS.
https Compatible La création d'un serveur "https" se comporte de la même manière qu'un serveur "http". Pour en savoir plus, consultez la section Comprendre la prise en charge des modules HTTP et HTTPS.
module Compatible
net Limité Les tentatives d'écoute des connexions TCP entrantes généreront une exception.
path Compatible
module Compatible
process Compatibilité partielle La fonctionnalité permettant de manipuler l'ID utilisateur, l'appartenance à un groupe et le répertoire de travail n'est pas acceptée.
punycode Compatible
querystring Compatible
readline Désactivé Il n'existe pas d'entrée standard pour les scripts exécutés sur Apigee Edge.
repl Désactivé Il n'existe pas d'entrée standard pour les scripts exécutés sur Apigee Edge.
module Incluse
STDIO Compatible

Les résultats et les erreurs standards sont acheminés vers un fichier journal au sein de l'infrastructure Apigee Edge. Vous pouvez afficher ces journaux en cliquant sur le bouton Journaux Node.js et l'interface utilisateur de gestion Apigee Edge pour votre proxy d'API.

Il n'existe pas d'entrée standard pour les scripts exécutés sur Apigee Edge. Toutefois, vous pouvez transmettre des arguments à l'aide de l'élément ScriptTarget de TargetEndpoint. Pour en savoir plus, consultez la section Configuration avancée de ScriptTarget.

stream Compatible
string_decoder Compatible
timers Incluse
tls Compatible Les paramètres TLS (Transport Layer Security) fonctionnent essentiellement de la même manière que dans le langage Node.js standard. Pour plus d'informations, consultez la section Utiliser le module Node.js TLS (SSL) sur Apigee Edge.
tty Désactivé Il n'existe pas d'entrée standard pour les scripts exécutés sur Apigee Edge.
url Compatible
util Compatible
vm Compatible
zlib Compatible

Modules compatibles supplémentaires

Cette section répertorie des modules supplémentaires qui ne sont pas compatibles avec le langage Node.js standard, mais qui sont compatibles avec Trireme et Trireme exécutés sur Apigee Edge. Trireme est le conteneur Node.js Open Source qui s'exécute sur Apigee Edge. Il est conçu pour exécuter des scripts Node.js dans une machine virtuelle Java (JVM). Tous ces modules sont disponibles dans GPR.

Module Description
apigee-access Permet aux applications Node.js exécutées sur la plate-forme Apigee Edge d'accéder à des fonctionnalités spécifiques à Apigee. Vous pouvez utiliser ce module pour accéder aux variables de flux et les modifier, récupérer des données à partir du magasin sécurisé et utiliser la mise en cache périphérique, les quotas et les services OAuth. Consultez également la section Utiliser le module "apigee-access".
trireme-support Permet aux applications Node.js de bénéficier des fonctionnalités propres à Trireme. Actuellement, une seule fonctionnalité est compatible : le chargement de modules Node.js créés en Java. Remarque : loadJars n'est pas compatible avec Edge Cloud.
trireme-xlsx. Présente une abstraction du traitement XLST. Il est spécialement conçu pour la plate-forme Trireme afin de permettre un traitement efficace de la feuille de style XSLT lorsque les applications Node.js sont exécutées sur Java.
trireme-jdbc Fournit l'accès à JDBC à partir de Node.js. Remarque: Non compatible avec Edge Cloud. Pour le cloud privé Edge, vous pouvez placer des fichiers JAR JDPC dans le chemin d'accès aux classes et utiliser ce module.

Compatibilité avec les modules Node.js couramment utilisés

Restrictions concernant les scripts Node.js

Notez cependant qu'Edge impose certaines restrictions aux scripts Node.js, telles que les suivantes:

  • Les applications Node.js dans l'environnement Apigee Edge ne peuvent pas accéder aux services sur Internet via UDP en raison de l'architecture réseau périphérique.
  • L'accès au système de fichiers est limité au répertoire dans lequel le script Node.js a été lancé: le répertoire /resources/node. Les scripts Node.js peuvent lire et écrire des fichiers dans ce répertoire (en tant que zone de travail temporaire, par exemple), mais il n'y a aucune garantie quant à la durée de conservation des fichiers.
  • Les tentatives d'écoute des connexions TCP entrantes génèrent une exception.
  • La fonctionnalité permettant de manipuler l'ID utilisateur, l'appartenance à un groupe et le répertoire de travail n'est pas acceptée.
  • Pour les entrées standards, vous êtes limité à la transmission d'arguments à l'aide de l'élément ScriptTarget de TargetEndpoint. Pour en savoir plus, consultez la section Configuration avancée de ScriptTarget.
  • Pour la sortie standard, vous êtes limité à l'utilisation du bouton "Journaux" de Node.js dans l'interface utilisateur de gestion Edge pour votre proxy. Vous pouvez également utiliser la commande « apigeetool getlogs ». Pour en savoir plus, consultez la section Déployer une application Node.js autonome.
  • Les modules qui dépendent du code natif ne sont pas compatibles.
  • Les modules qui dépendent des fonctionnalités d'EcmaScript 6, tels que les promesses et les générateurs, ne sont pas compatibles.
  • Les indicateurs d'exécution Node.js, tels que "harmony-proxies", ne sont pas compatibles.

Définition des restrictions de connexion IP sur Edge for Private Cloud

Edge for Private Cloud peut empêcher le code Node.js d'accéder aux adresses IP commençant par "10", "192.168" et localhost. Si vous tentez d'accéder à ces adresses IP, une erreur s'affiche dans le formulaire:

{ [Error: connect EINVAL] message: 'connect EINVAL', code: 'EINVAL', errno: 'EINVAL', syscall: 'connect' }

Vous pouvez modifier ces restrictions en définissant la propriété conf_nodejs_connect.ranges.denied dans le fichier conf_nodejs_connect.ranges.denied pour chaque processeur de messages. Par défaut, cette propriété a la valeur suivante:

  • Edge 4.17.05 et versions antérieures: conf_nodejs_connect.ranges.denied=10.0.0.0/8,192.168.0.0/16,127.0.0.1/32
  • Edge 4.17.09 et versions ultérieures: conf_nodejs_connect.ranges.denied= (ce qui signifie qu'il n'y a aucune restriction)

Pour définir cette propriété:

  1. Ouvrez le fichier message-processor.properties dans un éditeur. Si le fichier n'existe pas, créez-le:
    > vi /<inst_root>/apigee/customer/application/message-processor.properties
  2. Définissez la propriété comme vous le souhaitez. Par exemple, pour refuser uniquement l'accès à l'hôte local (localhost) :
    conf_nodejs_connect.ranges.denied=127.0.0.1/32
  3. Enregistrez les modifications.
  4. Assurez-vous que le fichier de propriétés appartient à l'utilisateur "apigee" :
    > chown apigee:apigee /<inst_root>/apigee/customer/application/message-processor.properties
  5. Redémarrez le processeur de messages:
    > /<inst_root>/apigee/apigee-service/bin/apigee-serviceedge-message-processor restart

Compatibilité avec les modules HTTP et HTTPS

Toutes les applications Node.js exécutées dans Apigee Edge doivent utiliser le module http ou https pour écouter les requêtes entrantes. Si vous déployez un script qui n'écoute pas les requêtes entrantes, il s'exécute simplement et se ferme.

La méthode listen des modules http et https dans Node.js utilise un numéro de port comme paramètre. Exemple :

svr.listen(process.env.PORT || 9000, function() {
   console.log('The server is running.');
});

Cet argument "port" est requis dans Node.js, mais Apigee Edge ignore ce paramètre. Au lieu de cela, le proxy d'API dans lequel le script Node.js s'exécute spécifie "l'hôte virtuel" qu'il écoute, et l'application Node.js utilise ces mêmes hôtes virtuels, comme n'importe quel autre proxy Apigee Edge.

Chaque environnement Apigee comporte au moins un hôte virtuel. L'hôte virtuel définit les paramètres HTTP de la connexion à l'organisation Apigee. Tous les proxys d'API d'un environnement partagent les mêmes hôtes virtuels. Par défaut, deux hôtes virtuels sont disponibles pour chaque environnement : default et secure. Pour en savoir plus, consultez Obtenir un hôte virtuel et Cycle de vie du développement de l'API.

La commande apigeetool deploynodeapp génère un wrapper de proxy Apigee Edge autour de l'application Node.js. Lorsqu'elle est déployée, l'application Node.js écoute sur l'hôte virtuel par défaut défini pour l'environnement. L'URL d'une application Node.js sera toujours http://{org_name}-{env_name}.apigee.net.

Gérer les requêtes entrantes

Comme d'autres applications Apigee Edge, si l'application proxy est configurée pour écouter l'hôte virtuel secure, elle acceptera les requêtes entrantes via HTTPS.

Gérer les requêtes sortantes

En plus de recevoir le trafic entrant, les applications Node.js dans Apigee Edge peuvent utiliser les modules http et https pour effectuer des requêtes sortantes, comme n'importe quelle autre application Node.js. Ces modules fonctionnent comme toujours dans Node.js.

Comprendre la compatibilité avec le module tls

Apigee Edge est compatible avec le module tls Node.js. Ce module utilise OpenSSL pour fournir des communications de flux chiffrées via TLS (Transport Layer Security) et/ou SSL (Secure Socket Layer). Vous pouvez utiliser le module tls pour créer des connexions sécurisées aux services de backend à partir d'applications Node.js exécutées sur Edge.

Pour comprendre le fonctionnement du module tls sur Apigee Edge, il est important de comprendre comment les virtual hosts sont utilisés sur Apigee Edge. Chaque environnement Apigee comporte au moins un hôte virtuel. L'hôte virtuel définit les paramètres HTTP de la connexion à l'organisation Apigee. Tous les proxys d'API d'un environnement partagent les mêmes hôtes virtuels. Par défaut, deux hôtes virtuels sont disponibles pour chaque environnement: default et secure. Pour en savoir plus sur les hôtes virtuels, consultez Obtenir un hôte virtuel et Cycle de vie du développement des API.

Voyons maintenant comment Apigee Edge gère la communication TLS (SSL) pour les requêtes entrantes et sortantes sur les applications Node.js:

Gérer les requêtes entrantes

Selon la configuration des hôtes virtuels pour votre organisation, Edge propose les options suivantes:

  • Si le proxy d'API est configuré pour écouter l'hôte virtuel default, il accepte les requêtes via HTTP.
  • Si le proxy d'API est configuré pour écouter sur l'hôte virtuel secure, il accepte les requêtes via HTTPS. L'URL se trouvera sous le domaine apigee.net. Un certificat SSL générique pour *.apigee.net sera utilisé. Tant que les applications envoient des requêtes au domaine apigee.net, le certificat SSL est validé normalement.

Gérer les requêtes sortantes

Vous pouvez effectuer des requêtes sortantes avec le module tls comme vous le feriez normalement dans Node.js. Vous devez essentiellement ajouter des clés et des certificats côté client (fichiers .pem) au répertoire resources/node et les charger dans votre script. Pour en savoir plus sur l'utilisation du module tls et de ses méthodes, consultez la documentation du module tls Node.js.

Configuration avancée de ScriptTarget

Dans la définition <TargetEndpoint>, l'élément <ScriptTarget> accepte des paramètres facultatifs supplémentaires en plus de <ResourceURL>. Vous pouvez également transmettre des arguments de ligne de commande et des variables d'environnement à un script Node.js à l'aide des paramètres <EnvironmentVariables> et <Arguments> :
<TargetEndpoint name="default">
  <ScriptTarget>
     <ResourceURL>node://hello.js</ResourceURL>
     <EnvironmentVariables>
         <EnvironmentVariable name="NAME">VALUE</EnvironmentVariable> 
     </EnvironmentVariables>
     <Arguments>
         <Argument>ARG</Argument>
     </Arguments>
  </ScriptTarget>
</TargetEndpoint>