Uso de API de vista previa en sitios de Oracle Content Management sin cabecera

Introducción

En este tutorial se describe cómo agregar soporte para la nueva API de REST para Content Preview en las aplicaciones de Oracle Content Management que utilizan el SDK de Oracle Content. Agregar esta funcionalidad facilita a los creadores de contenido ver su nuevo contenido en la misma aplicación que se utiliza para presentar su trabajo de producción. También abre la puerta al uso de la orquestación para manejar las versiones de producción y prototipo de la aplicación con cambios mínimos en el proceso de creación.

Tenga en cuenta que, si bien las versiones anteriores del SDK de contenido admitían un modo de vista previa, se basaba en otra interfaz REST del servidor que no estaba optimizada para la tarea. Cambiar a la API más reciente no es difícil y ayudará a preparar sus aplicaciones para el futuro.

En las siguientes secciones se proporcionan algunos detalles sobre los cambios realizados en el SDK de contenido, se describe cómo modificar un proyecto de ejemplo, el ejemplo de blog de React, para soportar la nueva API de vista previa y, por último, cómo obtener y utilizar los parámetros OAuth.

Este tutorial se centra en React, pero puede utilizar un enfoque similar para otras tecnologías web, como Angular, Gatsby, Next.js, Svelte y Vue.js.

Cambios en el SDK de Oracle Content

El SDK de Oracle Content es una biblioteca JavaScript que proporciona envoltorios adecuados para las llamadas de la API de REST de Oracle Content Management. Permite a las aplicaciones buscar y recuperar activos publicados y de vista previa del servidor sin tener que realizar llamadas REST directas. En este contexto, un activo publicado es un elemento de contenido que se ha hecho público mientras que un activo de vista previa es información que todavía está en desarrollo o que puede ser pública en algún momento en el futuro. Un activo publicado puede estar disponible con o sin necesidad de autenticación, mientras que un activo de previsualización siempre requiere autenticación.

Al utilizar el SDK de contenido, una aplicación creará una instancia de un cliente de contenido, ya sea contentDeliveryClient (para el contenido publicado) o contentPreviewClient (para el contenido de vista previa). En versiones anteriores del SDK de Oracle Content, solo había una interfaz de previsualización disponible. Se trata de un envoltorio que utilizó la API de REST para la gestión de contenido del servidor para realizar sus consultas. Aunque esto funcionó, no fue una solución óptima, ya que la API de REST se diseñó realmente para otros fines. Por este motivo, se introdujo una segunda interfaz: la API de REST para Content Preview. Ahora se puede seleccionar como alternativa al crear un cliente de vista previa en el SDK de Oracle Content.

API Rest utilizadas por el SDK de contenido

Estas son las API de REST que el SDK de contenido utiliza internamente:

Cómo configurar la aplicación de blog React para utilizar la nueva API de vista previa

Utilizaremos el ejemplo de blog React como base para este tutorial. Tenga en cuenta que utiliza la biblioteca dotenv, que permite cambiar los parámetros de creación mediante variables de entorno. Esto es valioso porque permite cambiar la aplicación del modo de publicación a vista previa sin cambios en el código interno.

  1. Primero, deberá instalar y crear el ejemplo de blog React. Al final de este paso, debe tener una aplicación que se pueda crear ejecutando npm run build y ejecutándose npm run start.

  2. Si la aplicación se está ejecutando, deténgala. Ahora procederemos a configurarla para utilizar el nuevo soporte de vista previa:

    1. Abra el archivo .env (situado en el directorio raíz de la aplicación).

    2. Agregue las siguientes líneas al archivo:

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

    La primera entrada, PREVIEW, se utiliza para indicar a la aplicación que se ejecute en modo de vista previa.

    La segunda entrada, OPCIONES, especifica que queremos utilizar la API de REST para Content Preview para el modo de previsualización. Como alternativa, la opción previewClientApi se podría haber definido en managementREST, pero eso solo se debe utilizar para la compatibilidad heredada.

Cómo definir los parámetros OAuth para el modo de vista previa

Para completar la configuración de la aplicación de blog, necesitamos configurar los parámetros OAuth necesarios para autenticarse en el servidor. Puede adoptar una de estas dos formas:

  1. Una cadena de token de portador definida en el archivo .env de la siguiente manera:

     AUTH=Bearer xxxxxx

    donde xxxxxx es el token OAuth de la aplicación.

    Esta opción es rápida y práctica si ya tiene una cadena de token OAuth válida que puede utilizar. Sin embargo, tiene una limitación en que el token solo puede ser válido durante un cierto período de tiempo y la aplicación comenzará a fallar una vez que el token haya caducado. Esto nos lleva a la segunda opción, que tiene una configuración más compleja, pero puede recuperar nuevos tokens a medida que los existentes caducan.

  2. Proporcione un objeto en el archivo .env con el siguiente formato:

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

    El parámetro IDP_URL es el URI del explorador de identidad. Puede ser Oracle Identity Cloud Service (IDCS) o Identity Access Management (IAM) cuando se utiliza con Oracle Content Management.

La documentación de Oracle Content Management proporciona detalles sobre cómo configurar una aplicación cliente y cómo obtener estos valores de parámetros.

Si se especifican AUTH y AUTH_PARAMS, AUTH_PARAMS tiene prioridad.

Manejo especial de la seguridad de la vista previa en el blog de React

Dependiendo de qué marco de JavaScript se utilice y de cómo se escriba una aplicación, puede realizar la recuperación de contenido y la generación de páginas por completo en el servidor, por completo en el cliente o una mezcla de ambos. En el caso de Ejemplo de blog React y otros ejemplos de CMS sin cabecera, se decidió que la recuperación de contenido seguro siempre debería producirse en el servidor para que el cliente no tuviera que saber nada sobre los valores de configuración de seguridad. Por este motivo, los clientes se modificaron para redirigir las llamadas directas al sistema de gestión de contenido de nuevo al servidor de la aplicación, lo cual sería responsable de recuperar y devolver el contenido.

Un ejemplo sencillo de esto se puede ver al cargar la página inicial de la aplicación React blog. Al cargar la página en un explorador, el servidor envía una página predefinida rellena con todo el contenido de texto. Sin embargo, todas las imágenes se proporcionan como direcciones URL que debe cargar el explorador web directamente desde Oracle Content Management. Esto requeriría que el explorador web realice llamadas autenticadas, que es algo que no queremos que haga. La solución es hacer que el código intercepte dichas llamadas y redirija de nuevo a la aplicación NodeJS que sirve a la aplicación.

En el caso de la aplicación de blog React, el código que redirige las llamadas directas al sistema de gestión de contenido al servidor se encuentra en /src/server/server.js.

En primer lugar, el servidor Express que proporciona la compatibilidad del servidor tiene el siguiente código de redirección:

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

Y eso a su vez llama:

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,
    });
  };

Conclusión

Agregar soporte de vista previa a la aplicación Oracle Content Management es una forma sencilla de aumentar la flexibilidad y el valor del producto. Algunas de las ventajas que esto aporta son: