Distribuisci le applicazioni su Heroku con Experience Orchestration in Oracle Content Management

Introduzione

Heroku è una piattaforma cloud che ti consente di creare, distribuire, monitorare e scalare le applicazioni.

La distribuzione di un'applicazione su Heroku è un'operazione semplice che richiede solo pochi semplici passi per le applicazioni di base, ma può anche supportare molte impostazioni avanzate per scenari più complessi.

In questa esercitazione verrà distribuita un'applicazione su Heroku da un'origine GitHub utilizzando le funzioni di orchestrazione dell'esperienza disponibili in Oracle Content Management. Oracle Content Management consente di connettere repository di contenuti e canali di pubblicazione a esperienze headless sviluppate e gestite al di fuori di Oracle Content Management e di attivare automaticamente le distribuzioni in base alle modifiche ai contenuti o allo stato pubblicato.

L'esercitazione è composta dai seguenti passaggi:

1. Creare un'applicazione Heroku
2. Creare un'esperienza di Oracle Content Management
3. Configurare i webhook in uscita
4. Configurare i webhook in entrata
5. Facoltativamente, aggiungere ulteriori webhook in uscita/in entrata per l'anteprima del contenuto
6. Analizzare gli eventi

Prerequisiti

Prima di procedere con questa esercitazione, si consiglia di leggere prima le seguenti informazioni:

• Connettersi alle esperienze senza problemi

Per seguire questa esercitazione, è necessario:

• una sottoscrizione a Oracle Content Management
• un account Oracle Content Management con il ruolo Amministratore contenuto;
• un account Heroku con ruolo Membro o Amministratore
• un account GitHub con codice sorgente

Task 1: Creare un'applicazione Heroku

Se non si dispone già di un'istanza di Oracle Content Management, vedere Avvio rapido per informazioni su come effettuare la registrazione a Oracle Cloud, eseguire il provisioning di un'istanza di Oracle Content Management e configurare Oracle Content Management come CMS headless.

Se non si dispone già di un account Heroku, sarà necessario creare un account Heroku. Il livello gratuito dispone di privilegi sufficienti per distribuire le applicazioni Heroku più semplici.

Se non disponi ancora di un account GitHub, dovrai creare un account GitHub. Un account gratuito di base è tutto ciò in cui è necessario inserire il codice sorgente. Il codice sorgente può essere un repository pubblico o privato.

Una volta impostati tutti questi elementi, connettiamo Heroku a GitHub e distribuiamo un'applicazione:

1. Eseguire il login a Heroku e scegliere Personale o Team in alto a sinistra in base al caso d'uso.

   

2. Fai clic su Nuovo nel menu a discesa in alto a destra e scegli Crea nuova applicazione.

   

3. Assegna un nome all'app e fai clic su Crea app.

   

4. Aprire la scheda Distribuisci e connettersi a GitHub cercando il repository e selezionando quello che si desidera distribuire. Se si intende distribuire la versione più recente dell'applicazione, questa impostazione può essere lasciata come 'principale' (impostazione predefinita). Se questa è la prima volta che si crea un sito da questo provider, verrà richiesto di fornire l'autorizzazione Heroku per accedere ai repository. Seguire i prompt per consentire questa operazione.

   

   

5. Per la prima volta, sarà necessario fare clic su Distribuisci diramazione nella sezione Distribuzione manuale. Se si desidera abilitare le distribuzioni automatiche, abilitarle nella sezione Distribuzioni automatiche.

   

Tenere presente:

• Se è necessario impostare qualsiasi variabile di ambiente prima di eseguire la build, assicurarsi di farlo nel file .env.

• Assicurarsi che tutti i file necessari si trovino all'interno del repository GitHub, prestando particolare attenzione ai file .env e .gitignore.

• Il file package.json deve contenere voci install, build e serve negli script per le applicazioni Node.js.

• Altri modi per connettersi con Heroku non utilizzando GitHub sono possibili con l'API Heroku Connect. Puoi trovare ulteriori dettagli in Heroku Dev Center.

• Se la distribuzione non riesce, leggere attentamente i log della build e dell'applicazione per rilevare eventuali errori.

• Consulta il Dev Center di Heroku per ulteriori informazioni sulla distribuzione di Node.js e sulla risoluzione dei problemi delle distribuzioni Node.js.

• Anche gli altri ambienti runtime dispongono del supporto linguistico in Heroku. Per ulteriori informazioni, consulta Heroku Dev Center.

Esempio di repository Vue per la distribuzione Heroku

Questa sezione è facoltativa, ma fornisce un esempio di repository di esempio di blog Vue che può essere facilmente distribuito su Heroku. Il repository è disponibile su GitHub.

Un'esercitazione su come impostare l'esempio di blog Vue è disponibile in Oracle Help Center, inclusa una procedura guidata video. Alcune impostazioni per questo esempio potrebbero essere necessarie sul sistema, ad esempio modificare il file .env e caricare i dati sul server, mostrato nell'esercitazione.

Puoi eseguire la fork del repository sul tuo account andando sul repository GitHub e facendo clic su "fork".

Se si collega un repository, viene creata una copia del repository. Qui, la creazione di un repository consente di sperimentare liberamente le modifiche senza influenzare il progetto originale, ma non sono necessarie modifiche per poter distribuire questa applicazione a Heroku.

Una volta eseguito il fork del progetto, è possibile proseguire e creare la prima distribuzione di esempio, come descritto in precedenza.

Risolvi potenziali errori CORS per la tua app Heroku

Questa sezione consente di correggere eventuali errori CORS (Cross-Origin Resource Sharing) presenti nell'applicazione. CORS è uno standard che consente a un server di rilassare il criterio di stessa origine, quindi se la posizione in cui viene servita l'applicazione e l'origine della risorsa richiesta sono diverse, il criterio di stessa origine del browser Web diventa effettivo e CORS è richiesto per la richiesta.

Per abilitare questa funzione nell'interfaccia Web di Oracle Content Management, andare al sistema, quindi alla sicurezza. Aggiungere l'URL dell'applicazione Heroku a Origine CORS canale frontale, quindi fare clic su Salva.

Nota: in base al criterio di stessa origine, due URL hanno la stessa origine se e solo se condividono lo stesso protocollo, dominio e porta. In questa sezione potrebbe essere necessario aggiungere URL sia http che https.

Task 2: Creare un'esperienza di Oracle Content Management

Nell'attività precedente, abbiamo collegato Heroku a GitHub. Ora creeremo un oggetto esperienza di Oracle Content Management, che verrà collegato a Heroku in un secondo momento.

Per creare un oggetto esperienza in Oracle Content Management, procedere come segue.

1. Eseguire il login all'interfaccia Web di Oracle Content Management come amministratore.

2. Fare clic su Esperienze nel pannello di navigazione sinistro, quindi su Crea in alto a destra.

   

3. Immettere le informazioni richieste e fare clic su Crea al termine. Per ulteriori informazioni, consultare la documentazione di Oracle Content Management.

   

Task 3: Configura webhook in uscita

Verrà quindi configurato il webhook in uscita per l'oggetto esperienza Oracle Content Management appena creato. Il webhook in uscita ha lo scopo di attivare automaticamente le distribuzioni da Oracle Content Management a Heroku in base alle modifiche dei contenuti o allo stato pubblicato.

Per configurare i webhook in uscita:

1. Eseguire il login all'interfaccia Web di Oracle Content Management come amministratore.

2. Fare clic su Experiences nel pannello di navigazione di sinistra.

3. Selezionare l'esperienza che si desidera configurare, quindi aprire il pannello Proprietà.

   

4. Nel pannello Proprietà aprire la scheda In uscita.

   

