Usar APIs de Visualização em Sites Sem Interface do Oracle Content Management

Introdução

Este tutorial descreve como adicionar suporte para a nova API REST para Visualização de Conteúdo nos aplicativos do Oracle Content Management que usam o Oracle Content SDK. Adicionar essa funcionalidade facilita que os criadores de conteúdo exibam seu novo conteúdo no mesmo aplicativo que é usado para renderizar seu trabalho de produção. Também abre a porta para usar a orquestração para lidar com versões de produção e protótipo do aplicativo com alterações mínimas no processo de criação.

Observe que, embora as versões anteriores do Content SDK tenham suportado um modo de visualização, ele foi baseado em outra interface REST do servidor que não foi otimizada para a tarefa. A alternância para a API mais recente não é difícil e ajudará a preparar seus aplicativos para o futuro.

As seções abaixo fornecem alguns detalhes sobre quais alterações foram feitas no Content SDK, descrevem como modificar um projeto de amostra, a amostra Reagir blog, para suportar a nova API de visualização e, finalmente, como obter e usar os parâmetros OAuth.

Este tutorial se concentra no React, mas você pode usar uma abordagem semelhante para outras tecnologias Web incluindo Angular, Gatsby, Next.js, Svelte e Vue.js.

Alterações no Oracle Content SDK

O Oracle Content SDK é uma biblioteca JavaScript que fornece wrappers convenientes em torno de chamadas de API REST do Oracle Content Management. Ele permite que os aplicativos procurem e recuperem ativos publicados e de visualização do servidor sem precisar fazer chamadas REST diretas. Nesse contexto, um ativo publicado é um conteúdo que foi tornado público enquanto um ativo de visualização é informações que ainda estão em desenvolvimento ou podem ser públicas no futuro. Um ativo publicado pode ser disponibilizado com ou sem necessidade de autenticação, enquanto um ativo de visualização sempre requer autenticação.

Ao usar o Content SDK, um aplicativo criará uma instância de um cliente de conteúdo, contentDeliveryClient (para conteúdo publicado) ou contentPreviewClient (para conteúdo de visualização). Nas versões anteriores do SDK do Oracle Content, havia apenas uma interface de visualização disponível. Este foi um wrapper que usou a API REST para Gerenciamento de Conteúdo do servidor para executar suas consultas. Embora isso funcionasse, não era uma solução ideal, pois essa API REST foi realmente projetada para outros fins. Por isso, uma segunda interface foi introduzida: a API REST para Visualização de Conteúdo. Isso agora pode ser selecionado como uma alternativa ao criar um cliente de visualização no Oracle Content SDK.

APIs Rest Usadas pelo Content SDK

Estas são as APIs REST que o Content SDK usa internamente:

Como configurar o aplicativo React Blog para usar a nova API de visualização

Usaremos a amostra Reagir blog como base para este tutorial. Observe que ele usa a biblioteca dotenv, que permite alterar os parâmetros de compilação usando variáveis de ambiente. Isso é valioso porque permite que o aplicativo seja alternado de publicado para o modo de visualização sem alterações no código interno.

  1. Primeiro, você precisará instalar e criar a amostra do blog React. Ao final desta etapa, você deve ter um aplicativo que possa ser criado executando npm run build e executado executando npm run start.

  2. Se o aplicativo estiver em execução, interrompa-o. Agora continuaremos com a configuração para usar o novo suporte para visualização:

    1. Abra o arquivo .env (localizado no diretório raiz do aplicativo).

    2. Adicione as linhas a seguir ao arquivo:

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

    A primeira entrada, PREVIEW, é usada para instruir o aplicativo a ser executado no modo de visualização.

    A segunda entrada, OPTIONS, especifica que queremos usar a API REST para a Visualização de Conteúdo para o modo de visualização. Como alternativa, a opção previewClientApi poderia ter sido definida como managementREST, mas que só deve ser usada para suporte legado.

Como definir os parâmetros OAuth para o modo de visualização

Para concluir a configuração do aplicativo de blog, precisamos configurar os parâmetros OAuth necessários para autenticação no servidor. Isso pode assumir uma das duas formas:

  1. Uma string de token do portador definida no arquivo .env da seguinte forma:

     AUTH=Bearer xxxxxx

    em que xxxxxx é o token OAuth do seu aplicativo.

    Essa opção é rápida e conveniente se você já tiver uma string de token OAuth válida que possa usar. No entanto, ele tem uma limitação de que o token só pode ser válido por um determinado período e o aplicativo começará a falhar quando o token tiver expirado. Isso nos leva à segunda opção, que tem uma configuração mais complexa, mas pode recuperar novos tokens à medida que os existentes expiram.

  2. Forneça um objeto no arquivo .env com o seguinte formato:

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

    O parâmetro IDP_URL é o URI do seu prover de identidade. Ele pode ser o Oracle Identity Cloud Service (IDCS) ou o Identity Access Management (IAM) quando usado com o Oracle Content Management.

A documentação do Oracle Content Management fornece detalhes sobre como configurar um aplicativo cliente e como obter esses valores de parâmetro.

Se AUTH e AUTH_PARAMS forem especificados, AUTH_PARAMS terá precedência.

Manuseio especial da segurança da pré-visualização na amostra do blog React

Dependendo do framework JavaScript usado e de como um aplicativo é escrito, ele pode executar a recuperação de conteúdo e a geração de páginas inteiramente no lado do servidor, totalmente no lado do cliente, ou uma combinação de ambos. No caso da amostra de blog React e de outras amostras CMS sem interface do usuário, foi decidido que a recuperação de conteúdo seguro deveria sempre acontecer no lado do servidor para que o cliente não precisasse saber nada sobre as configurações de segurança. Por esse motivo, os clientes foram modificados para redirecionar o que seria chamadas diretas para o sistema de gerenciamento de conteúdo de volta ao lado do servidor do aplicativo, que seria então responsável por recuperar e devolver o conteúdo.

Um exemplo simples disso pode ser visto ao carregar a página inicial do aplicativo React blog. Ao carregar a página em um navegador, o servidor envia uma página pré-criada preenchida com todo o conteúdo de texto. No entanto, todas as imagens são fornecidas como URLs a serem carregadas pelo Web browser diretamente do Oracle Content Management. Isso exigiria que o navegador da Web fizesse chamadas autenticadas, o que é algo que não queremos que ele faça. A solução é fazer com que o código intercepte essas chamadas e as redirecione de volta para o aplicativo NodeJS que está atendendo ao aplicativo.

No caso do aplicativo de blog React, o código que redireciona chamadas diretas para o sistema de gerenciamento de conteúdo para o lado do servidor pode ser encontrado em /src/server/server.js.

Primeiro, o servidor expresso que fornece o suporte do servidor tem o seguinte código de redirecionamento:

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

E isso, por sua vez, chama:

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

Conclusão

Adicionar suporte de visualização ao seu aplicativo Oracle Content Management é uma forma simples de aumentar a flexibilidade e o valor do seu produto. Alguns dos benefícios que isso traz incluem: