在无头 Oracle Content Management 站点中使用预览 API

简介

本教程介绍了如何在使用 Oracle Content SDK 的 Oracle Content Management 应用程序中添加对新 REST API for Content Preview 的支持。通过添加此功能，内容创建者可以在用于呈现生产工作的同一应用程序中轻松查看其新内容。它还为使用编排来处理应用的生产和原型版本打开了大门，大大减少了构建流程的更改。

请注意，虽然以前版本的内容 SDK 支持预览模式，但基于未针对任务优化的不同服务器端 REST 接口。切换到较新的 API 不难，并且有助于为您的应用提供面向未来的支持。

以下各节提供了有关内容 SDK 所做更改的一些详细信息，介绍如何修改示例项目、React 博客示例、支持新预览 API 以及如何获取和使用 OAuth 参数。

此教程侧重于 React，但您可以为其他 Web 技术（包括 Angular、Gatsby、Next.js、Svelte 和 Vue.js）使用类似的方法。

Oracle Content SDK 中的更改

Oracle Content SDK 是一个 JavaScript 库，可围绕 Oracle Content Management REST API 调用提供方便的包装。它允许应用从服务器搜索和检索已发布和预览资产，而无需直接进行 REST 调用。在此背景下，发布的资产是一段在预览资产时公开的内容，这些内容仍在开发中，也可能在未来某个时候公开。发布资产可以在不需要验证的情况下提供，而预览资产始终需要验证。

使用内容 SDK 时，应用程序将创建内容客户端的实例：contentDeliveryClient（对于已发布的内容）或 contentPreviewClient（对于预览内容）。在早期版本的 Oracle Content SDK 中，只有一个预览界面可用。这是使用服务器的 REST API for Content Management 执行其查询的包装器。虽然这确实有效，但这不是一个理想的解决方案，因为该 REST API 确实是为其他目的而设计的。因此，引入了第二个接口：用于内容预览的 REST API。现在，在 Oracle Content SDK 中创建预览客户端时，可以选择此选项作为替代方案。

内容 SDK 使用的 Rest API

这些是内容 SDK 在内部使用的 REST API：

如何配置 React Blog 应用程序以使用新预览 API

我们将使用React blogample作为本教程的基础。请注意，它使用 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 框架以及如何编写应用程序，它可能会完全在服务器端执行内容检索和页面生成，完全在客户端，或者两者混合。对于 React blog Sample 和其他 headless CMS Sample，决定安全的内容检索应始终出现在服务器端，这样客户端就不必了解有关安全配置设置的任何信息。因此，客户机的修改是为了将直接调用内容管理系统的内容重定向回应用产品的服务器端，然后该端负责检索和返回内容。

在加载 React 博客应用程序的主页时，可以看到一个简单的例子。在浏览器中加载页面时，服务器会发送一个预构建页面，其中包含所有文本内容。不过，所有图像都作为 URL 提供，供 Web 浏览器直接从 Oracle Content Management 加载。这需要 Web 浏览器拨打经过验证的电话，这是我们不希望的。解决方案是让代码拦截此类调用并将其重定向回为应用程序提供服务的 NodeJS 应用程序。

对于 React 博客应用程序，可以在 /src/server/server.js 中找到将直接调用重定向到内容管理系统到服务器端的代码。

首先，提供服务器端支持的 Express 服务器具有以下重定向代码：

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 应用程序添加预览支持是提高产品灵活性和价值的简单方法。这带来的某些好处包括：