5. Configurare il nome per la destinazione, il metodo (GET o POST), l'endpoint URL e il trigger per la richiesta.

   • Nome destinazione: è possibile assegnare il nome desiderato alla destinazione. Oracle Content Management fornirà un TARGET_IDENTIFIER univoco per questa destinazione.

   • Metodo: specificare GET o POST nella richiesta tramite il menu a discesa. Per Heroku, vogliamo fare una richiesta POST per attivare una build.

   • endpoint URL: questo è l'endpoint API. Per Heroku, useremo l'endpoint https://api.heroku.com/apps/NAME-OF-YOUR-HEROKU-APP/builds, dove NAME-OF-YOUR-HEROKU-APP dovrebbe essere sostituito di conseguenza.

   • Attivazione richiesta: si trova nella scheda Contenuto, in cui è possibile specificare un trigger basato su un evento specifico. Nell'esempio seguente, una build verrà attivata in base a una modifica nel repository degli asset denominato OCEGettingStartedRepository, che rappresenta il canale Blog in Oracle Content Management.

   

6. Configurare le intestazioni. Sono necessarie tre intestazioni: Autorizzazione, Accetta e Tipo di contenuto. Tali funzionalità sono documentate nella documentazione di Heroku.

   • Autorizzazione: questo è un token di autorizzazione che è necessario ottenere da Heroku. Solo gli utenti autorizzati possono creare build da Heroku. Questo token è necessario per l'autenticazione per utilizzare l'API Heroku. Puoi visualizzare la tua chiave API Heroku andando su Impostazioni account > Chiave API > Rivela.

   • Accetta: l'intestazione Accetta sarà: application/vnd.heroku+json; version=3. Per funzionare, è necessario utilizzare la versione 3 dell'API Heroku Build.

   • Content-Type: si tratta dell'intestazione Content-Type: application/json.

   

