Oracle Content Managementのエクスペリエンス・オーケストレーションによるHerokuへのアプリケーションのデプロイ

イントロダクション

Herokuは、アプリケーションの構築、提供、監視およびスケーリングを可能にするクラウド・プラットフォームです。

Herokuへのアプリケーションのデプロイは単純な操作で、基本的なアプリケーションにはいくつかの簡単な手順のみが必要ですが、より複雑なシナリオでは多くの高度な設定をサポートすることもできます。

このチュートリアルでは、Oracle Content Managementのエクスペリエンス・オーケストレーション機能を使用して、GitHubソースからHerokuにアプリケーションをデプロイします。Oracle Content Managementは、コンテンツ・リポジトリおよび公開チャネルを、Oracle Content Managementの外部で開発および管理されたヘッドレス・エクスペリエンスに接続し、コンテンツの変更または公開済ステータスに基づいてデプロイメントを自動的にトリガーする方法を提供します。

チュートリアルは次のステップで構成されます。

  1. Herokuアプリケーションの作成
  2. Oracle Content Managementエクスペリエンスの作成
  3. 送信Webフックの構成
  4. 着信Webフックの構成
  5. オプションで、コンテンツ・プレビュー用の送信/受信Webフックを追加します
  6. イベントの分析

前提条件

このチュートリアルに進む前に、最初に次の情報を読むことをお薦めします。

このチュートリアルに従うには、次のものが必要です。

タスク1: Herokuアプリケーションの作成

Oracle Content Managementインスタンスがまだない場合は、クイック・スタートを参照して、Oracle Cloudに登録する方法、Oracle Content Managementインスタンスのプロビジョニング方法、およびOracle Content ManagementをヘッドレスCMSとして構成する方法を学習します。

Herokuアカウントを持っていない場合は、Herokuアカウントを作成してください。無料の層には、ほとんどのシンプルなHerokuアプリケーションをデプロイするための十分な権限があります。

GitHubアカウントをまだ持っていない場合は、GitHubアカウントを作成する必要があります。基本的な無料アカウントとは、ソースコードを入れる必要があるすべてです。ソース・コードは、パブリック・リポジトリまたはプライベート・リポジトリのいずれかです。

これらすべてを設定したら、HerokuをGitHubに接続し、アプリケーションをデプロイします。

  1. Herokuにログインし、ユース・ケースに応じて左上にある「個人」または「チーム」を選択します。

    この図は、個人設定とチーム設定を示しています。

  2. 右上のドロップダウン・メニューで「新規」をクリックし、「新規アプリケーションの作成」を選択します。

    この図は、アプリケーション作成プロセスを示しています。

  3. アプリケーションに名前を付け、「アプリケーションの作成」をクリックします。

    この図は、アプリケーション・ネーミング・プロセスを示しています。

  4. 「デプロイ」タブを開き、リポジトリを検索してGitHubに接続し、デプロイするリポジトリを選択します。最新バージョンのアプリケーションをデプロイする場合は、この設定を「main」(デフォルト)のままにできます。このプロバイダからサイトを初めて構築する場合、リポジトリにアクセスする権限をHerokuに付与するように求められます。これを許可するには、プロンプトに従います。

    この図は、GitHubリポジトリ接続プロセスを示しています。

    この図は、個人設定とチーム設定を示しています。

  5. 初めて、「手動デプロイ」セクションの「ブランチのデプロイ」をクリックする必要があります。自動デプロイメントを有効にする場合は、「自動デプロイ」セクションで有効にします。

    この図は、最終的なデプロイメント・ステップを示しています。

次のことに注意してください。

HerokuデプロイメントのサンプルVueリポジトリ

このセクションはオプションですが、Herokuに簡単に配備できるVueブログのサンプルリポジトリが用意されています。リポジトリはGitHubにあります。

