Découvrez Edge et XM Cloud / Blogs / Perficient

Ayant travaillé sur des projets Sitecore sans tête pendant environ un an et demi impliquant Experience Edge et/ou XM Cloud, j’ai rencontré des choses… intéressantes. Dans cet article, j’espère partager quelques « leçons du front » dans l’espoir que d’autres équipes pourront éviter les mêmes erreurs et potentiellement s’épargner du temps et des maux de tête.

Je n’entrerai pas dans les détails sur Experience Edge ou XM Cloud en tant que produits dans cet article. Il existe, bien sûr, de la documentation de Sitecore ainsi qu’une tonne d’excellent contenu provenant des nombreux experts utiles de la communauté Sitecore sur ces deux produits SaaS de Sitecore. Pour plus d’informations sur Experience Edge et/ou XM Cloud, je vous recommande de commencer par la documentation officielle ici :

J’encourage également le lecteur à consulter les autres articles de blog de mes collègues ici sur le blog Perficient. Par exemple, celui de David San Filippo Le gros problème avec le sans tête poste et celui de Martin Miles Maîtriser XM Cloud série.

Découvrez le boîtier d’URL d’image Edge

Une tâche typique pour un développeur Sitecore est de s’assurer que les URL sont dans une casse cohérente et, généralement, cela signifie que les URL sont uniformément en minuscules, quel que soit le chemin de l’élément dans Sitecore. Ceci est fait pour plusieurs raisons, notamment le référencement et l’esthétique. Il existe plusieurs configurations pour Sitecore qui peuvent affecter la génération d’URL en ce qui concerne la casse.

Sur un projet récent, une pull request a été complétée qui a ajouté une configuration de correctif pour définir le lowercaseUrls attribuer à true sur le Sitecore.XA.Foundation.Multisite.LinkManagers.LocalizableLinkProvider élément (oui, nous utilisions SXA). Cela ressemblait à ceci :

<linkManager defaultProvider="switchableLinkProvider" patch:source="Sitecore.XA.Foundation.Multisite.config">
  <providers>
    <add name="localizedProvider" type="Sitecore.XA.Foundation.Multisite.LinkManagers.LocalizableLinkProvider, Sitecore.XA.Foundation.Multisite" 
          cacheExpiration="5" 
          addAspxExtension="false" 
          alwaysIncludeServerUrl="false" 
          encodeNames="true" 
          languageEmbedding="never" 
          languageLocation="filePath" 
          shortenUrls="true" 
          useDisplayName="false" 
          lowercaseUrls="true" /> <!-- HERE, THIS THING -->
  </providers>
</linkManager>

Bien que cela ait fonctionné dans la mesure où les URL du gestionnaire de liens étaient en minuscules comme prévu, le changement a eu pour effet secondaire involontaire de forcer les URL des éléments multimédias à être en minuscules avant leur publication sur Experience Edge. En d’autres termes, ce paramètre de configuration entraînait la publication des URL d’éléments multimédias en minuscules sur Experience Edge. Cependant, seules les URL « natives » (sans minuscules) seraient correctement résolues lors de la navigation sur Experience Edge : les URL des éléments multimédias dans Experience Edge sont sensibles à la casse en ce qui concerne le chemin de l’élément.

Par exemple, si une page de contenu comprenait, par exemple, un logo nommé logo.png qui résidait dans le Foo dossier (remarque : majuscule « F » à la racine de la médiathèque, alors la mise en page JSON renvoyée via la requête GraphQL de l’application sans tête serait :

...
"Logo": {
    "value": {
        "src": "https://edge.sitecorecloud.io/<environment-token>/media/foo/logo.png?h=123&iar=0&w=400",
        "alt": "Logo",
        "width": "400",
        "height": "123"
    }
}
...

Lors d’une navigation directe, la nouvelle URL en minuscules ne serait pas résolue. Ce n’est que lorsque la casse du dossier dans l’URL a été mise à jour pour correspondre au chemin de l’élément multimédia dans Sitecore que la demande a été résolue correctement.

• ❌ https://edge.sitecorecloud.io//media/Foui/logo.png (404)
• ✅ https://edge.sitecorecloud.io//media/Foui/logo.png (200)

Le support Sitecore a reconnu ce problème et enregistré un bug (numéro de référence 597185).

Les plats à emporter : Si vous publiez des images sur Experience Edge et que vous ajoutez des configurations de correctifs pour manipuler la casse des URL, assurez-vous de vérifier qu’après la publication, les URL des éléments multimédias qui atteignent Experience Edge sont résolues comme prévu. Nous avons fini par annuler la modification de la configuration du gestionnaire de liens.

Déploiement XM Cloud via la CLI Sitecore

Sur un récent projet XM Cloud, la tâche de notre pipeline Azure DevOps YAML responsable du déploiement sur XM Cloud ressemblait initialement à ceci :

...
- script: |
  dotnet sitecore cloud login --client-credentials --client-id ${{ parameters.xmcClientId }} --client-secret ${{ parameters.xmcClientSecret }} --allow-write
  echo 'Logged in - Deploying to XM Cloud'
  dotnet sitecore cloud deployment create --environment-id ${{ parameters.environmentId }} --upload
  echo 'Deployment to XM Cloud Completed.'
...

Le login sans surprise, la commande se connecterait à XM Cloud avant le déploiement et le deployment create La commande regrouperait le code dans le répertoire de travail et lancerait le déploiement. Cela a bien fonctionné pendant un moment. Cependant, nous avons remarqué qu’en cas de problème avec le déploiement (selon l’interface XM Cloud Deploy), la tâche de déploiement dans le pipeline s’exécutait pendant environ 20 minutes avant de signaler un problème. réussi achèvement… malgré un problème de déploiement sous-jacent signalé dans XM Cloud Deploy. De plus, les journaux du pipeline ont même signalé un problème, mais la tâche a quand même réussi, ce qui signifie que nous avons eu un faux positif.

Nous avons appris que, au moins pour les versions de Sitecore CLI et les outils que nous utilisions (Sitecore CLI 5.2.113 et Sitecore.DevEx.Extensibility.XMCloud 1.1.30), la commande de déploiement est renvoyée avec succès si le déploiement a été soumis avec succès, pas nécessairement que le déploiement lui-même ait réussi.

Nous sommes vite tombés sur ce problème dans le référentiel GitHub officiel de Sitecore XM Cloud Introduction qui pointait vers ce s’engager dans lequel le résultat de la dotnet sitecore cloud deployment create La commande a été capturée et analysée pour déterminer le résultat du déploiement (et refléter le même résultat que celui observé dans XM Cloud Deploy). Nous avons modifié notre tâche de pipeline (une tâche de script bash) en quelque chose comme ceci :

...
- script: |
  dotnet sitecore cloud login --client-credentials --client-id ${{ parameters.xmcClientId }} --client-secret ${{ parameters.xmcClientSecret }} --allow-write
  echo 'Logged in - deploying to XM Cloud'

  result=$(dotnet sitecore cloud deployment create --environment-id ${{ parameters.environmentId }} --upload --json)
  echo $result

  isTimedOut=$(echo $result | jq ' .IsTimedOut')
  isCompleted=$(echo $result | jq ' .IsCompleted')

  if [ $isTimedOut = true ]
  then
      echo "Deployment Timed Out."
      exit -1
  fi  
  if ! [ $isCompleted = true ]
  then
      echo "Deployment Failed."
      exit -1
  fi

  echo "Deployment Completed"
...

Noter la --json drapeau passé au cloud deployment create commande et que la valeur de retour de la commande est définie sur une variable. Le déploiement s’est maintenant terminé (avec succès ou non) et le résultat a été analysé pour déterminer l’état du déploiement qui a ensuite été correctement signalé dans le pipeline Azure DevOps. Le compromis est que nous n’obtenons plus la sortie de « progression » par défaut (avec les pourcentages d’achèvement, etc.) pendant l’exécution de la commande d’origine. Idéalement, la commande devrait à la fois renvoyer des informations détaillées sur la progression au fur et à mesure de son exécution et rapporter avec précision le résultat du déploiement (c’est-à-dire : un code retour différent de zéro pour les déploiements ayant échoué).

Les plats à emporter : Si vous utilisez la CLI Sitecore pour déployer sur XM Cloud, il est préférable d’analyser le résultat de la dotnet sitecore cloud deployment create commande pour obtenir le résultat du déploiement plutôt que de risquer un faux positif, même si cela signifie ne pas voir la progression du déploiement sophistiqué pendant l’exécution de la commande.

Provisionnement des informations d’identification d’administrateur Experience Edge dans XM Cloud Deploy

Les administrateurs Sitecore gèrent les instances Experience Edge à l’aide de l’outil Administrateur API. Cette API permet des opérations telles que vider le cache, supprimer du contenu, gérer la durée de vie du cache et les paramètres d’effacement automatique, ainsi que gérer les webhooks. Pour une solution PaaS utilisant Experience Edge, Sitecore fournit généralement les informations d’identification pour gérer la ou les instances Experience Edge via l’API Admin. Le processus d’obtention d’informations d’identification similaires dans XM Cloud est un peu différent. Ce l’article de blog (et d’autres, je suppose) décrit le problème et la solution. Le résultat net, essentiellement, est que des étapes supplémentaires sont nécessaires pour obtenir un jeton d’accès avec les étendues Experience Edge (autorisations) appropriées avec lesquelles appeler ensuite l’API d’administration.

Après avoir appris cela, un membre de notre équipe (…c’est moi, salut, c’est moi le problème, c’est moi) a créé une collection Postman pour automatiser entièrement la série d’appels nécessaires pour obtenir un jeton d’accès pour finalement appeler l’API Admin (principalement pour vider le cache à des fins de dépannage). Ces demandes automatisées ont été effectuées à plusieurs reprises dans différents environnements sur une période d’environ un mois. Les appels comprenaient une requête POST adressée au https://xmclouddeploy-api.sitecorecloud.io/api/clients/v1/edge point de terminaison avec la charge utile suivante :

{
  "projectId": "<PROJECT_ID_HERE>",
  "environmentId": "<ENVIRONMENT_ID_HERE>",
  "name": "EDGE_CI_CD",
  "description": "Credentials for interacting with the Experience Edge Admin API in <ENVIRONMENT>."
}

Quoi n’était pas Il est immédiatement clair pour cette personne (moi) que cette demande crée un identifiant permanent dans XM Cloud Deploy – il ne fait pas créer un identifiant éphémère à usage unique. Autrement dit, lorsque cette requête est effectuée avec succès, un nouvel élément est ajouté à cette liste dans l’interface XM Cloud Deploy :

Découvrez les informations d’identification d’administration Edge répertoriées dans l’interface XM Cloud Deploy.

Cette fourniture itérative (et totalement superflue) d’informations d’identification a atteint son paroxysme lorsque, apparemment tout d’un coup, l’appel à ce point de terminaison a cessé de fonctionner et a commencé à renvoyer une erreur énigmatique qui, au moins pour cette personne (oui, toujours moi) était  » Ce n’est pas incroyablement révélateur. La demande échouerait avec un 504 - Gateway Timeout qui avait la signature de réponse suivante :

HTTP/1.1 504 Gateway Timeout
Date: Wed, 15 Nov 2023 18:29:44 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 51
Connection: close
CF-Cache-Status: DYNAMIC
Server: cloudflare
CF-RAY: 82698e3fbad653db-ATL
alt-svc: h3=":443"; ma=86400

{
  "message": "The upstream server is timing out"
}

Après avoir travaillé avec le support Sitecore, il est devenu connu que, parce que le point de terminaison XM Cloud Deploy pour fournir de nouvelles informations d’identification Experience Edge avait été appelé à de nombreuses reprises, nous avions dépassé une limite supérieure non documentée sur le nombre d’informations d’identification Experience Edge autorisées pour un donné. projet: dix. Lorsque la demande de création du 11ème identifiant a été effectuée, elle a échoué avec le 504.

L’ingénieur du support Sitecore a enregistré le comportement comme un bug, ne serait-ce que pour mettre à jour la documentation afin d’inclure un verbiage décrivant la limite stricte (numéro de référence 603658).

Les plats à emporter : Ne pas automatiser les appels vers les API XM Cloud Deploy https://xmclouddeploy-api.sitecorecloud.io/api/clients/v1/edge point final pour fournir les informations d’identification. Il vaut mieux prévoir un ensemble d’informations d’identification d’administration Experience Edge pour chaque environnement et distribuez ces informations d’identification en toute sécurité à votre équipe à l’aide, par exemple, d’un Azure Key Vault ou [insert your favorite secrets management tool here].

Merci pour la lecture! 🙏