7. Configurare il corpo. È necessario un blob di origine con un URL e una versione facoltativa formattata come oggetto JSON come mostrato di seguito. Il blob di origine è il punto in cui si trova il codice sorgente per la distribuzione. L'oggetto JSON per il corpo deve essere:

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

   URL

   L'URL da utilizzare è la posizione in cui è stato scaricato un archivio tar compresso del codice di origine per la build. Possiamo utilizzare l'API GitHub.

   Ricorda che esiste una differenza nell'URL per i repository pubblici e privati su GitHub. Per ulteriori dettagli, consultare la documentazione di Heroku.

   Per i repository pubblici, l'URL dovrebbe essere:

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

   Per i repository privati, l'URL dovrebbe essere:

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

   <username> è il nome utente GitHub, <repo name> è lo slug del repository GitHub e <branch> è il nome della diramazione (di solito 'principale' o 'master'. Un esempio di repository pubblico di esempio è riportato di seguito.

   Per i repository privati, è necessario modificare la sezione user:token per l'URL blob di origine del repository privato. La parte user può essere sostituita con lo stesso nome utente precedente e token deve essere sostituito con un token di accesso personale GitHub con l'ambito appropriato. Per generare questo token, seguire i passaggi descritti nella documentazione su GitHub. Prestare particolare attenzione alla data di scadenza di questo token (in genere non si desidera impostarlo come scaduto) e assegnare solo questo token come accesso "repo", che fornisce il controllo completo sui repository privati.

   versione

   Il parametro della versione non è obbligatorio e non viene utilizzato durante il download e la creazione del codice sorgente. È solo una parte di metadati che è possibile utilizzare facoltativamente per tenere traccia della versione del codice sorgente che è stata utilizzata per creare lo slug.

   Per il nostro caso, aggiungeremo "{{TARGET_IDENTIFIER}}" come parametro della versione. Oracle Content Management inserirà TARGET_IDENTIFIER come ID visualizzato accanto al nome della destinazione nel corpo della richiesta. Quando viene inviato a Heroku, verrà inviato di nuovo tramite il webhook in entrata dopo che sarà stato configurato. In questa risposta di Heroku sulla build, Oracle Content Management riceverà il payload e valuterà se tale ID destinazione esiste. In caso contrario, il payload viene associato alla destinazione in uscita da Oracle Content Management, altrimenti viene considerato "Sconosciuto". Per ulteriori informazioni sugli ID destinazione, consultare la documentazione di Oracle Content Management.

   

8. Fare clic su Applica in alto a destra per salvare la configurazione.

9. Facoltativamente, fare clic su Test accanto all'endpoint API per eseguire il test di un trigger della build come se il contenuto o lo stato pubblicato cambia nel canale selezionato.

Nota: ulteriori dettagli sulla configurazione del webhook in uscita in Oracle Content Management sono disponibili nella documentazione di Oracle Content Management.

Task 4: Configura webhook in entrata

Successivamente, configureremo il webhook in entrata da Heroku a Oracle Content Management per l'oggetto esperienza appena creato. Il webhook in entrata ha lo scopo di fornire informazioni sulla build e sul relativo stato a Oracle Content Management senza lasciare Oracle Content Management. I risultati possono essere visualizzati nella scheda Eventi, dove è possibile reperire ulteriori informazioni durante l'analisi degli eventi.

Per configurare i webhook in entrata:

1. Eseguire il login all'interfaccia Web di Oracle Content Management come amministratore.

2. Fare clic su Experiences nel pannello di navigazione di sinistra.

3. Selezionare l'esperienza che si desidera configurare, quindi aprire il pannello Proprietà.

   

4. Nel pannello Proprietà aprire la scheda In entrata. Copia l'URL del webhook, che metteremo in Heroku.

   

5. Accedi a Heroku e trova la tua applicazione. In alto a destra fare clic su Altro, quindi su Visualizza webhook.

   

6. Fare clic su Crea webhook al centro della schermata.

   

7. Nella finestra di dialogo Nuovo webhook, fornire le informazioni per il nuovo webhook. Qualsiasi nome è valido, l'URL del payload deve essere quello copiato da Oracle Content Management e non è necessario alcun segreto. Per i tipi di evento, assicurarsi che sia selezionato solo 'api:build'.

   

8. Al termine, fare clic su Aggiungi webhook.

Task 5 (facoltativo): aggiungere ulteriori webhook in uscita e in entrata per l'anteprima del contenuto

Le API REST sono disponibili in Oracle Content Management per la distribuzione e la gestione dei contenuti, nonché per conversazioni, documenti, utenti e gruppi. Per l'integrazione con Heroku, potrebbe essere utile disporre di due distribuzioni separate su diverse applicazioni Heroku utilizzando la stessa esperienza per l'anteprima dei contenuti e la consegna dei contenuti in modo che le modifiche non pubblicate di un asset possano essere visualizzate in anteprima in un'applicazione senza influire sulla creazione di consegne di produzione. In questa sezione facoltativa verrà illustrato come utilizzare una seconda destinazione nell'esperienza per attivare le distribuzioni in anteprima separatamente dalle distribuzioni in produzione.

Il primo passo è creare un totale di due app Heroku separate, dove un'app Heroku utilizzerà il contenuto di anteprima e l'altro il contenuto di consegna. È possibile creare un'applicazione Heroku seguendo le istruzioni del task 1.

Dopo aver impostato questa opzione, sarà necessario configurare entrambe le destinazioni in uscita. È possibile aggiungere una seconda destinazione facendo clic su Aggiungi destinazione nella parte inferiore. Seguire la procedura descritta al task 3 per creare un webhook in uscita. Si noti che ci dovrebbero essere due differenze principali tra entrambi i webhook in uscita:

1. L'API di distribuzione del contenuto deve essere attivata in base a una pubblicazione nel canale del contenuto e l'API di anteprima del contenuto deve essere attivata in base a una modifica nel repository del contenuto.

2. Il corpo del webhook in uscita deve essere collegato al codice appropriato che utilizza l'API di distribuzione del contenuto o l'API di anteprima del contenuto. Questo richiederà il codice di anteprima e il codice di distribuzione gestiti in hosting su due repository GitHub separate.

   

Nota: per ulteriori dettagli sulla configurazione dell'API di anteprima in Oracle Content Management, vedere Usa API di anteprima nei siti Oracle Content Management headless.

L'ultimo passo è configurare i webhook in entrata da ogni applicazione Heroku, che è possibile eseguire seguendo i passi riportati nella task 4 per ciascuna applicazione. Entrambe le applicazioni Heroku condivideranno lo stesso URL webhook in entrata fornito da Oracle Content Management.

Un problema importante da notare è che Heroku limita il numero di build concorrenti per conto. Heroku consente solo agli account verificati di eseguire contemporaneamente build di più applicazioni su un account, che richiede un pagamento aggiuntivo a Heroku. Se si utilizza la versione gratuita di Heroku integrata con la funzione di orchestrazione dell'esperienza di Oracle Content Management su due applicazioni Heroku con lo stesso account, potrebbe essere necessario attendere il completamento delle build prima di eseguire un'altra modifica in un repository di asset o pubblicare in un canale di contenuto.

Task 6: Analizzare gli eventi

Infine, è possibile eseguire il test dell'orchestrazione completa dell'esperienza in Oracle Content Management senza dover uscire dall'interfaccia Web di Oracle Content Management. In base alle modifiche apportate al contenuto o allo stato di pubblicazione oppure facendo semplicemente clic sul pulsante Test nella scheda In uscita, verranno eseguite le seguenti operazioni:

1. Oracle Content Management attiva una build richiamando l'API Heroku Build utilizzando l'intestazione e il corpo specificati con la richiesta POST sull'endpoint URL.

2. Heroku riceve la richiesta di eseguire una build, che utilizza il codice sorgente (che estrae il contenuto da Oracle Content Management).

3. Heroku effettua il push di una risposta a Oracle Content Management all'avvio della build, fornendo uno stato in sospeso e altri metadati.

4. Al termine della build, Heroku invia a Oracle Content Management un'altra risposta in merito all'errore o al successo della build con metadati aggiuntivi.

Tutti questi eventi vengono visualizzati nella scheda Eventi del pannello Proprietà. Di seguito è riportata una sequenza di esempi di eventi numerati 1, 2 e 3, in ordine di occorrenza:

Come mostrato, il primo evento (con etichetta 1) è il trigger da Oracle Content Management a Heroku per avviare una build. Il secondo evento (con etichetta 2) è il webhook in arrivo di Heroku che dice a Oracle Content Management che la build è stata avviata. L'evento finale (con etichetta 3) è l'evento di creazione riuscito, anche dal webhook in entrata di Heroku a Oracle Content Management. Ognuno di questi eventi può essere analizzato in dettaglio facendo clic su di essi nella scheda Eventi. Notare come tutti gli eventi hanno lo stesso tag denominato 'Build di API dell'endpoint Heroku'. Il primo evento (con etichetta 1) è chiamato che, dato che era il nome che abbiamo dato nella scheda In uscita. Il secondo e il terzo evento (rispettivamente 2 e 3) sono contrassegnati come uguali poiché è stato aggiunto un token {{TARGET_IDENTIFIER}} alle richieste associate alle destinazioni.

Il contenuto visualizzato sotto ogni evento della scheda Eventi proviene dalle impostazioni della scheda Analizza. La scheda Analizza consente di estrarre le informazioni da un payload di risposta in entrata e di visualizzarle nella scheda Eventi per fornire informazioni importanti per gli editor di contenuto e i collaboratori, ad esempio quando il contenuto viene salvato, pubblicato o attivo. Ulteriori informazioni sulla scheda Analizza sono disponibili nella documentazione di Oracle Content Management.

Per gli eventi sopra visualizzati, nella scheda Analizza è stato specificato quanto segue:

Orchestrazione completa dell'esperienza

Questa sezione è facoltativa ma illustra l'intero processo e il vantaggio di utilizzare le funzioni di orchestrazione dell'esperienza di Oracle Content Management. In questa sezione verrà visualizzato un URL di esperienza in produzione, verrà apportata una modifica al contenuto, quindi verrà pubblicato e infine verrà visualizzato il contenuto pubblicato in una distribuzione Heroku senza influenzare l'URL di esperienza o lasciare Oracle Content Management.

È innanzitutto necessario assicurarsi di voler visualizzare le modifiche all'anteprima in base allo stato di pubblicazione degli asset in OCEGettingStartedRepository, che può essere impostato nella scheda In uscita dell'esperienza.

In primo luogo, ecco il sito URL esperienza, che può essere impostato nella sezione Proprietà del sito per l'URL esperienza. Questo è lo stato attivo corrente del sito di cui si desidera visualizzare le anteprime senza influenzare questa produzione.

Ora, creeremo una modifica del contenuto e pubblicheremo tale contenuto nel canale corrispondente corretto. Per questa sezione, aggiorniamo l'asset per la home page del blog chiamato "How To" e aggiungiamo le parole "Make Coffee" ad esso.

Cercare l'asset 'Come fare' nella barra di ricerca e fare clic sull'icona di modifica.

Ora, cambiamo il contenuto aggiungendo le parole "Fai caffè" e salvalo in alto a destra.

Pubblichiamo questo contenuto nel canale corretto, che dovrebbe attivare la build corretta per l'anteprima.

È possibile verificare la build attivata inserendo l'oggetto di orchestrazione dell'esperienza e visualizzando la scheda Eventi durante l'analisi degli eventi.

Una volta completata e riuscita la build, possiamo verificare che l'URL di anteprima, che abbiamo chiamato "Heroku Endpoint API Build", abbia questi aggiornamenti con le parole "Make Coffee" dopo "How to". E vediamo che l'URL dell'esperienza precedente è ancora lo stesso sito.

Conclusione e fasi successive

In questa esercitazione è stata distribuita un'applicazione su Heroku da un'origine GitHub utilizzando le funzioni di orchestrazione dell'esperienza disponibili in Oracle Content Management. Abbiamo creato un'applicazione Heroku e implementato un'origine GitHub, come il repository del blog Vue di esempio, che viene eseguito con Node.js. Abbiamo quindi creato un'esperienza di Oracle Content Management e configurato i Webhook in uscita e i Webhook in entrata. Infine, il processo di orchestrazione dell'esperienza è ora impostato in modo che, in caso di modifiche al contenuto o allo stato di pubblicazione, oppure facendo semplicemente clic sul pulsante Test nella scheda In uscita, Oracle Content Management attiverà una build richiamando l'API Build Heroku utilizzando l'intestazione e il corpo specificati con la richiesta POST sull'endpoint URL. Gli eventi possono essere analizzati direttamente in Oracle Content Management nella scheda Eventi e, inoltre, è stato dimostrato il processo completo di orchestrazione dell'esperienza.

I passi successivi per la gestione del processo di orchestrazione dell'esperienza sono i seguenti:

1. Visualizza le esperienze headless connesse

2. Condividi l'oggetto esperienza

Con questo, ora possiamo connettere repository di contenuti e canali di pubblicazione a esperienze headless distribuite su Heroku che attivano automaticamente le distribuzioni in base alle modifiche di contenuto o allo stato pubblicato. I provider di contenuti possono sfruttare i vantaggi della gestione degli asset del repository, ad esempio strumenti efficaci per diverse operazioni relative ai contenuti: organizzazione, recupero, traduzione, collaborazione, approvazione e pubblicazione. Successivamente, senza lasciare Oracle Content Management, possono visualizzare in anteprima le applicazioni headless in base al contesto e ai contenuti. Gli sviluppatori di esperienze possono lavorare con strumenti dotati di cui dispongono e configurare esperienze headless per creare in modo automatico in base alle modifiche al contenuto nei repository associati o allo stato di pubblicazione dei contenuti nei canali di pubblicazione associati in modo da favorire l'integrazione continua/distribuzione continua (CI/CD).

---

Titolo e informazioni sul copyright

Distribuisci le applicazioni su Heroku con Experience Orchestration in Oracle Content Management

F52231-02

Giugno 2022

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

Autore principale: Oracle Corporation