Implantar Aplicativos no Heroku com Orquestração de Experiência no Oracle Content Management

Introdução

Heroku é uma plataforma em nuvem que permite criar, entregar, monitorar e dimensionar aplicativos.

Implantar um aplicativo no Heroku é uma operação simples que requer apenas algumas etapas fáceis para aplicativos básicos, mas também pode suportar muitas configurações avançadas para cenários mais complexos.

Neste tutorial, implantaremos um aplicativo no Heroku de uma origem GitHub usando os recursos de orquestração da experiência no Oracle Content Management. O Oracle Content Management fornece uma maneira de conectar repositórios de conteúdo e canais de publicação a experiências sem supervisão desenvolvidas e gerenciadas fora do Oracle Content Management e para acionar automaticamente implantações com base nas alterações de conteúdo ou no status publicado.

O tutorial consiste nestas etapas:

1. Crie um aplicativo Heroku
2. Criar uma experiência com o Oracle Content Management
3. Configurar webhooks de saída
4. Configurar webhooks de entrada
5. Opcionalmente, adicione webhooks de saída/entrada para visualização de conteúdo
6. Analise os eventos

Pré-requisitos

Antes de continuar com este tutorial, recomendamos que você leia as seguintes informações primeiro:

• Conectando-se a experiências sem supervisão

Para seguir este tutorial, você precisará de:

• uma assinatura do Oracle Content Management
• uma conta do Oracle Content Management com a atribuição de Administrador de Conteúdo
• uma conta Heroku com atribuição de Membro ou Administrador
• uma conta do GitHub com código-fonte

Tarefa 1: Criar um Aplicativo Heroku

Se você ainda não tiver uma instância do Oracle Content Management, consulte Início Rápido para saber como se registrar no Oracle Cloud, provisionar uma instância do Oracle Content Management e configurar o Oracle Content Management como um CMS sem interface.

Se você ainda não tiver uma conta Heroku, precisará criar uma conta Heroku. A camada gratuita tem privilégios suficientes para implantar os aplicativos Heroku mais simples.

Se você ainda não tiver uma conta do GitHub, precisará criar uma conta do GitHub. Uma conta gratuita básica é tudo o que você precisa para colocar seu código-fonte. Seu código-fonte pode ser um repositório público ou privado.

Quando tudo isso estiver configurado, vamos conectar Heroku ao GitHub e implantar um aplicativo:

1. Faça login no Heroku e escolha Pessoal ou Equipe na parte superior esquerda, dependendo do seu caso de uso.

   

2. Clique em Novo no menu suspenso no canto superior direito e escolha Criar novo aplicativo.

   

3. Dê um nome ao seu aplicativo e clique em Criar aplicativo.

   

4. Abra a guia Implantar e conecte-se ao GitHub procurando seu repositório e selecione o que deseja implantar. Se você pretende implantar a versão mais recente do aplicativo, essa definição poderá ser deixada como 'principal' (que é o padrão). Se esta for a primeira vez que você estiver construindo um site deste provedor, você será solicitado a dar permissão Heroku para acessar seus repositórios. Siga os prompts para permitir isso.

   

   

5. Pela primeira vez, você precisará clicar em Implantar Ramificação na seção Implantação manual. Se quiser ativar implantações automáticas, ative-as na seção Implantações automáticas.

   

Observe o seguinte:

• Se você precisar definir quaisquer variáveis de ambiente antes de executar a compilação, certifique-se de fazer isso no arquivo .env.

• Certifique-se de que todos os arquivos necessários estejam dentro do repositório GitHub, prestando especial atenção aos arquivos .env e .gitignore.

• O arquivo package.json deve conter as entradas install, build e serve nos scripts dos aplicativos Node.js.

• Outras maneiras de se conectar com o Heroku não usando o GitHub são possíveis com a API do Heroku Connect. Mais detalhes podem ser encontrados no Centro de Desenvolvimento Heroku.

• Se sua implantação falhar, leia os logs de criação e aplicativo com atenção para verificar se há erros.

• Consulte o Centro de Desenvolvimento Heroku para obter mais informações sobre implantação do Node.js e solução de problemas de implantações do Node.js.

• Outros ambientes de runtime também têm suporte à linguagem em Heroku. Consulte o Centro de Desenvolvimento Heroku para obter informações adicionais.

Repositório de Vue de Amostra para implantação de Heroku

Esta seção é opcional, mas fornece um repositório de amostra de blog Vue que pode ser facilmente implantado no Heroku. O repositório pode ser encontrado no GitHub.

Um tutorial sobre como configurar a amostra do blog do Vue está disponível no Oracle Help Center, incluindo uma entrada de vídeo. Algumas configurações para esta amostra podem ser necessárias no sistema, como alterar o arquivo .env e carregar dados para o servidor, que é mostrado no tutorial.

Você pode bifurcar este repositório em sua conta indo para o repositório GitHub e clicando em "fork".

Forçar um repositório cria uma cópia do repositório. Aqui, a criação de um repositório permite que você experimente livremente as alterações sem afetar o projeto original, mas nenhuma alteração é necessária para poder implantar este aplicativo em Heroku.

Depois de fazer uma bifurcação deste projeto, você poderá criar sua primeira implantação de amostra, conforme descrito acima.

Corrigir possíveis erros de CORS para seu aplicativo Heroku

Esta seção ajudará você a corrigir quaisquer erros de CORS (Cross-Origin Resource Sharing) que possam existir no seu aplicativo. O CORS é um padrão que permite que um servidor relaxe a política de mesma origem, portanto, se a localização de onde o aplicativo está sendo servido e a origem do recurso que está sendo solicitado são diferentes, então a política de mesma origem do navegador da Web entra em vigor e o CORS é necessário para que a solicitação seja feita.

Podemos ativar isso na interface Web do Oracle Content Management indo para Sistema e Segurança. Adicione o URL do aplicativo Heroku às Origens CORS do Canal Frente e clique em Salvar.

Observação: Com base na política de mesma origem, dois URLs têm a mesma origem se e apenas se compartilharem exatamente o mesmo protocolo, domínio e porta. Isso significa que pode ser necessário adicionar URLs http e https nesta seção.

Tarefa 2: Criar uma Experiência do Oracle Content Management

Na tarefa anterior, conectamos o Heroku ao GitHub. Agora vamos criar um objeto de experiência do Oracle Content Management, que será conectado ao Heroku posteriormente.

Para criar um objeto de experiência no Oracle Content Management:

1. Efetue log-in na interface Web do Oracle Content Management como administrador.

2. Clique em Experiências no painel de navegação esquerdo e, em seguida, clique em Criar no canto superior direito.

   

3. Especifique as informações necessárias e clique em Criar quando terminar. Mais informações podem ser encontradas na documentação do Oracle Content Management.

   

Tarefa 3: Configurar Webhooks de Saída

Em seguida, vamos configurar o webhook de saída para o objeto de experiência recém-criado do Oracle Content Management. O webhook de saída destina-se a acionar automaticamente implantações do Oracle Content Management para Heroku com base em alterações de conteúdo ou status publicado.

Para configurar os webhooks de saída:

1. Efetue log-in na interface Web do Oracle Content Management como administrador.

2. Clique em Experiências no painel de navegação esquerdo.

3. Selecione a experiência que você deseja configurar e abra o painel Properties.

   

4. No painel Properties, abra a guia Outgoing.

   

5. Configure o nome do destino, método (GET ou POST), ponto final de URL e trigger da solicitação.

   • Nome do destino: Você pode atribuir ao destino qualquer nome desejado. O Oracle Content Management fornecerá um TARGET_IDENTIFIER exclusivo para este destino.

   • Método: Especifique GET ou POST na solicitação por meio do menu suspenso. Para Heroku, queremos fazer uma solicitação POST para acionar uma compilação.

   • Ponto final do URL: Este é o ponto final da API. Para Heroku, usaremos o ponto final https://api.heroku.com/apps/NAME-OF-YOUR-HEROKU-APP/builds, em que NAME-OF-YOUR-HEROKU-APP deve ser substituído de acordo.

   • Trigger de solicitação: está na guia Conteúdo, na qual você pode especificar um trigger com base em um evento específico. No exemplo abaixo, um build será acionado com base em uma alteração no repositório de ativos chamada OCEGettingStartedRepository, que representa o canal Blog no Oracle Content Management.

   

6. Configure os cabeçalhos. Você precisará de três cabeçalhos: Autorização, Aceitar e Tipo de Conteúdo. Estes estão documentados na documentação do Heroku.

   • Autorização: Este é um token de autorização que você precisa obter de Heroku. Somente usuários autorizados podem criar builds do Heroku, e esse token é necessário para a autenticação usar a API Heroku. Você pode exibir sua chave de API Heroku acessando Configurações da Conta > Chave de API > Revelar.

   • Aceitar: É isso que o cabeçalho Aceitar será: application/vnd.heroku+json; version=3. Observe que você deve usar a versão 3 da API de Criação Heroku para que isso funcione.

   • Content-Type: É isso que seu cabeçalho Content-Type será: application/json.

   

