Antimodèles de migration d'Apigee Edge vers Apigee X

Vous consultez la documentation Apigee Edge.
Accédez à la documentation Apigee X.

Si vous êtes actuellement client Apigee Edge, vous pouvez choisir de migrer votre installation vers Apigee X pour profiter de nouvelles fonctionnalités ou d'une disponibilité régionale différente.

Cette page décrit les antipatterns de votre configuration que vous devrez corriger avant de migrer vers Apigee X, ainsi que d'autres changements de comportement dont vous devez être conscient avant la migration.

La liste plus large des antimodèles Apigee Edge décrit les pratiques d'utilisation à éviter dans tous les cas. Cette page décrit les pratiques d'utilisation spécifiques non recommandées qui bloqueront une migration. Résolvez-les maintenant pour éviter les problèmes lors de la migration vers Apigee X.

Applications sans produits d'API
Résumé Nécessite des modifications côté client ? Solution

Certaines applications ne comportent aucun produit d'API.

Différence entre Apigee Edge et Apigee X :

Apigee Edge Apigee X
Il est possible de configurer une application et des identifiants qui ne sont associés à aucun produit d'API. Cette application a effectivement accès à tous les produits d'API. Chaque application doit être configurée pour accéder à au moins un produit d'API. Il n'existe aucun moyen d'accorder l'accès à tous les produits d'API de manière implicite. Vous pouvez configurer une application pour qu'elle ait accès à tous les produits d'API, mais vous devez le faire explicitement.
Non.

Résolution : applications sans produits d'API

Associez chaque identifiant d'application à au moins un produit d'API. Pour en savoir plus, consultez Enregistrer des applications et gérer des clés API.

Le plus simple est d'attribuer à chaque application l'accès à tous les produits d'API. Cela correspondra à ce qui est possible dans Apigee Edge. Le défi consiste à déterminer la liste minimale de produits d'API auxquels chaque identifiant d'application doit avoir accès si vous souhaitez adopter une approche de "moindre privilège". Vous pouvez analyser cela avec les rapports Apigee Edge Analytics, en fonction de l'ID client.

Cache sans délai d'expiration
Résumé Nécessite des modifications côté client ? Solution

Les caches n'ont pas de délai d'expiration.

Différence entre Apigee Edge et Apigee X :

Apigee Edge Apigee X
Permet de créer, de mettre à jour et de supprimer des descripteurs de ressources de cache. Ne permet pas de créer, de mettre à jour ni de supprimer les descripteurs de ressources de cache.
Non

Résolution : Cache sans délai d'expiration

Définissez une heure d'expiration pour tous les caches.

Expressions de filtre JSONPath sur des chemins non définis
Résumé Nécessite des modifications côté client ? Solution

Pour les chemins non définitifs, l'interrogation du résultat d'une expression de filtre ne fait pas partie de la spécification JSONPath. Consultez https://goessner.net/articles/JsonPath/.

Différence entre Apigee Edge et Apigee X :

Lorsque vous parcourez cette structure d'exemple,

{
    "books": [
      {
        "name": "A",
      },
      {
        "name": "B",
      }
    ]
}

Avec l'expression $..books[?(@.name == 'A')][0],

Apigee Edge Apigee X
Sorties ‘{"name": "A"}’ Sorties []

Avec l'expression $..books[?(@.name == 'A')][0].name,

Apigee Edge Apigee X
Sorties "A" Sorties []
Oui

Résolution : expressions de filtre JSONPath sur des chemins non définis

Recherchez et remplacez les requêtes concernées.

Expressions JSONPath pour les index qui ne sont pas présents
Résumé Nécessite des modifications côté client ? Solution

Les expressions JSONPath avec un index absent ont des comportements différents dans Apigee X et Apigee Edge. Apigee X renvoie une erreur PathNotFoundException lorsque le chemin est introuvable.

Différence entre Apigee Edge et Apigee X :

Lorsque vous parcourez cette structure d'exemple,

{
    "books": [
      {
        "name": "A",
      },
      {
        "name": "B",
      }
    ]
}

Avec l'expression $.books[3],

Apigee Edge Apigee X
Sorties null Erreur de sortie PathNotFoundException
Oui

Résolution : expressions JSONPath pour les index qui ne sont pas présents

Recherchez et remplacez les requêtes concernées.

Expressions JSONPath avec un index de tableau ne renvoyant pas d'objet tableau
Résumé Nécessite des modifications côté client ? Solution

Les expressions JSONPath avec un index ou des tranches de tableau renvoient un objet de tableau dans Apigee X.

