Uso delle API di anteprima nei siti Oracle Content Management headless

Introduzione

Questa esercitazione descrive come aggiungere supporto per la nuova API REST per l'anteprima contenuto nelle applicazioni Oracle Content Management che utilizzano l'SDK di Oracle Content. L'aggiunta di questa funzionalità consente ai creatori di contenuti di visualizzare facilmente i nuovi contenuti nella stessa applicazione utilizzata per eseguire il lavoro di produzione. Inoltre, apre la porta all'uso dell'orchestrazione per gestire le versioni di produzione e prototipo dell'applicazione con modifiche minime al processo di creazione.

Tenere presente che, mentre le versioni precedenti dell'SDK contenuto supportavano una modalità di anteprima, l'SDK si basava su un'interfaccia REST lato server diversa non ottimizzata per il task. Passare all'API più recente non è difficile e aiuterà le tue applicazioni a prova di futuro.

Le sezioni seguenti forniscono alcuni dettagli sulle modifiche apportate all'SDK di contenuto, descrivono come modificare un progetto di esempio, il esempio di blog React, per supportare la nuova API di anteprima e infine come ottenere e utilizzare i parametri OAuth.

Questa esercitazione si concentra su React, ma è possibile utilizzare un approccio simile per altre tecnologie Web, tra cui Angular, Gatsby, Next.js, Svelte e Vue.js.

Modifiche all'SDK di Oracle Content

Oracle Content SDK è una libreria JavaScript che fornisce wrapper convenienti in base alle chiamate API REST di Oracle Content Management. Consente alle applicazioni di cercare e recuperare asset pubblicati e visualizzare in anteprima dal server senza dover effettuare chiamate REST dirette. In questo contesto, un asset pubblicato è un elemento di contenuto reso pubblico mentre un asset di anteprima è informazioni ancora in fase di sviluppo o che potrebbero essere pubbliche in futuro. Un asset pubblicato può essere reso disponibile con o senza richiedere l'autenticazione, mentre un asset di anteprima richiede sempre l'autenticazione.

Quando si utilizza Content SDK, un'applicazione creerà un'istanza di un client di contenuto, ovvero contentDeliveryClient (per il contenuto pubblicato) o contentPreviewClient (per il contenuto di anteprima). Nelle versioni precedenti dell'SDK di Oracle Content era disponibile una sola interfaccia di anteprima. Wrapper che ha utilizzato l'API REST per la gestione dei contenuti del server per eseguire le relative query. Benché questo abbia funzionato, non è stata una soluzione ottimale poiché l'API REST è stata realmente progettata per altri scopi. Per questo motivo è stata introdotta una seconda interfaccia: l'API REST per l'anteprima del contenuto. È ora possibile selezionare questa opzione come alternativa quando si crea un client di anteprima nel Oracle Content SDK.

Interfacce API restanti utilizzate dall'SDK dei contenuti

Di seguito sono riportate le interfacce API REST utilizzate internamente dall'SDK di contenuto.

Come configurare l'applicazione di blog React per l'uso della nuova API Preview

Per questa esercitazione verrà utilizzato il esempio di blog React come base. Si noti che utilizza la libreria dotenv, che consente di modificare i parametri di build utilizzando le variabili di ambiente. Ciò è utile perché consente di passare dall'applicazione alla modalità di anteprima senza apportare modifiche al codice interno.

  1. Per prima cosa, dovrai installare e creare l'esempio di blog React. Alla fine di questo passo, è necessario disporre di un'applicazione che può essere creata eseguendo npm run build ed eseguendo npm run start.

  2. Se l'applicazione è in esecuzione, arrestarla. Procederemo con la configurazione per utilizzare il nuovo supporto anteprima:

    1. Aprire il file .env (nella directory radice dell'applicazione).

    2. Aggiungere al file le seguenti righe:

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

    La prima voce, PREVIEW, viene utilizzata per indicare l'esecuzione dell'applicazione in modalità anteprima.

    La seconda voce, OPTIONS, specifica che si desidera utilizzare l'API REST per l'anteprima del contenuto per la modalità di anteprima. In alternativa, l'opzione previewClientApi potrebbe essere stata impostata su managementREST, ma dovrebbe essere utilizzata solo per il supporto precedente.

Come impostare i parametri OAuth per la modalità anteprima

Per completare la configurazione dell'applicazione blog, è necessario configurare i parametri OAuth necessari per l'autenticazione sul server. Questo può assumere una delle due forme seguenti:

  1. Stringa di token del portatore impostata nel file .env come indicato di seguito:

     AUTH=Bearer xxxxxx

    dove xxxxxx è il token OAuth dell'applicazione.

    Questa opzione è rapida e conveniente se si dispone già di una stringa di token OAuth valida utilizzabile. Tuttavia, ha una limitazione in quanto il token può essere valido solo per un determinato periodo di tempo e l'applicazione inizierà a non funzionare dopo la scadenza del token. Questo ci porta alla seconda opzione, che ha una configurazione più complessa, ma può recuperare nuovi token alla scadenza di quelli esistenti.

  2. Fornire un oggetto nel file .env con il seguente formato:

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

    Il parametro IDP_URL è l'URI del provider di identità. Può essere Oracle Identity Cloud Service (IDCS) o IAM (Identity Access Management) quando utilizzato con Oracle Content Management.

Nella documentazione di Oracle Content Management vengono forniti dettagli su come configurare un'applicazione client e su come ottenere questi valori di parametro.

Se vengono specificati sia AUTH che AUTH_PARAMS, la priorità è AUTH_PARAMS.

Gestione speciale della sicurezza di anteprima nel campione del blog React

A seconda di quale framework JavaScript viene utilizzato e di come viene scritta un'applicazione, può eseguire il recupero dei contenuti e la generazione di pagine interamente sul lato server, interamente sul lato client, oppure una combinazione di entrambi. Nel caso di un esempio di blog React e di altri esempi di CMS headless, è stato deciso che il recupero sicuro dei contenuti dovrebbe avvenire sempre sul lato server, in modo che il lato client non dovrebbe conoscere le impostazioni di configurazione della sicurezza. Per questo motivo, i client sono stati modificati per reindirizzare le chiamate dirette al sistema di gestione dei contenuti sul lato server dell'applicazione, che sarebbe poi responsabile del recupero e della restituzione del contenuto.

Un semplice esempio può essere visualizzato quando si carica la home page dell'applicazione del blog React. Quando si carica la pagina in un browser, il server invia una pagina predefinita popolata con tutto il contenuto del testo. Tutte le immagini, tuttavia, vengono fornite come URL che devono essere caricati dal browser Web direttamente da Oracle Content Management. Questo richiederebbe al browser di effettuare chiamate autenticate, che è qualcosa che non vogliamo che faccia. La soluzione prevede che il codice intercetta tali chiamate e li reindirizzi all'applicazione NodeJS che gestisce l'applicazione.

Nel caso dell'applicazione del blog React, il codice che reindirizza le chiamate dirette al sistema di gestione dei contenuti sul lato server è disponibile in /src/server/server.js.

In primo luogo, il server Express che fornisce il supporto lato server ha il seguente codice di reindirizzamento:

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

E questo a sua volta chiama:

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

Conclusione

L'aggiunta del supporto in anteprima all'applicazione Oracle Content Management rappresenta un modo semplice per aumentare la flessibilità e il valore del prodotto. Ecco alcuni dei vantaggi che ciò comporta: