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

Vous consultez la documentation d'Apigee Edge.
Accédez à la documentation sur Apigee X. info

En tant que client Apigee Edge, vous pouvez choisir de migrer votre installation vers Apigee X afin de profiter de nouvelles fonctionnalités ou d'une disponibilité régionale différente.

Cette page décrit les antimodèles de votre configuration que vous devrez résoudre avant de migrer vers Apigee X, ainsi que d'autres modifications de comportement que vous devez connaître avant la migration.

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

Applications sans produits d'API
Résumé Nécessite-t-il 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 un accès implicite à tous les produits d'API. 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 la section Enregistrer des applications et gérer des clés API.

La méthode la plus simple consiste à attribuer à chaque application l'accès à tous les produits d'API. Il s'agit de l'équivalent de ce qui est possible dans Apigee Edge. Si vous souhaitez adopter une approche "moindre privilège", vous devrez déterminer la liste minimale de produits API auxquels chaque identifiant d'application doit avoir accès. Vous pouvez analyser cela à l'aide des rapports Apigee Edge Analytics, en fonction de l'ID client.

Cache sans date d'expiration
Résumé Nécessite-t-il 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
Prend en charge la création, la mise à jour et la suppression de descripteurs de ressources de cache. Ne permet pas de créer, de mettre à jour ni de supprimer des descripteurs de ressources de cache.
Non

Résolution: Cache sans date d'expiration

Définissez un délai d'expiration pour tous les caches.

Expressions de filtre JSONPath sur des chemins non définis
Résumé Nécessite-t-il 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 cet exemple de structure :

{
    "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-t-il des modifications côté client ? Solution

Les expressions JSONPath avec un indice non présent ont un comportement différent dans Apigee X par rapport à Apigee Edge. Apigee X renvoie une erreur PathNotFoundException lorsque le chemin d'accès n'est pas trouvé.

Différence entre Apigee Edge et Apigee X:

Lorsque vous parcourez cet exemple de structure :

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

Avec l'expression $.books[3],

Apigee Edge Apigee X
Sorties null Génère une erreur 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 indice de tableau ne renvoyant pas d'objet de tableau
Résumé Nécessite-t-il des modifications côté client ? Solution

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

Différence entre Apigee Edge et Apigee X:

Lorsque vous parcourez cet exemple de structure :

{
    "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 indice de tableau ne renvoyant pas d'objet de tableau

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

Restrictions de dénomination des keystores
Résumé Nécessite-t-il 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 de dénomination du keystore

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

Plusieurs chemins d'accès de base déployés pour un proxy d'API
Résumé Nécessite-t-il 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 dispose d'un chemin de base différent.

Différence entre Apigee Edge et Apigee X:

Apigee Edge Apigee X
Prend en charge le déploiement de plusieurs révisions d'un proxy d'API, où chaque révision peut avoir un chemin de base différent. Ne prend pas en charge le déploiement de plusieurs révisions d'un proxy d'API, même si le proxy dispose de 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 d'accès de base.

Messages HTTP non conformes
Résumé Nécessite-t-il 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, des noms d'en-tête non valides, des doublons dans certains en-têtes restreints, etc.

Vous ne pouvez pas migrer vers Apigee X si votre exécution d'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é détecté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 : (deux-points) manquant dans la paire nom de l'en-tête et 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 ne doit être utilisé que pour activer les connexions WebSocket, mais ce n'est pas le cas.
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 compatible.
ZERO_CONTENT_LENGTH_FOR_POST_OR_PUT La valeur du champ d'en-tête "Content-Length" a été définie sur zéro ("0") 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-t-il des modifications côté client ? Solution

Les limites d'expiration des jetons OAuth 2.0 dépassent la plage prescrite.

Différence entre Apigee Edge et Apigee X:

Apigee Edge Apigee X
Aucune contrainte n'est actuellement appliquée à la date d'expiration du jeton OAuth 2.0, mais une application est prévue. Consultez les consignes de la section OAuth de la page "Limites". Vous devez définir une date 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: le délai d'expiration du jeton OAuth 2.0 n'est pas valide

Utilisez la stratégie OAuthV2 et spécifiez la date d'expiration dans <ExpiresIn> et <RefreshTokenExpiresIn>.

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

La configuration d'Apigee Edge n'est pas conforme aux limites du 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 cible de chemin
Résumé Nécessite-t-il 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>.

Apigee Edge documente 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 de point de terminaison et de cible de chemin

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

Restrictions concernant le nom du serveur cible
Résumé Nécessite-t-il 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. Les noms de serveurs cibles Edge n'imposent pas ces restrictions.

Non

Résolution: Restrictions concernant le nom du serveur cible

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

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

Un ou plusieurs hôtes virtuels utilisent le certificat "essai sans frais" fourni par Apigee. L'hôte virtuel répond alors 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 le vhost "par défaut" pour prendre en charge un nom de domaine au format ORG-ENV.apigee.net. Un certificat générique, appelé "certificat d'essai sans frais", permet l'utilisation du protocole TLS sur ces domaines. Les anciens domaines Apigee de la forme 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-t-il des modifications côté client ? Solution

Le ou les points de terminaison cibles comportent un ou plusieurs 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 se résout 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

Remplacez le point de terminaison cible par un nom de domaine valide.