Vorschau-APIs in Headless-Oracle Content Management-Sites verwenden

Einführung

In diesem Tutorial wird beschrieben, wie Sie Unterstützung für die neue REST-API für Inhaltsvorschau in Oracle Content Management-Anwendungen hinzufügen, die das Oracle Content-SDK verwenden. Durch das Hinzufügen dieser Funktionalität können Inhaltsersteller ihre neuen Inhalte in derselben Anwendung anzeigen, die zur Wiedergabe ihrer Produktionsarbeit verwendet wird. Außerdem wird die Tür geöffnet, mit der Orchestrierung Produktions- und Prototypversionen der Anwendung mit minimalen Änderungen am Erstellungsprozess verarbeitet werden können.

Während frühere Versionen des Content-SDK einen Vorschaumodus unterstützt haben, basierte es auf einer anderen serverseitigen REST-Schnittstelle, die nicht für die Aufgabe optimiert wurde. Der Wechsel zur neueren API ist nicht schwierig und hilft Ihnen, Ihre Anwendungen zukunftssicher zu machen.

Die folgenden Abschnitte enthalten einige Details zu den Änderungen am Content-SDK, beschreiben, wie Sie ein Beispielprojekt ändern, das React-Blogbeispiel, um die neue Vorschau-API zu unterstützen und schließlich OAuth-Parameter abzurufen und zu verwenden.

Dieses Tutorial konzentriert sich auf React, Sie können jedoch einen ähnlichen Ansatz für andere Web-Technologien verwenden, einschließlich Angular, Gatsby, Next.js, Svelte und Vue.js.

Änderungen am Oracle Content-SDK

Das Oracle Content-SDK ist eine JavaScript-Library, die praktische Wrapper für Oracle Content Management-REST-API-Aufrufe bereitstellt. Damit können Anwendungen sowohl veröffentlichte als auch Vorschau von Assets vom Server suchen und abrufen, ohne direkte REST-Aufrufe tätigen zu müssen. In diesem Kontext ist eine veröffentlichte Anlage ein Inhaltselement, das veröffentlicht wurde, während eine Vorschauanlage Informationen ist, die sich noch in der Entwicklung befinden oder irgendwann in der Zukunft öffentlich sein können. Ein veröffentlichtes Asset kann mit oder ohne Authentifizierung verfügbar gemacht werden, während ein Vorschauasset immer eine Authentifizierung erfordert.

Wenn Sie das Content-SDK verwenden, erstellt eine Anwendung eine Instanz eines Contentclients, entweder contentDeliveryClient (für veröffentlichten Inhalt) oder contentPreviewClient (für Vorschauinhalt). In früheren Versionen des Oracle Content-SDK war nur eine Vorschauschnittstelle verfügbar. Dies war ein Wrapper, der die REST-API für Content Management des Servers zur Ausführung seiner Abfragen verwendet hat. Das hat zwar funktioniert, war aber keine optimale Lösung, da die REST-API wirklich für andere Zwecke entwickelt wurde. Daher wurde eine zweite Schnittstelle eingeführt: die REST-API für Inhaltsvorschau. Dies kann jetzt als Alternative beim Erstellen eines Vorschauclients im Oracle Content-SDK ausgewählt werden.

Rest-APIs, die vom Content-SDK verwendet werden

Das Content-SDK verwendet die folgenden REST-APIs intern:

So konfigurieren Sie die React-Bloganwendung zur Verwendung der neuen Vorschau-API

Das React-Blogbeispiel wird als Basis für dieses Tutorial verwendet. Beachten Sie, dass die dotenv-Bibliothek verwendet wird, mit der Sie Build-Parameter mit Umgebungsvariablen ändern können. Dies ist nützlich, da die Anwendung vom veröffentlichten in den Vorschaumodus ohne Änderungen am internen Code gewechselt werden kann.

  1. Zuerst müssen Sie das React-Blogbeispiel installieren und erstellen. Am Ende dieses Schrittes benötigen Sie eine Anwendung, die mit npm run build erstellt und mit npm run start ausgeführt werden kann.

  2. Wenn die Anwendung ausgeführt wird, stoppen Sie sie. Anschließend wird die Konfiguration fortgesetzt, um die neue Vorschauunterstützung zu verwenden:

    1. Öffnen Sie die .env-Datei (im Root-Verzeichnis der Anwendung).

    2. Fügen Sie der Datei die folgenden Zeilen hinzu:

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

    Der erste Eintrag PREVIEW wird verwendet, um die Anwendung im Vorschaumodus anzuzeigen.

    Der zweite Eintrag OPTIONS gibt an, dass wir die REST-API für die Inhaltsvorschau für den Vorschaumodus verwenden möchten. Alternativ könnte die Option previewClientApi auf managementREST gesetzt sein, dies sollte jedoch nur für Legacy-Support verwendet werden.