Vueブログ・サンプルの設定方法に関するチュートリアルは、Oracle Help Center (ビデオ・ウォークスルーを含む)にあります。.envファイルの変更やサーバーへのデータのアップロードなど、このサンプルの設定がシステムに必要になる場合があります。これはチュートリアルに示されています。

GitHubリポジトリに移動して「fork」をクリックすると、アカウントでこのリポジトリをフォークできます。

フォークVueブログリポジトリ。

リポジトリをフォークすると、リポジトリのコピーが作成されます。ここで、リポジトリをフォークすると、元のプロジェクトに影響することなく変更を自由に試すことができますが、このアプリケーションをHerokuにデプロイするには変更は不要です。

このプロジェクトをフォークしたら、前述のように最初のサンプル・デプロイメントを作成できます。

あなたのHerokuアプリの潜在的なCORSエラーを修正

このセクションは、アプリケーションに存在するCORS (Cross- Origin Resource Sharing)エラーを修正するのに役立ちます。CORSは、サーバーが同一生成元ポリシーを緩和できる標準です。そのため、アプリケーションが処理される場所とリクエストされるリソースの元が異なる場合、Webブラウザの同一生成元ポリシーが有効になり、CORSはリクエストの作成に必要です。

Oracle Content Management Webインタフェースでこれを有効にするには、「システム」、「セキュリティ」の順に選択します。HerokuアプリケーションURLをFront Channel CORS Originsに追加し、「保存」をクリックします。

Heroku AppのURLをフロント・チャネルCORSのオリジンに追加しています。

ノート: 同じオリジン・ポリシーに基づいて、2つのURLの起点が同じであるのは、同じプロトコル、ドメインおよびポートを共有している場合のみです。つまり、このセクションでhttpとhttpsの両方のURLを追加する必要がある場合があります。

タスク2: Oracle Content Managementエクスペリエンスの作成

前のタスクで、HerokuをGitHubに接続しました。ここでは、後でHerokuに接続するOracle Content Managementエクスペリエンス・オブジェクトを作成します。

Oracle Content Managementでエクスペリエンス・オブジェクトを作成するには:

  1. Oracle Content Management Webインタフェースに管理者としてログインします。

  2. 左側のナビゲーション・パネルで「エクスペリエンス」をクリックし、右上の「作成」をクリックします。

    この図は、Oracle Content Management Webインタフェースでのエクスペリエンス・オブジェクトの作成を示しています。

  3. 必要な情報を入力し、完了したら「作成」をクリックします。詳細は、Oracle Content Managementのドキュメントを参照してください。

    この図は、エクスペリエンス・オブジェクトのプロパティの構成を示しています。

タスク3: 送信Webフックの構成

次に、新しく作成されたOracle Content Managementエクスペリエンス・オブジェクトに対して送信Webフックを構成します。発信Webフックは、コンテンツの変更または公開済ステータスに基づいて、Oracle Content ManagementからHerokuへのデプロイメントを自動的にトリガーすることを目的としています。