7. Configure o corpo. Você precisará de um blob de origem com um URL e uma versão opcional formatada como um objeto JSON, conforme mostrado abaixo. O blob de origem é o local onde seu código-fonte está localizado para a implantação. O objeto JSON do corpo deve ser:

   {"source_blob":{"url":"GITHUB_API_ENDPOINT_FOR_TARBALL", "version":"OPTIONAL_TARGET_IDENTIFIER"}}

   url

   O URL a ser usado é o local onde um arquivo compactado tar do código-fonte do build foi baixado. Conseguiremos isso por meio da API do GitHub.

   Observe que há uma diferença na URL para repositórios públicos e privados no GitHub. Consulte a documentação do Heroku para obter detalhes.

   Para repositórios públicos, seu URL deve ser:

   https://api.github.com/repos/<username>/<repo name>/tarball/<branch>

   Para repositórios privados, seu URL deve ser:

   https://user:[e-mail]/repos/<username>/<repo name>/tarball/<branch>

   O <username> é seu nome de usuário do GitHub, o <repo name> é o slug do seu repositório do GitHub e <branch> é o nome da sua ramificação (geralmente 'principal' ou 'mestre'). Um exemplo de repositório público de amostra é mostrado abaixo.

   Para repositórios privados, você precisa alterar a seção user:token do URL blob de origem do repositório privado. A parte user pode ser substituída pelo mesmo nome de usuário de antes, e token precisa ser substituído por um Token de Acesso Pessoal do GitHub com escopo apropriado. Para gerar esse token, siga as etapas descritas na documentação do GitHub. Preste atenção particular à data de expiração deste token (normalmente não deseja defini-lo para expirar), e você precisa dar a este token "repo" acesso somente, que dá controle total sobre repositórios privados.

   versão

   O parâmetro de versão não é obrigatório e não é usado durante o download e a criação do código-fonte. É apenas um trecho de metadados que você pode usar como opção para rastrear qual versão do código-fonte foi introduzida na criação do slug.

   No nosso caso, adicionaremos "{{TARGET_IDENTIFIER}}" como parâmetro de versão. O Oracle Content Management colocará TARGET_IDENTIFIER como o ID visto ao lado do nome de destino no corpo da solicitação. Quando este for enviado para Heroku, ele será enviado de volta pelo webhook de entrada depois que for configurado. Nesta resposta de Heroku sobre a criação, o Oracle Content Management receberá a carga útil e avaliará se esse ID de destino existe. Se o fizer, o payload será associado ao destino de saída do Oracle Content Management; caso contrário, será considerado 'Desconhecido'. Mais informações sobre IDs de destino podem ser encontradas na documentação do Oracle Content Management.

   

8. Clique em Aplicar no canto superior direito para salvar sua configuração.

9. Opcionalmente, clique em Testar ao lado do ponto final da API para testar um trigger desse build como se o conteúdo ou o status publicado mudasse no canal selecionado.

Observação: Detalhes adicionais sobre a configuração do webhook de saída no Oracle Content Management podem ser encontrados na documentação do Oracle Content Management.

Tarefa 4: Configurar Webhooks de Entrada

Em seguida, vamos configurar o webhook de entrada do Heroku para o Oracle Content Management para o objeto de experiência recém-criado. O webhook de entrada destina-se a fornecer informações sobre a criação e seu status de volta ao Oracle Content Management sem sair do Oracle Content Management. Os resultados podem ser exibidos na guia Eventos, onde mais informações podem ser encontradas ao analisar os eventos.

Para configurar os webhooks de entrada:

1. Efetue log-in na interface Web do Oracle Content Management como administrador.

2. Clique em Experiências no painel de navegação esquerdo.

3. Selecione a experiência que você deseja configurar e abra o painel Properties.

   

4. No painel Properties, abra a guia Incoming. Copie o URL do webhook, que colocaremos em Heroku.

   

5. Faça login novamente em Heroku e encontre seu aplicativo. No canto superior direito, clique em Mais e, em seguida, em Exibir webhooks.

   

6. Clique em Criar Webhook no centro da tela.

   

7. Na caixa de diálogo Novo Webhook, forneça as informações do novo webhook. Qualquer nome está correto, o URL do payload deve ser o copiado do Oracle Content Management e nenhum segredo é necessário. Para tipos de evento, verifique se apenas 'api:build' está selecionado.

   

8. Clique em Adicionar Webhook quando tiver concluído.

Tarefa 5 (Opcional): Adicionar Webhooks de Entrada e Saída Adicionais para Visualização de Conteúdo

As APIs REST estão disponíveis no Oracle Content Management para entrega e gerenciamento de conteúdo, bem como para conversas, documentos e usuários e grupos. Para a integração com Heroku, pode ser útil ter duas implantações separadas em diferentes aplicativos Heroku usando a mesma experiência para visualização de conteúdo e entrega de conteúdo para que alterações não publicadas em um ativo possam ser visualizadas em um aplicativo sem afetar a criação de entrega de produção. Nesta seção opcional, analisaremos como usar um segundo destino na experiência para acionar implantações de visualização separadamente das implantações de produção.

O primeiro passo é criar um total de dois aplicativos Heroku separados, onde um aplicativo Heroku estará usando o conteúdo de visualização e o outro o conteúdo de entrega. Você pode criar um aplicativo Heroku seguindo as instruções na tarefa 1.

Uma vez configurado, você precisará configurar os dois destinos de saída. Você pode adicionar um segundo destino clicando em Adicionar Destino na parte inferior. Siga as etapas na tarefa 3 para criar um webhook de saída. Observe que deve haver duas diferenças principais entre os dois webhooks de saída:

1. A API de entrega de conteúdo deve ser acionada com base em uma publicação no canal de conteúdo e a API de visualização de conteúdo deve ser acionada com base em uma alteração no repositório de conteúdo.

2. O corpo do webhook de saída deve estar vinculado ao código apropriado que usa a API de entrega de conteúdo ou a API de visualização de conteúdo. Isso exigirá seu código de visualização e código de entrega hospedados em dois repositórios GitHub separados.

   

Observação: Para obter detalhes adicionais sobre a configuração da API de visualização no Oracle Content Management, consulte Usar APIs de Visualização em Sites do Oracle Content Management sem Interface do Usuário.

A última etapa é configurar os webhooks de entrada de cada aplicativo Heroku, que pode ser feito seguindo as etapas da tarefa 4 para cada um dos aplicativos. Ambos os aplicativos Heroku compartilharão o mesmo URL do webhook de entrada fornecido pelo Oracle Content Management.

Uma questão importante a observar é que Heroku limita o número de compilações simultâneas por conta. Heroku só permite que contas verificadas executem compilações de vários aplicativos em uma conta simultaneamente, o que requer pagamento adicional para Heroku. Se você estiver usando a versão gratuita do Heroku integrada ao recurso de orquestração de experiência do Oracle Content Management em dois aplicativos Heroku na mesma conta, talvez seja necessário aguardar a conclusão dos builds antes de executar outra alteração em um repositório de ativos ou publicar em um canal de conteúdo.

Tarefa 6: Analisar os Eventos

Por fim, podemos testar a orquestração de experiência completa no Oracle Content Management sem precisar sair da interface Web do Oracle Content Management. Com base em alterações no conteúdo ou no status de publicação ou simplesmente clicando no botão Testar na guia Saída, as seguintes etapas serão executadas:

1. O Oracle Content Management aciona um build chamando a API Heroku Build usando o cabeçalho e o corpo especificados com a solicitação POST no ponto final do URL.

2. Heroku recebe a solicitação para executar uma criação, que usa o código-fonte (que extrai o conteúdo do Oracle Content Management).

3. O Heroku envia uma resposta de volta ao Oracle Content Management quando a compilação é iniciada, fornecendo um status pendente e alguns outros metadados.

4. Quando o build terminar, Heroku emitirá outra resposta ao Oracle Content Management sobre a falha ou sucesso do build com metadados adicionais.

Todos esses eventos são exibidos na guia Events do painel Properties. Veja a seguir uma sequência de amostra de eventos numéricos de 1, 2 e 3, em ordem de ocorrência:

Como mostrado, o primeiro evento (rotulado como 1) é o acionador do Oracle Content Management para Heroku para iniciar uma compilação. O segundo evento (identificado como 2) é o webhook de entrada de volta de Heroku informando ao Oracle Content Management que a compilação foi iniciada. O evento final (rotulado como 3) é o evento de construção bem-sucedido, também do webhook recebido de Heroku para o Oracle Content Management. Cada um desses eventos pode ser analisado em detalhes clicando-se neles na guia Eventos. Observe como todos os eventos têm a mesma tag chamada 'Heroku Endpoint API Build'. O primeiro evento (denominado 1) é chamado de isso, já que esse era o nome que nós damos na guia Saída. O segundo e o terceiro eventos (identificados 2 e 3, respectivamente) são marcados da mesma forma, uma vez que adicionamos um token {{TARGET_IDENTIFIER}} às solicitações associadas com destinos.

O conteúdo exibido abaixo de cada evento na guia Eventos vem das configurações da guia Analisar. A guia Analisar permite extrair informações de um payload de resposta recebido e exibi-las na guia Eventos para fornecer informações importantes aos editores de conteúdo e colaboradores, como quando seu conteúdo é salvo, publicado ou está em operação. Informações adicionais sobre a guia Analisar podem ser encontradas na documentação do Oracle Content Management.

Para os eventos exibidos acima, o seguinte foi especificado na guia Analisar:

A Orquestração da Experiência Completa

Esta seção é opcional, mas demonstra todo o processo e o benefício de usar os recursos de orquestração de experiência do Oracle Content Management. Nesta seção, veremos um URL de experiência na produção, faremos uma alteração no conteúdo e depois o publicaremos e, finalmente, veremos o conteúdo publicado em uma implantação do Heroku sem afetar o URL de experiência ou deixar o Oracle Content Management.

Primeiro precisamos nos certificar de que queremos ver as alterações de visualização com base no status de publicação de ativos no OCEGettingStartedRepository, que pode ser definido na guia Saída da experiência.

Primeiro, aqui está o site do URL da experiência, que pode ser definido na seção Propriedades do site para o URL da experiência. Este é o estado ativo atual do seu site do qual você deseja ver visualizações sem afetar esta produção.

Agora, vamos criar uma alteração no conteúdo e publicar esse conteúdo no canal correspondente correto. Para esta seção, vamos atualizar o ativo para a página inicial do blog chamado 'Como fazer' e adicionar as palavras 'Fazer café' a ele.

Procure o ativo "Como fazer para" na barra de pesquisa e clique no ícone de edição.

Agora, vamos mudar o conteúdo adicionando as palavras "Make Coffee" e salvá-lo no canto superior direito.

Vamos publicar esse conteúdo no canal correto, que deve acionar a compilação adequada para a visualização.

Podemos verificar o build acionado acessando o objeto de orquestração da experiência e exibindo a guia Eventos quando analisar os eventos.

Uma vez que o build é concluído e bem-sucedido, podemos verificar se o URL de visualização, que chamamos de 'Heroku Endpoint API Build', tem essas atualizações com as palavras 'Make Coffee' após 'How To'. E podemos ver que a URL da experiência anterior ainda é o mesmo site.

Conclusão e próximas etapas

Neste tutorial, implantamos um aplicativo no Heroku de uma origem GitHub usando os recursos de orquestração da experiência no Oracle Content Management. Primeiramente, criamos um aplicativo Heroku e implantamos uma origem GitHub, como o repositório de blogs Vue de amostra, que é executado usando o Node.js. Em seguida, criamos uma experiência no Oracle Content Management e configuramos os webhooks de saída e os webhooks de entrada. Por fim, o processo de orquestração de experiência agora é configurado de forma que, nas alterações de conteúdo ou status de publicação, ou simplesmente clicando no botão Testar na guia Saída, o Oracle Content Management acionará uma compilação chamando a API de Criação Heroku usando o cabeçalho e o corpo especificados com a solicitação POST no ponto final do URL. Os eventos podem ser analisados diretamente no Oracle Content Management na guia Eventos e também demonstramos o processo de orquestração de experiência completa.

As próximas etapas para gerenciar o processo de orquestração da experiência são:

1. Veja as experiências conectadas sem supervisão

2. Compartilhar o objeto experience

Com isso, agora podemos conectar repositórios de conteúdo e canais de publicação a experiências sem supervisão implantadas no Heroku que acionam automaticamente implantações com base em alterações de conteúdo ou status publicado. Os provedores de conteúdo podem aproveitar as vantagens do gerenciamento de ativos do repositório, como ferramentas avançadas para organizar, recuperar, traduzir, colaborar, aprovar e publicar conteúdo. Em seguida, sem sair do Oracle Content Management, eles podem visualizar seus aplicativos sem interface no contexto e com conteúdo. Os desenvolvedores da experiência podem trabalhar com ferramentas que possuem e configurar experiências headless para criar automaticamente com base em alterações no conteúdo em repositórios associados ou no status de publicação do conteúdo em canais de publicação associados para impulsionar a integração contínua/implantação contínua (CI/CD).

---

Título e Informações de Copyright

Implantar Aplicativos no Heroku com Orquestração de Experiência no Oracle Content Management

F52229-02

Junho de 2022

Copyright © 2021, 2022, Oracle and/or its affiliates.

Autor Principal: Oracle Corporation