在無頭 (headless) Oracle Content Management 網站中使用預覽 API

簡介

本教學課程說明如何在使用 Oracle Content SDK 的 Oracle Content Management 應用程式中為新的 REST API for Content Preview 新增支援。新增此功能可讓內容建立者輕鬆在用來轉譯其生產工作的相同應用程式中檢視其新內容。它也會開啟門以使用協調流程，在對組建處理作業進行最少的變更時，同時處理應用程式的生產和原型版本。

請注意，當舊版的 Content SDK 支援預覽模式時，它是以不同的伺服器端 REST 介面為基礎，而該介面未針對作業進行最佳化。切換到更新版的 API 並不困難，未來將會協助您的應用程式經得起未來的考驗。

下列各節提供有關如何對 Content SDK 進行變更的詳細資訊，說明如何修改範例專案、反應部落格範例、支援新的預覽 API，以及最終如何取得和使用 OAuth 參數。

本教學課程著重於 React，但您可以對其他 Web 技術使用類似的方式，包括 Angular、Gatsby、Next.js、Svelte 及 Vue.js。

Oracle Content SDK 中的變更

Oracle Content SDK 是一種 JavaScript 程式庫，提供 Oracle Content Management REST API 呼叫的便利包裝。它可讓應用系統在不須進行直接 REST 呼叫的情況下，從伺服器搜尋及擷取已發布和預覽資產。在此內容中，已發布的資產是已公開的內容，而預覽資產是仍在開發中的資訊，或可能會在未來某個時間公用。已發布的資產在預覽資產一律需要驗證時，可以使用或不需要驗證。

使用 Content SDK 時，應用程式會建立 contentDeliveryClient (適用於已發布的內容) 或 contentPreviewClient (適用於預覽內容) 的內容從屬端執行處理。在舊版的 Oracle Content SDK 中，只有一個預覽介面可供使用。這是使用伺服器的 REST API for Content Management 執行其查詢的包裝函式。雖然這樣做的工作並不是最佳解決方案，因為 REST API 確實是針對其他用途所設計。因此，引進了第二個介面：REST API for Content Preview。在 Oracle Content SDK 中建立預覽從屬端時，現在可以將它選取為替代選項。

內容 SDK 使用的 Rest API

這些是 Content SDK 在內部使用的 REST API：

如何設定反應部落格應用程式以使用新預覽 API

我們將以反應部落格範例作為本教學課程的基礎。請注意，它使用 dotenv 程式庫，您可以使用環境變數來變更組建參數。這有價值，因為它允許應用程式從已發布切換為預覽模式，而不對內部程式碼進行任何變更。

  1. 首先，您需要安裝並建置 React 部落格範例。在此步驟結束時，您應該要有能夠透過執行 npm run build 建立的應用程式，然後執行 npm run start 來執行。

  2. 如果應用程式正在執行，請將其停止。現在我們將繼續設定成使用新的預覽支援：

    1. 開啟 .env 檔案 (位於應用程式的根目錄中)。

    2. 新增下列行至檔案：

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

    第一個項目 PREVIEW 會用來告知應用程式在預覽模式中執行。

    第二個項目 OPTIONS 指定我們要使用 REST API 進行預覽模式。您可以改為將 previewClientApi 選項設為 managementREST，但只能用於傳統支援。

如何設定預覽模式的 OAuth 參數

若要完成部落格應用程式的組態，我們需要設定向伺服器認證所需的 OAuth 參數。這可以採用兩種形式的其中一種：

  1. .env 檔案中所設定的 bearer 記號字串，如下所示：

     AUTH=Bearer xxxxxx

    其中 xxxxxx 是您應用程式的 OAuth 記號。

    如果已有可使用的有效 OAuth 記號字串，此選項會快速方便。不過，此權杖只有一段時間才有效，且一旦權杖過期，應用程式就會開始失敗。這會將我們帶到第二個選項，該選項具有較複雜的設定，但可在現有的記號到期時擷取新的記號。

  2. 以 .env 檔案格式提供物件：

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

    IDP_URL 參數是您識別產生器的 URI。與 Oracle Content Management 搭配使用時，可以是 Oracle Identity Cloud Service (IDCS) 或身分識別存取管理 (IAM)。

Oracle Content Management 文件提供如何設定從屬端應用程式以及如何取得這些參數值的詳細資訊。

如果同時指定 AUTH 和 AUTH_PARAMS，則會優先執行 AUTH_PARAMS。

React 部落格範例中的預覽安全性特殊處理

視使用的 JavaScript 架構以及應用程式寫入方式而定，它可能會在伺服器端、完全在從屬端上執行其內容擷取與頁面產生，或是兩者混合。如果是反應部落格範例與其他無頭 (headless) CMS 範例，它被認為安全內容擷取應一律在伺服器端進行，因此用戶端不必知道安全組態設定值的任何內容。因此，已修改用戶端將直接呼叫的內容管理系統重新導向至應用程式的伺服器端，這會負責擷取與傳回內容。

載入 React 部落格應用程式的首頁時，可以看到這個範例。在瀏覽器中載入頁面時，伺服器會傳送一個植入所有文字內容的預建頁面。不過，所有影像都會提供為 Web 瀏覽器直接從 Oracle Content Management 載入的 URL。這需要 Web 瀏覽器撥打經過認證的通話，這是我們不想做的事。此解決方案是用來讓程式碼攔截這類呼叫，並將它們重新導向至提供應用程式的 NodeJS 應用程式。

若是 React 部落格應用程式，可在 /src/server/server.js 中找到將直接呼叫的內容管理系統重新導向至伺服器端的程式碼。

首先，提供伺服器端支援的快速伺服器具有下列重新導向代碼：

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

反而呼叫：

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

結論

新增預覽支援至 Oracle Content Management 應用程式是增加產品彈性和價值的一種簡單方式。這種帶來的好處包括：