送信Webフックを構成するには:

  1. Oracle Content Management Webインタフェースに管理者としてログインします。

  2. 左側のナビゲーション・パネルで「エクスペリエンス」をクリックします。

  3. 構成するエクスペリエンスを選択し、「プロパティ」パネルを開きます。

    この図は、エクスペリエンス・オブジェクトのプロパティを検索する方法を示しています。

  4. 「プロパティ」パネルで、「送信」タブを開きます。

    この図は、エクスペリエンス・オブジェクトの「送信」タブを示しています。

  5. ターゲットの名前、メソッド(GETまたはPOST)、URLエンドポイントおよびリクエストのトリガーを構成します。

    • ターゲット名: ターゲットには任意の名前を指定できます。Oracle Content Managementでは、このターゲットに一意のTARGET_IDENTIFIERが提供されます。

    • 方法: ドロップダウン・メニューから、リクエストでGETまたはPOSTを指定します。Herokuでは、ビルドをトリガーするPOSTリクエストを実行します。

    • URLエンドポイント: これはAPIエンドポイントです。Herokuには、エンドポイントhttps://api.heroku.com/apps/NAME-OF-YOUR-HEROKU-APP/buildsを使用します。ここで、NAME- OF- YOUR- HEROKU- APPを適宜置き換える必要があります。

    • リクエスト・トリガー: これは「コンテンツ」タブの下にあり、特定のイベントに基づいてトリガーを指定できます。次の例では、Oracle Content Managementのブログ・チャネルを表すOCEGettingStartedRepositoryというアセット・リポジトリの変更に基づいてビルドがトリガーされます。

    この図は、エクスペリエンス・オブジェクトの送信ターゲットを示しています。

  6. ヘッダーを構成します。「認可」、「承諾」および「コンテンツ・タイプ」の3つのヘッダーが必要です。これらは、Herokuのドキュメントに記載されています。

    • 認可: Herokuから取得する必要がある認可トークンです。Herokuからビルドを作成できるのは承認されたユーザーのみであり、このトークンはHeroku APIを使用する認証に必要です。Heroku APIキーは、[アカウント設定] > [APIキー] > [Reveal]の順にクリックして表示できます。

    • 受入れ: これは、Acceptヘッダーの動作です: application/vnd.heroku+json; version=3。これが機能するには、バージョン3のHeroku Build APIを使用する必要があります。

    • Content- Type: Content- Typeヘッダーは次のようになります: application/json。

    この図は、エクスペリエンス・オブジェクトの送信ヘッダーを示しています。

  7. 本体を構成します。次に示すように、URLおよびオプションのバージョンがJSONオブジェクトとして書式設定されたソースblobが1つ必要です。ソースblobは、デプロイメントのソース・コードがある場所です。本文のJSONオブジェクトは次である必要があります:

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

    URL

    使用するURLは、ビルドのソースコードのgzipped tarアーカイブがダウンロードされた場所です。これは GitHubのAPIを通じて取得します。

    GitHubのパブリック・リポジトリとプライベート・リポジトリのURLに違いがあることに注意してください。詳細は、Herokuのドキュメントを参照してください。

    パブリック・リポジトリの場合、URLは次のようになります。

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

    プライベート・リポジトリの場合、URLは次のようになります。

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

    <username>はGitHubユーザー名で、<repo name>はGitHubリポジトリのスラグで、<branch>はブランチの名前です(通常は'main'または'master')。サンプルのパブリック・リポジトリの例を次に示します。

    プライベート・リポジトリの場合、プライベート・リポジトリ・ソースのblob URLのuser:tokenセクションを変更する必要があります。user部分は以前と同じユーザー名で置き換えることができ、tokenは適切なスコープのGitHub個人アクセス・トークンに置き換える必要があります。このトークンを生成するには、GitHubドキュメントで説明されているステップに従います。このトークンの有効期限(通常は期限切れに設定したくない)には特に注意してください。このトークン"repo"アクセス権のみを指定する必要があります。これにより、プライベート・リポジトリを完全に制御できます。

    翻訳

    バージョン・パラメータは必須ではなく、ソース・コードのダウンロードおよび構築時には使用されません。これは単に、どのソース・コード・バージョンがどのスラグで構築されたかを追跡するためにオプションで使用できるメタデータの一部です。

    ここでは、"{{TARGET_IDENTIFIER}}"をバージョン・パラメータとして追加します。Oracle Content Managementでは、ターゲット名の横に表示されるIDとしてTARGET_IDENTIFIERがリクエストの本文に配置されます。これがHerokuに送信されると、構成されると、着信Webフック経由で返信されます。Herokuからのビルドに関するこのレスポンスでは、Oracle Content Managementはペイロードを受信し、そのターゲットIDが存在するかどうかを評価します。その場合、ペイロードはOracle Content Managementからの送信ターゲットに関連付けられます。それ以外の場合、「不明」とみなされます。ターゲットIDの詳細は、Oracle Content Managementのドキュメントを参照してください。

    この図は、エクスペリエンス・オブジェクトの送信本文を示しています。

  8. 右上の「適用」をクリックして構成を保存します。

  9. オプションで、APIエンドポイントの横にある「テスト」をクリックして、選択したチャネルのコンテンツまたは公開済ステータスが変更されたかのように、このビルドのトリガーをテストします。

ノート: Oracle Content Managementでの送信Webフック構成の詳細は、Oracle Content Managementのドキュメントを参照してください。

タスク4: 受信Webフックの構成

次に、新規に作成したエクスペリエンス・オブジェクトに対してHerokuからOracle Content Managementへの受信Webフックを構成します。着信Webフックは、Oracle Content Managementを離れることなくビルドとそのステータスに関する情報をOracle Content Managementに戻すことを目的としています。結果は「イベント」タブに表示でき、イベントの分析時に詳細を確認できます。

受信Webフックを構成するには:

  1. Oracle Content Management Webインタフェースに管理者としてログインします。

  2. 左側のナビゲーション・パネルで「エクスペリエンス」をクリックします。

  3. 構成するエクスペリエンスを選択し、「プロパティ」パネルを開きます。

    この図は、エクスペリエンス・オブジェクトのプロパティを検索する方法を示しています。

  4. 「プロパティ」パネルで、「受信」タブを開きます。ウェブフックのURLをコピーします。これをHerokuに配置します。

    この図は、エクスペリエンス・オブジェクトの「受信」タブを示しています。

  5. Herokuに再度ログインし、アプリケーションを見つけます。右上の「詳細」、「Webフックの表示」の順にクリックします。

    この図は、HerokuのWebフックを表示する場所を示しています。

  6. 画面中央の「Webフックの作成」をクリックします。

    この図は、HerokuでWebフックを作成する場所を示しています。

  7. 「New Webhook」ダイアログで、新しいWebフックの情報を指定します。名前は問題なく、ペイロードURLはOracle Content Managementからコピーされたものであり、シークレットは必要ありません。イベント・タイプの場合、「api:build」のみが選択されていることを確認します。

    この図は、HerokuでOracle Content ManagementをWebフックとして構成する方法を示しています。

  8. 完了したら、「Webフックの追加」をクリックします。

タスク5 (オプション): コンテンツ・プレビューの追加送信および受信Webフックの追加

REST APIは、コンテンツの配信と管理、および会話、ドキュメント、ユーザーおよびグループに対してOracle Content Managementで使用できます。Herokuとの統合では、コンテンツ・プレビューとコンテンツ配信で同じ経験を使用して、異なるHerokuアプリケーションに2つの個別のデプロイメントを用意すると便利です。これにより、本番デリバリ・ビルドに影響を与えることなく、アセットに対する未公開の変更をアプリケーションでプレビューできます。このオプションのセクションでは、実稼働環境とは別に、2番目のターゲットを使用してプレビュー・デプロイメントをトリガーする方法を説明します。

最初のステップは、1つのHerokuアプリケーションがプレビュー・コンテンツ、もう1つの配信コンテンツを使用する、合計2つの異なるHerokuアプリを作成することです。Herokuアプリケーションを作成するには、task 1の手順に従います。

これを設定したら、両方の送信ターゲットを構成する必要があります。下部にある「ターゲットの追加」をクリックして、2番目のターゲットを追加できます。タスク3のステップに従って、送信Webフックを作成します。発信Webフックには、次の2つの主な違いがあります。

  1. コンテンツ配信APIは、コンテンツ・チャネルの公開に基づいてトリガーする必要があり、コンテンツ・リポジトリの変更に基づいてコンテンツ・プレビューAPIをトリガーする必要があります。

  2. 送信Webフックの本文は、コンテンツ配信APIまたはコンテンツ・プレビューAPIを使用する適切なコードに関連付ける必要があります。これには、2つの別々のGitHubリポジトリでホストされているプレビュー・コードと配信コードが必要です。

    この図は、配信を構成し、外部Webフックをプレビューする方法を示しています。