So legen Sie die OAuth-Parameter für den Vorschaumodus fest

Um die Konfiguration der Bloganwendung abzuschließen, müssen die OAuth-Parameter konfiguriert werden, die für die Authentifizierung beim Server erforderlich sind. Dies kann eine von zwei Formen annehmen:

  1. Eine Bearer-Tokenzeichenfolge, die in der .env-Datei wie folgt festgelegt ist:

     AUTH=Bearer xxxxxx

    Dabei ist xxxxxx das Token OAuth der Anwendung.

    Diese Option ist schnell und bequem, wenn Sie bereits über eine gültige OAuth-Tokenzeichenfolge verfügen, die Sie verwenden können. Die Einschränkung besteht jedoch darin, dass das Token nur für einen bestimmten Zeitraum gültig sein kann und die Anwendung nach Ablauf des Tokens nicht erfolgreich verläuft. Dies führt uns zur zweiten Option, die ein komplexeres Setup aufweist, aber neue Token abrufen kann, wenn die vorhandenen Token ablaufen.

  2. Geben Sie ein Objekt in der .env-Datei im folgenden Format an:

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

    Der Parameter IDP_URL ist die URI Ihres Identitätsprovers. Bei Verwendung mit Oracle Content Management kann es sich um Oracle Identity Cloud Service (IDCS) oder Identity Access Management (IAM) handeln.

Die Oracle Content Management-Dokumentation enthält Details zur Konfiguration einer Clientanwendung und zum Abrufen dieser Parameterwerte.

Wenn sowohl AUTH als auch AUTH_PARAMS angegeben sind, hat AUTH_PARAMS Vorrang.

Besondere Behandlung von Vorschau-Sicherheit im React Blog Beispiel

Je nachdem, welches JavaScript-Framework verwendet wird und wie eine Anwendung geschrieben wird, kann sie ihre Inhaltsabruf- und Seitengenerierung vollständig auf der Serverseite, vollständig auf der Clientseite oder einer Mischung aus beiden ausführen. Bei dem React-Blogbeispiel und anderen headless CMS-Proben wurde entschieden, dass ein sicherer Content-Abruf immer auf Serverseite erfolgen sollte, damit die Clientseite keine Informationen über die Sicherheitskonfigurationseinstellungen erhalten müsste. Aus diesem Grund wurden die Clients so geändert, dass sie die direkten Aufrufe an das Content-Management-System zurück zur Serverseite der Anwendung umleiten, was dann für das Abrufen und Zurückgeben des Inhalts verantwortlich wäre.

Ein einfaches Beispiel dafür ist beim Laden der Homepage der React-Bloganwendung zu sehen. Beim Laden der Seite in einem Browser sendet der Server eine vordefinierte Seite mit dem gesamten Textinhalt. Alle Images werden jedoch als URLs bereitgestellt, die vom Webbrowser direkt aus Oracle Content Management geladen werden sollen. Dies würde erfordern, dass der Webbrowser authentifizierte Anrufe macht, was wir nicht wollen. Die Lösung besteht darin, dass der Code solche Aufrufe abfangen und zurück zur Anwendung NodeJS umleitet, die die Anwendung bedient.

Im Falle der React-Bloganwendung finden Sie den Code, der direkte Aufrufe an das Content-Management-System auf die Serverseite umleitet, in /src/server/server.js.

Zuerst hat der Express-Server, der die serverseitige Unterstützung bereitstellt, den folgenden Umleitungscode:

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

Und das wiederum ruft:

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

Schlussfolgerung

Das Hinzufügen von Vorschauunterstützung zu Ihrer Oracle Content Management-Anwendung ist eine einfache Möglichkeit, die Flexibilität und den Wert Ihres Produkts zu erhöhen. Sie bietet folgende Vorteile: