Utiliser les API d'aperçu sur les sites Oracle Content Management sans tête

Introduction

Ce tutoriel explique comment ajouter la prise en charge de la nouvelle API REST pour l'aperçu de contenu dans les applications Oracle Content Management qui utilisent le kit SDK Oracle Content. L'ajout de cette fonctionnalité permet aux créateurs de contenu de visualiser facilement leur nouveau contenu dans la même application que celle utilisée pour effectuer leur travail de production. Il ouvre également la porte à l'utilisation de l'orchestration pour gérer les versions de production et de prototype de l'application avec des modifications minimales du processus de création.

Même si les versions précédentes du kit SDK de contenu prenaient en charge un mode d'aperçu, il reposait sur une interface REST côté serveur différente qui n'était pas optimisée pour la tâche. Passer à la nouvelle API n'est pas difficile et vous permettra de pérenniser vos applications.

Les sections ci-dessous fournissent des détails sur les modifications apportées au kit SDK Content, décrivent comment modifier un exemple de projet, l'exemple de blog React, pour prendre en charge la nouvelle API d'aperçu, et enfin comment obtenir et utiliser les paramètres OAuth.

Ce tutoriel se concentre sur React, mais vous pouvez adopter une approche similaire pour les autres technologies Web, notamment Angular, Gatsby, Next.js, Svelte et Vue.js.

Modifications dans le kit SDK Oracle Content

Le kit SDK Oracle Content est une bibliothèque JavaScript qui fournit des wrappers pratiques pour les appels d'API REST Oracle Content Management. Elle permet aux applications de rechercher et d'extraire des ressources publiées et de prévisualiser à partir du serveur sans avoir à effectuer d'appels REST directs. Dans ce contexte, une ressource publiée est un élément de contenu rendu public tandis qu'une ressource d'aperçu est une information en cours de développement ou peut être publique à un moment donné. Une ressource publiée peut être rendue disponible avec ou sans authentification, tandis qu'une ressource d'aperçu nécessite toujours une authentification.

Lorsque vous utilisez le kit SDK de contenu, une application crée une instance d'un client de contenu : contentDeliveryClient (pour le contenu publié) ou contentPreviewClient (pour le contenu d'aperçu). Dans les versions précédentes du kit SDK Oracle Content, une seule interface d'aperçu était disponible. Ce wrapper a utilisé l'API REST pour la gestion de contenu du serveur pour exécuter ses requêtes. Bien que cela fonctionne, il ne s'agissait pas d'une solution optimale, car l'API REST a été réellement conçue à d'autres fins. Pour cette raison, une seconde interface a été introduite : l'API REST pour l'aperçu de contenu. Vous pouvez maintenant sélectionner cette option lors de la création d'un client d'aperçu dans le kit SDK Oracle Content.

API Rest utilisées par le kit SDK Content

Voici les API REST que le kit SDK de contenu utilise en interne :

Configuration de l'application React Blog pour utiliser la nouvelle API d'aperçu

Nous utiliserons l'exemple de blog React comme base pour ce tutoriel. Notez qu'il utilise la bibliothèque dotenv, qui vous permet de modifier les paramètres de construction à l'aide de variables d'environnement. Cela est utile car il permet à l'application de passer du mode publié au mode aperçu sans modification du code interne.

  1. Vous devez d'abord installer et créer l'exemple de blog React. A la fin de cette étape, vous devez disposer d'une application pouvant être créée en exécutant npm run build et exécutée en exécutant npm run start.

  2. Si l'application est en cours d'exécution, arrêtez-la. Nous allons maintenant la configurer pour utiliser le nouveau support d'aperçu :

    1. Ouvrez le fichier .env (situé dans le répertoire racine de l'application).

    2. Ajoutez les lignes suivantes au fichier :

      PREVIEW=TRUE    
OPTIONS='{ "previewClientAPI": "previewREST" }'

    La première entrée, PREVIEW, est utilisée pour indiquer à l'application de s'exécuter en mode aperçu.

    La deuxième entrée, OPTIONS, indique que nous voulons utiliser l'API REST pour l'aperçu de contenu en mode aperçu. Sinon, l'option previewClientApi aurait pu être définie sur managementREST, mais elle ne doit être utilisée que pour la prise en charge héritée.

Définition des paramètres OAuth pour le mode Aperçu

Pour terminer la configuration de l'application de blog, nous devons configurer les paramètres OAuth nécessaires à l'authentification auprès du serveur. Cela peut prendre l'une des deux formes suivantes :

  1. Chaîne de jeton de porteur définie dans le fichier .env comme suit :

     AUTH=Bearer xxxxxx

    où xxxxxx est le jeton OAuth de votre application.

    Cette option est rapide et pratique si vous disposez déjà d'une chaîne de jeton OAuth valide que vous pouvez utiliser. Cependant, il est limité en ce que le jeton ne peut être valide que pendant un certain temps et l'application commencera à échouer une fois le jeton arrivé à expiration. Cela nous amène à la deuxième option, qui dispose d'une configuration plus complexe, mais peut récupérer de nouveaux jetons à l'expiration des jetons existants.

  2. Fournissez un objet dans le fichier .env au format suivant :

    AUTH_PARAMS='{ "CLIENT_ID": "aaa", "CLIENT_SECRET": "bbb", "CLIENT_SCOPE_URL": "ccc", "IDP_URL": "ddd" }'

    Le paramètre IDP_URL est l'URI du proverbe d'identité. Il peut s'agir d'Oracle Identity Cloud Service (IDCS) ou d'Identity Access Management (IAM) lorsqu'il est utilisé avec Oracle Content Management.

La documentation Oracle Content Management fournit des détails sur la configuration d'une application client et sur la manière d'obtenir ces valeurs de paramètre.

Si AUTH et AUTH_PARAMS sont indiqués, AUTH_PARAMS est prioritaire.

Gestion spéciale de la sécurité d'aperçu dans l'exemple de blog React

En fonction de la structure JavaScript utilisée et de la manière dont une application est écrite, elle peut effectuer sa récupération de contenu et sa génération de page entièrement côté serveur, entièrement côté client ou un mélange des deux. Dans le cas de l'exemple de blog React et d'autres échantillons CMS sans tête, il a été décidé que l'extraction de contenu sécurisé devrait toujours se faire côté serveur afin que le côté client n'ait pas à connaître les paramètres de configuration de la sécurité. Pour cette raison, les clients ont été modifiés pour rediriger les appels directs vers le système de gestion de contenu vers le côté serveur de l'application, qui serait alors responsable de l'extraction et du renvoi du contenu.

Un exemple simple de ceci peut être vu lors du chargement de la page d'accueil de l'application de blog React. Lors du chargement de la page dans un navigateur, le serveur envoie une page prédéfinie remplie de tout le contenu texte. Toutefois, toutes les images sont fournies sous forme d'URL à charger par le navigateur Web directement à partir d'Oracle Content Management. Cela nécessiterait que le navigateur Web effectue des appels authentifiés, ce qui est quelque chose que nous ne voulons pas. La solution consiste à ce que le code intercepte ces appels et les redirige vers l'application NodeJS servant l'application.

Dans le cas de l'application de blog React, le code qui redirige les appels directs vers le système de gestion de contenu côté serveur se trouve dans /src/server/server.js.

Tout d'abord, le serveur express fournissant le support côté serveur dispose du code de redirection suivant :

server.use('/content/', (req, res) => {
  const client = getClient();
  client.getAuthorizationHeaderValue().then((authValue) => {
    handleContentRequest(req, res, authValue);
   });
 });

Et cela appelle à son tour :

function handleContentRequest(req, res, authValue) {
  // only proxy GET requests, ignore all other requests
  if (req.method !== 'GET') {
    return;
  }

  // build the URL to the real server
  let content = process.env.SERVER_URL.charAt(process.env.SERVER_URL.length - 1) === '/'
    ? 'content' : '/content';
  if (req.url.charAt(0) !== '/') {
    content = `${content}/`;
  }
  const oceUrl = `${process.env.SERVER_URL}${content}${req.url}`;

  // Add the authorization header
  const options = {};
  if (authValue) {
    options.headers = { Authorization: authValue };
  }

  // define a function that writes the proxied content to the response
  const writeProxyContent = (proxyResponse) => {
    res.writeHead(proxyResponse.statusCode, proxyResponse.headers);
    proxyResponse.pipe(res, {
      end: true,
    });
  };

Conclusion

L'ajout de la prise en charge de l'aperçu à votre application Oracle Content Management est un moyen simple d'augmenter la flexibilité et la valeur de votre produit. Les avantages qu'elle apporte sont les suivants :