Différence entre Apigee Edge et Apigee X :

Lorsque vous parcourez cette structure d'exemple,

{
    "books": [
      {
        "name": "A",
      },
      {
        "name": "B",
      }
    ]
}

Avec l'expression $.books,

Apigee Edge Apigee X
Sorties {“name”:”A”, “name”: “B”} Sorties [{“name”:”A”, “name”: “B”}]

Avec l'expression $.books[-1],

Apigee Edge Apigee X
Sorties {“name”: “B”} Sorties [{“name”: “B”}]

Avec l'expression $.books[-2:],

Apigee Edge Apigee X
Sorties {“name”:”A”, “name”: “B”} Sorties [{“name”:”A”, “name”: “B”}]
Oui

Résolution : les expressions JSONPath avec un index de tableau ne renvoient pas d'objet tableau

Recherchez et remplacez les expressions qui pourraient renvoyer des résultats différents après la mise à niveau.

Restrictions concernant le nom du keystore
Résumé Nécessite des modifications côté client ? Solution

Les noms de keystore Apigee X ne peuvent contenir que des lettres, des chiffres et des traits d'union. Les noms de keystore Edge n'imposent pas ces restrictions.

Non

Résolution : restrictions concernant le nom du keystore

Vérifiez les noms des keystores et modifiez-les si nécessaire pour supprimer les caractères non pris en charge.

Plusieurs chemins de base déployés pour un proxy d'API
Résumé Nécessite des modifications côté client ? Solution

Plusieurs révisions d'un proxy d'API sont déployées dans un environnement et chacune d'elles possède un chemin de base différent.

Différence entre Apigee Edge et Apigee X :

Apigee Edge Apigee X
Permet de déployer plusieurs révisions d'un proxy d'API, où chaque révision peut avoir un chemin de base différent. Ne permet pas de déployer plusieurs révisions d'un proxy d'API, même si le proxy a des chemins de base différents.
Non

Résolution : plusieurs chemins de base déployés pour un proxy d'API

Mettez à jour tous les bundles afin qu'une seule révision d'un bundle soit déployée dans un environnement, quel que soit le chemin de base.

Messages HTTP non conformes
Résumé Nécessite des modifications côté client ? Solution

Les clients ou le proxy d'API envoient des messages (requêtes ou réponses) qui ne respectent pas la norme HTTP. Par exemple, les noms d'en-tête non valides, les doublons dans certains en-têtes restreints, etc.

Vous ne pouvez pas migrer vers Apigee X si l'exécution de votre API présente une ou plusieurs des erreurs suivantes :

Erreur Détails
INVALID_CHARACTERS_IN_HEADER Un ou plusieurs caractères non autorisés ont été trouvés dans l'en-tête spécifié. Les noms d'en-tête valides se composent de lettres de l'alphabet latin, de chiffres et de tirets.
MISSING_COLON Il manque un : (deux-points) dans la paire nom/valeur de l'en-tête.
MULTIPLE_CONTENT_LENGTH Plusieurs valeurs ont été fournies pour l'en-tête Content-Length.
CONTENT_LENGTH_NOT_INTEGER La valeur de l'en-tête Content-Length n'est pas un entier.
INVALID_UPGRADE L'en-tête "Upgrade" doit être utilisé uniquement pour activer les connexions WebSocket, mais il ne l'est pas.
URL_HEADER_SIZE_TOO_LONG La taille totale de l'URL et des en-têtes de la requête dépasse la taille maximale autorisée de 15 Ko.
BODY_NOT_ALLOWED Un corps de message n'est pas autorisé avec les méthodes "GET", "DELETE", "TRACE", "OPTIONS" et "HEAD".
UNSUPPORTED_HTTP_VERSION Une version HTTP autre que 1.1 est utilisée pour la requête et n'est pas acceptée.
ZERO_CONTENT_LENGTH_FOR_POST_OR_PUT Une valeur de champ d'en-tête Content-Length nulle ("0") a été définie pour une méthode "POST" ou "PUT".
UNSUPPORTED_RESPONSE_PREFIX Un préfixe d'en-tête "X-Apigee-" non compatible était présent dans l'en-tête de réponse.
Oui, c'est possible.

Résolution : messages HTTP non conformes

Vous devez corriger toutes les erreurs dans les protocoles HTTP avant de migrer vers Apigee X. Si une erreur provient d'une application cliente, vous devez demander au développeur de l'application cliente de corriger le problème.

Délai d'expiration du jeton OAuth 2.0 non valide
Résumé Nécessite des modifications côté client ? Solution