ノート: Oracle Content ManagementのプレビューAPI構成の詳細は、「ヘッドレスOracle Content ManagementサイトのプレビューAPIの使用」を参照してください。

最後の手順は、各Herokuアプリケーションからの着信Webフックを構成することです。これは、各アプリケーションの task 4の手順に従って実行できます。どちらのHerokuアプリケーションも、Oracle Content Managementで提供されるものと同じ受信WebフックURLを共有します。

注意すべき重要な課題の1つは、Herokuがアカウントごとの同時ビルド数を制限することです。Herokuでは、検証済のアカウントのみが、アカウント全体で複数のアプリのビルドを同時に実行でき、Herokuに追加の支払いが必要です。同じアカウントの2つのHerokuアプリケーションでOracle Content Managementのエクスペリエンス・オーケストレーション機能と統合された無料のHerokuバージョンを使用している場合は、アセット・リポジトリで別の変更を実行するか、コンテンツ・チャネルで公開する前にビルドが終了するのを待つ必要がある場合があります。

タスク6: イベントの分析

最後に、Oracle Content ManagementのWebインタフェースを離れることなく、Oracle Content Managementで完全なエクスペリエンス・オーケストレーションをテストできます。コンテンツまたは公開ステータスの変更に基づいて、または「送信」タブの「テスト」ボタンをクリックすると、次のステップが実行されます。

  1. Oracle Content Managementは、指定されたヘッダーおよび本文とURLエンドポイントのPOSTリクエストを使用してHeroku Build APIを呼び出してビルドをトリガーします。

  2. Herokuはビルドを実行するリクエストを受信し、ソース・コードを使用します(Oracle Content Managementからコンテンツを取得します)。

  3. Herokuは、ビルドの開始時にOracle Content Managementにレスポンスをプッシュし、保留中のステータスやその他のメタデータを提供します。

  4. ビルドが終了すると、Herokuはビルド失敗または追加のメタデータによる成功に関する別のレスポンスをOracle Content Managementに発行します。

これらのすべてのイベントは、「プロパティ」パネルの「イベント」タブに表示されます。次に、1、2および3の番号が付けられたイベントのシーケンスの例を示します。

この図は、エクスペリエンス・オーケストレーションのイベントを示しています。

示されているように、最初のイベント(ラベル1)は、ビルドを開始するためのOracle Content ManagementからHerokuへのトリガーです。2番目のイベント(ラベル2)は、Herokuから戻される受信Webフックで、ビルドが開始されたことをOracle Content Managementに伝えます。最後のイベント(ラベル3)は、HerokuからOracle Content Managementへの着信Webフックからも成功するビルド・イベントです。これらの各イベントは、「イベント」タブでイベントをクリックして詳細に分析できます。すべてのイベントに「Heroku Endpoint API Build」という同じタグがあることに注意してください。最初のイベント(ラベル1)は、「送信」タブで指定した名前であるため、このイベントと呼ばれます。2番目と3番目のイベント(それぞれ2および3というラベルが付いた)は、ターゲットに関連付けられたリクエストに{{TARGET_IDENTIFIER}}トークンを追加したため、同じタグが付けられます。

「イベント」タブの各イベントの下に表示されるコンテンツは、「分析」タブの設定から取得されます。「分析」タブでは、受信レスポンス・ペイロードから情報を抽出し、「イベント」タブに表示して、コンテンツ・エディタやコントリビュータにとって重要な情報(コンテンツの保存、公開、稼働時間など)を提供できます。「分析」タブの詳細は、Oracle Content Managementのドキュメントを参照してください。

前述のイベントについて、「分析」タブで次が指定されています。

この図は、エクスペリエンス・オーケストレーションの分析を示しています。

包括的なエクスペリエンス・オーケストレーション

このセクションはオプションですが、Oracle Content Managementのエクスペリエンス・オーケストレーション機能を使用するプロセスと利点の全体を示します。この項では、実稼働環境のエクスペリエンスURLを表示し、コンテンツを変更してから公開し、エクスペリエンスURLに影響を与えずにHerokuデプロイメントで公開されたコンテンツを表示し、Oracle Content Managementから移動します。

最初に、経験の「送信」タブで設定できるOCEGettingStartedRepositoryのアセットの公開ステータスに基づいてプレビューの変更を確認する必要があります。

最初に、エクスペリエンスURLの「プロパティ」セクションで設定できるエクスペリエンスURLサイトです。これは、この本番に影響を与えずにプレビューを表示するサイトの現在のライブ状態です。

この図は、ブログのエクスペリエンスURLを示しています。

次に、コンテンツの変更を作成し、そのコンテンツを適切な対応するチャネルに公開します。ここでは、「How To」というブログのホームページのアセットを更新し、「Make Coffee」という単語を追加します。

検索バーで「方法」アセットを検索し、「編集」アイコンをクリックします。

この図は、How To資産を示しています。

次に、「コーヒーを作る」という単語を追加してコンテンツを変更し、右上に保存します。

このイメージは、編集したHow Toアセットを示しています。

そのコンテンツを正しいチャネルに公開して、プレビュー用に適切なビルドをトリガーします。

この図は、「公開」タブを示しています。

この図は、チャネルへの公開保存を示しています。

エクスペリエンス・オーケストレーション・オブジェクトに移動し、イベントの分析時に「イベント」タブを表示することで、トリガーされたビルドを検証できます。

ビルドが終了して成功したら、「Heroku Endpoint API Build」というプレビューURLが「How To」の後の「Make Coffee」という語で更新されていることを確認できます。また、以前のエクスペリエンスURLが引き続き同じサイトであることがわかります。

この図は、ブログのプレビューURLを示しています。

結論と次のステップ

このチュートリアルでは、Oracle Content Managementのエクスペリエンス・オーケストレーション機能を使用して、GitHubソースからHerokuにアプリケーションをデプロイしました。最初にHerokuアプリケーションを作成し、Node.jsを使用して動作するサンプルVueブログ・リポジトリなどのGitHubソースをデプロイしました。次に、Oracle Content Managementエクスペリエンスを作成し、送信Webフックおよび受信Webフックを構成しました。最後に、エクスペリエンス・オーケストレーション・プロセスが設定され、コンテンツまたは公開ステータスの変更、または「送信」タブの「テスト」ボタンをクリックするだけで、Oracle Content Managementは、URLエンドポイントでPOSTリクエストを使用して指定されたヘッダーと本文を使用してHeroku Build APIをコールしてビルドをトリガーします。イベントは、「イベント」タブのOracle Content Managementで直接分析でき、完全なエクスペリエンス・オーケストレーション・プロセスもデモンストレーションしました。

エクスペリエンス・オーケストレーション・プロセスを管理する次のステップは、次のとおりです。

  1. コネクテッドなヘッドレス体験を見る

  2. エクスペリエンス・オブジェクトの共有

これにより、コンテンツ・リポジトリと公開チャネルをHerokuにデプロイされたヘッドレス・エクスペリエンスに接続し、コンテンツの変更や公開済ステータスに基づいてデプロイメントを自動的にトリガーできるようになりました。コンテンツ・プロバイダは、コンテンツを整理、取得、翻訳、コラボレーション、承認および公開するための強力なツールなど、リポジトリ・アセット管理の利点を活用できます。その後、Oracle Content Managementを離れることなく、ヘッドレス・アプリケーションをコンテキスト内およびコンテンツとともにプレビューできます。エクスペリエンス開発者は、所有するツールで作業し、ヘッドレス・エクスペリエンスを構成することで、関連するリポジトリ内のコンテンツへの変更や、関連する公開チャネル内のコンテンツの公開ステータスに基づいて自動的に構築されるようにし、継続的な統合/継続的なデプロイメント(CI/CD)を促進できます。