Les limites d'expiration des jetons OAuth 2.0 sont en dehors de la plage prescrite.

Différence entre Apigee Edge et Apigee X :

Apigee Edge Apigee X
Aucune contrainte n'est actuellement appliquée à la durée d'expiration du jeton OAuth 2.0, mais cela est prévu. Consultez les consignes de la section OAuth de la page "Limites". Vous devez définir une durée d'expiration pour le jeton d'accès et le jeton d'actualisation OAuth 2.0. Les plages acceptées sont les suivantes :
  • 180 secondes <= durée d'expiration du jeton d'accès OAuth 2.0 <= 30 jours
  • 1 jour ≤ délai d'expiration du jeton d'actualisation OAuth 2.0 ≤ 2 ans
Non

Résolution : délai d'expiration du jeton OAuth 2.0 non valide

Utilisez la règle OAuthV2 et spécifiez le délai d'expiration dans <ExpiresIn> et <RefreshTokenExpiresIn>.

Limites de produits dépassées
Résumé Nécessite des modifications côté client ? Solution

La configuration d'Apigee Edge n'est pas conforme aux limites de produit définies. Certaines limites de produit documentées, mais non appliquées sur Apigee Edge, le sont sur Apigee X.

Non

Résolution : Limites de produits dépassées

Corrigez toute utilisation qui dépasse les limites du produit avant de migrer vers Apigee X.

Règles ServiceCallout avec des spécificateurs de connexion de point de terminaison et de chemin d'accès cibles
Résumé Nécessite des modifications côté client ? Solution

Dans la règle ServiceCallout, l'élément <LocalTargetConnection> doit inclure les éléments <APIProxy> et <ProxyEndpoint> ou l'élément <Path>, mais pas les deux. Pour en savoir plus, consultez l'élément <LocalTargetConnection>.

La documentation Apigee Edge mentionne cette exigence, mais ne l'applique pas. Apigee X arrête le traitement s'il rencontre un <LocalTargetConnection> avec les deux configurations.

Non

Résolution : règles ServiceCallout avec des spécificateurs de connexion cible de point de terminaison et de chemin d'accès

Vérifiez les configurations des règles ServiceCallout et éliminez toutes les configurations <LocalTargetConnection> non conformes.

Restrictions concernant le nom du serveur cible
Résumé Nécessite des modifications côté client ? Solution

Les noms de serveurs cibles Apigee X ne peuvent contenir que des lettres, des chiffres, des traits d'union et des points. Ces restrictions ne s'appliquent pas aux noms de serveurs cibles Edge.

Non

Résolution : restrictions concernant le nom du serveur cible

Vérifiez les noms des serveurs cibles et modifiez-les si nécessaire pour supprimer les caractères non acceptés.

Certificat d'essai dans un hôte virtuel
Résumé Nécessite des modifications côté client ? Solution

Un ou plusieurs hôtes virtuels utilisent le certificat "essai sans frais" fourni par Apigee. Cela permet à l'hôte virtuel de répondre aux requêtes sur des domaines tels que ORG-ENV.apigee.net.

Différence entre Apigee Edge et Apigee X :

Apigee Edge Apigee X
Configure automatiquement l'hôte virtuel "par défaut" pour qu'il accepte un nom de domaine au format ORG-ENV.apigee.net. Il existe un certificat générique, appelé "certificat d'essai sans frais", qui autorise le protocole TLS sur ces domaines. Les anciens domaines Apigee au format ORG-ENV.apigee.net ne sont pas disponibles dans Apigee X. Vous devez configurer votre propre nom de domaine et provisionner les certificats de manière appropriée.
Oui

Résolution : certificat d'essai dans un hôte virtuel

Vous devez configurer votre propre domaine et provisionner les certificats de manière appropriée.

Toute application cliente qui dépend de l'ancien nom de domaine du formulaire ORG-ENV.apigee.net doit être modifiée pour appeler le nouveau domaine.

DNS non résolu
Résumé Nécessite des modifications côté client ? Solution

Le ou les points de terminaison cibles comportent des noms de domaine non résolus.

Différence entre Apigee Edge et Apigee X :

Apigee Edge Apigee X
Si la résolution DNS échoue, Apigee ajoute .apigee.com au nom de domaine, et le DNS est résolu avec succès avec un code de réponse 4xx. Si la résolution DNS échoue, Apigee n'exécute pas la requête et renvoie un code de réponse 5xx.
Non

Résolution : DNS non résolu

Mettez à jour le point de terminaison cible avec un nom de domaine valide.