機械翻訳について
  1. Oracle Content Managementの統合および拡張
  2. Oracle Content Management統合の開発
  3. Webhookの使用

18 Webフックの使用

Oracle Content Managementは、外部アプリケーションからイベント通知を受信するために使用できる受信webフックを提供します。

送信webフックを使用して、アセットの公開、アセット・ライフサイクル、サイト公開、事前レンダリングおよびスケジュール済ジョブ・イベントの通知を他のアプリケーションに自動的にプッシュすることもできます。

次のトピックでは、webフックの使用方法について説明します:

送信Webフック

アセット公開、アセット・ライフサイクル、サイト公開、事前レンダリングおよびスケジュール済ジョブ・イベントのプッシュ通知には、送信webフック・エンドポイントを使用できます。

送信Webフックの構成

送信webフックを使用して、アセットおよびサイト・イベントに基づいてOracle Content Managementで通知を自動的に投稿できます。

たとえば、新しいコンテンツの公開時にアプリケーションに通知を投稿し、アプリケーションで新しいコンテンツを使用できるようにすることが考えられます。

送信webフックを作成するには:

  1. 管理者としてOracle Content Management webアプリケーションにサインインしたら、左側のナビゲーション・メニューの「管理」領域の「統合」をクリックします。
  2. 「統合」メニューで、Webhooksをクリックします。
  3. 「作成」をクリックします。
  4. 作成するwebフックのタイプを選択します:
    • アセット・ライフサイクルWebフック: リポジトリ内のアセット・ライフサイクルの変更に関するプッシュ通知を受け取ります。
    • アセット公開Webフック: チャネルに公開されたアセットまたはチャネルから公開されていないアセットに関するプッシュ通知を受信します。
    • サイト公開Webフック: サイトの公開についてのプッシュ通知を受信します。
    • プリンタ・ページ・リフレッシュWebフック: サイト詳細ページをレンダリングおよびキャッシュする必要性に関するプッシュ通知を受信します。
    • スケジュール済ジョブWebフック: リポジトリでスケジュールされたジョブの公開に関するプッシュ通知を受信します。
  5. webフックの名前と説明を入力します。 この名前は投稿された会話メッセージの見出しとして表示されます。
  6. Webフックを有効にします。
  7. webフック・モニタリングの情報を指定します:
    • アセット・ライフサイクルwebフックを作成している場合は、アセット・イベントを監視するリポジトリを選択します。 通知を「アセット・タイプ」でフィルタできます。これは、選択したタイプのコンテンツ・アイテムまたはデジタル・アセットに対して公開されたイベントにのみ適用されます。
    • アセット公開webフックを作成する場合は、アセット公開イベントをモニターする公開チャネルを選択します。
    • サイト公開webフックを作成する場合は、サイト・イベントとして監視するサイトの名前を指定します。
    • 事前レンダーwebフックを作成する場合は、詳細ページをレンダリングおよびキャッシュする必要があることをPrerenderに通知します。
    • スケジュール済ジョブのwebフックを作成する場合は、スケジュール済ジョブ・イベントをモニターするリポジトリを選択します。
  8. 通知を生成するイベントを選択します。
  9. 各イベントについて簡潔な情報または詳細な情報のいずれが必要かを選択します。
    • アセット・ライフ・サイクルwebフックの場合、イベントをトリガーしたユーザー、イベントの内容、イベントに関係したアイテム、イベントが発生したリポジトリ、イベントが発生した時間などの簡単な通知が含まれます。 詳細通知には、概要に一覧表示されている同じ情報と、各コンテンツ・アイテムまたはデジタル・アセットのすべてのフィールドのリストが含まれます。
    • アセット公開webフックの場合、概要通知には、公開された各アセットのIDが含まれます。 詳細通知には、短い通知にリストされた同じ情報に加えて、各公開済アセットのすべてのフィールドのリストが表示されます。
  10. 通知を投稿するターゲットURL (エンドポイント)を入力します。
  11. エンドポイントで認証が必要な場合は、認証のタイプを選択し、「詳細」をクリックして認証情報を入力します。

    Oracle Content Management (OCM) webフックは、次のオプションをサポートして、Webフック通知レシーバの認証を構成します:

    • なし: レシーバは、認証を必要としません。
    • 基本: レシーバにはBasic認証が必要です。
    • ヘッダー: レシーバにはセキュア・ヘッダーが必要です。
  12. エンドポイントが自己署名SSL証明書を使用できるようにするには(テストまたは開発でのみお薦めします)、対応するチェック・ボックスを選択します:
    • 自己署名SSL証明書: レシーバは自己署名SSL証明書を受け入れます。
  13. webフック・エンドポイントにイベント通知が送信されるときにサービスとOracle Content Management間のコールを認証するには、OCMがシグネチャを使用してイベントにシグネチャします。 シグネチャは、標準のSHA-256 HMAC暗号化を使用したハッシュ・ベースのメッセージ認証(HMAC)コードのセキュリティ・トークンです。 HMACトークンを使用して、Oracle Content Managementによって通知が送信されたことを確認できます。

    送信webフックの構成ページで、対応するチェック・ボックスを選択して、シグネチャ・ベースのセキュリティ・オプションを有効にします。 32文字の英数字(小文字a-z、数字0-9)で構成されるシークレット・キーを入力します。

    • シグネチャ・ベースのセキュリティ: 受信側では、サーバーとクライアントの認証トークンが同じである必要があります。

    目的のイベントがトリガーされると、webフック・ペイロードが、署名済イベントのX-OCM-Webhook-Signatureヘッダーを使用してアプリケーションに送信されます。 X-OCM-Webhook-Signatureヘッダーには、エポック・タイムスタンプおよびシグネチャが含まれます。次に例を示します: 

    {
            X-OCM-Webhook-Signature: 
            t=1660807672,
            v=d1b1ea85b53f8dd435a96f59d778d9cdb09be1905d1cecc7acdf4e03ecf60a1b
}

    tの値はエポック・タイムスタンプで、リクエストの送信時に計算され、リクエストの送信時にシグネチャvの計算に使用されます。

    vの値は、tおよびペイロード( hash(t + ”.” + payload))から計算されたシグネチャです

    webフック・リクエストを受信したら、シグネチャを確認します:
    1. リクエスト・ヘッダー X-OCM-Webhook-Signatureを解析して、エポック・タイムスタンプtおよびシグネチャvの値を取得します。
    2. 現在のエポック・タイムスタンプt1をコンピュートし、t1とt (ステップaから取得したエポック・タイムスタンプ)の差が、30秒や60秒などのしきい値を超えないようにします。 エポック・タイムスタンプの差がしきい値より小さい場合にのみ、次のステップに進みます。
    3. ステップaのタイムスタンプtの値とリクエストからのペイロードを使用して、次のように連結して文字列を作成します:

      t + “.” + payload

    4. シグネチャ・ベースのセキュリティを選択したときにwebフック構成ページのシークレット・キーを使用して、ステップcで作成した文字列のHMACシグネチャをSHA-256アルゴリズムでコンピュートします。 次のステップに進む前に、シグネチャが16進数でエンコードされていることを確認してください。 javax.crypto.Mac (jdk-1.8ライブラリの一部)を使用して、HMACシグネチャを生成できます。 また、Bouncy Castleなどのサードパーティ・ライブラリを使用して、ペイロードのシグネチャを生成することもできます。
    5. ステップdで生成されたシグネチャとリクエスト・ヘッダーのシグネチャを比較します。 シグネチャの値が一致する場合にのみ、リクエストの追加処理を続行します。
  14. 「保存」をクリックします。

webフックを削除するには、Webフックの横にある「削除」をクリックします。

webフックを編集するには、Webフックの横にある「編集」をクリックします。

Webフック・イベントのモニター

管理者または開発者は、Webフックにポストされたイベントのログにアクセスできます。 「イベント・ログ」には、Oracle Content Managementインスタンスのwebフック・アクティビティのオブジェクトID、イベントIDおよび公開日時が表示されます。

Webフック・イベントを監視する手順は、次のとおりです:

  1. 管理者または開発者としてOracle Content Management webアプリケーションにサインインした後、左側のナビゲーション・メニューの「管理」領域の「統合」をクリックします。
  2. 統合ドロップダウン・メニューでWebhooksをクリックします。
  3. webフック・インスタンスの設定ページで、「イベント・ログ」ページを開くオプションを選択します。

    「イベント・ログ」ページには、このwebフックに公開されたすべてのイベントのリストが表示されます。 最近の投稿が上部に表示されます。


webhook-log.pngの説明は以下のとおりです
「図webhook-log.pngの説明」

イベントごとに、そのレスポンス・ステータス(「成功」または「失敗」)もログに表示されます。 ポストされたイベントを展開して、webフック・クライアントに送信された通知の詳細を表示できます。

次の表に、トリガーされるイベントの詳細を示します:
イベント 詳細
SCHEDULEDPUBLISHING_PARENTCREATED - 繰返しスケジュール済公開ジョブの作成

キー: cec.event.scheduledpublishing.parentcreated.name

表示名: スケジュール済公開ジョブが作成されました

メッセージの詳細: 繰返しジョブ'{job-name}' '{job-id}'が'{datetime}'に作成されました
SCHEDULEDPUBLISHING_PARENTUPDATED - 繰返しジョブ全体のプロパティが更新されます(シリーズ名または説明の更新、ジョブ・マネージャの追加または削除など)

キー: cec.event.scheduledpublishing.parentupdated.name

表示名: スケジュール済公開ジョブが更新されました

メッセージの詳細: 定期公開ジョブ'{job-name}' '{job-id}'が'{datetime}'に更新されました
SCHEDULEDPUBLISHING_CREATED - スケジュール済公開ジョブの作成

キー: cec.event.scheduledpublishing.created.name

表示名: スケジュール済公開ジョブが作成されました

メッセージの詳細: '{datetime}'に作成されたアセット'{the-first-10-asset-guids}'を使用したスケジュール済公開ジョブ'{job-name}' '{job-id}'
SCHEDULEDPUBLISHING_UPDATED - スケジュール済公開ジョブの更新

キー: cec.event.scheduledpublishing.updated.name

表示名: スケジュール済公開ジョブが更新されました

メッセージの詳細: スケジュールされた公開ジョブ'{job-name}' '{job-id}'(アセット'{the-first-10-asset-guids}')が'{datetime}'に更新されました
SCHEDULEDPUBLISHING_CANCELLED - スケジュール済公開ジョブの取消

キー: cec.event.scheduledpublishing.cancelled.name

表示名: スケジュール済公開ジョブが取り消されました

メッセージの詳細: スケジュールされた公開ジョブ'{job-name}' '{job-id}'(アセット'{the-first-10-asset-guids}')が'{datetime}'で取り消されました
SCHEDULEDPUBLISHING_STARTED - スケジュール済公開ジョブが開始されました

キー: cec.event.scheduledpublishing.started.name

表示名: スケジュール済公開ジョブが開始されました

メッセージの詳細: スケジュールされた公開ジョブ'{job-name}' '{job-id}'(アセット'{the-first-10-asset-guids}')が'{datetime}'で開始されました
SCHEDULEDPUBLISHING_COMPLETED - スケジュール済公開ジョブが完了しました

キー: cec.event.scheduledpublishing.completed.name

表示名: スケジュール済公開ジョブが完了しました

メッセージの詳細: アセット'{the-first-10-asset-guids}'を使用したスケジュール済公開ジョブ'{job-name}' '{job-id}'が'{datetime}'に完了しました

ジョブが失敗した場合、失敗した理由が追加されます。

メッセージの詳細: アセット'{the-first-10-asset-guids}'を使用したスケジュール済公開ジョブ'{job-name}' '{job-id}'が'{datetime}'に完了しました。{if-failed-failed-reason}

Oracle Cloud 「アクティビティ・ログ用のREST API」は、Oracle Content Managementでアクティビティを検索する機能を提供します。 このAPIには、次のエンドポイントがあります:

  • 「監査ログ」:アクティビティおよび関連データの詳細を提供します。
  • 「イベント」:タイプおよびカテゴリの詳細を提供します。

プッシュ通知にエンドポイントを使用

Oracle Content Managementは、アセットの公開、アセット・ライフサイクル、サイト公開、事前レンダリングおよびスケジュール済ジョブ・イベントに関する通知をwebフック・エンドポイントに自動的に配信します。

エンドポイントのペイロードでイベントが発生したときに通知を受信するwebフックのイベントをサブスクライブします。 たとえば、エンドポイントがDIGITALASSET_CREATEDというイベントにサブスクライブしている場合、デジタル・アセットを指定したリポジトリに作成すると、webフック・ペイロードによりWebフックの名前、イベントが発生した時間、およびイベントを行ったユーザーを知らせることができます。

なんらかのアクションが発生した場合に通知を受けるためにエンドポイントを使用できます。 その後、Oracle Content Managementはそのエンドポイントを呼び出します。 他のREST APIと同様に、RESTエンドポイントを使用してwebフックを作成できます。 webフック・エンドポイントごとにサーバーURLを指定する必要があります。 GET、POST、PUTおよびDELETEエンドポイントはOracle Content Managementサーバーでホストされるため、すべてのwebフック・エンドポイントのコンテキストは同じホスト名、ポートおよびシステムになります。

REST APIヘッドレス・エンドポイントですべてのコンテンツ・アイテムを作成できます。 REST APIを使用してwebフックを作成し、イベントをリスニングすることもできます。

webフック・エンドポイントは次のとおりです:

GET /webhooks          Lists all webhooks.
POST /webhooks         Creates a webhook with the given information in the payload.
GET /webhooks/{id}     Reads a webhook with the given ID.
PUT /webhooks/{id}     Updates a webhook with the given information in the payload.
DELETE /webhooks/{id}  Deletes a webhook with the given ID.

または、「管理>統合>Webフック」のOracle Content Management web UIでWebフックを作成、構成、有効化または無効化できます。 「Webフックの構成」を参照してください。

イベント・ペイロードは、「要約」または「詳細」出力とともに参照できます。 Webフック・ペイロードには次のデータが含まれています:

  • 起動されたwebフック
  • トリガーされたイベント(CONTENTITEM_UPDATEDまたはCHANNEL_ASSETPUBLISHEDなど)
  • イベントが登録され、どのユーザーがトリガーしたか
  • イベントの対象エンティティ:
    • 資産ライフサイクルwebフックの場合、コンテンツ・アイテムまたはデジタル・アセットにできます。
    • アセット公開イベントの場合、公開されたすべてのコンテンツの識別子のリストが表示されます。

Webフックには、次の表で説明するように3つの異なるフォーマットがあります。

書式 出力
要約 出力には、ペイロードの基本情報のみが含まれます。 出力には、アクションの内容、発生日時、内容のリポジトリ、アクションの実行者などの詳細が表示されます。
詳細 出力には、ペイロードのすべてのコンテンツ情報が含まれます。 この出力から、指定したURLのコンテンツ・アイテム・データ全体が取得されます。
空 アセット公開webフックでのみ使用できます。 出力に「空」を指定すると、ペイロードには公開セッションIDを表す識別子のみが含まれます。

エンドポイントで認証が必要な場合は、認証のタイプを選択し、認証情報を入力できます。

アセット・ライフ・サイクルWebフックからのプッシュ通知の受信

アセット・ライフサイクルwebフックでは、コンテンツ・アイテムおよびタクソノミのOracle Content Managementリポジトリ内のアセット・ライフサイクル・イベントに関する通知をプッシュできます。

webフックに関する次のイベントに関する情報通知を受信できます:


webフック・タイプ・アセット・ライフ・サイクルに使用できるイベント

リポジトリ・マネージャは、REST APIエンドポイントまたはOracle Content Management webインタフェースの「管理>統合>Webフック」ページで、アセット・ライフサイクルWebフックを作成できます。 webフックのページでは、次の設定を構成できます:

  • 名前: webフック名。
  • 説明: webフックの説明。
  • タイプ: webフック・タイプ。
  • Webフックの有効化: webフックの有効または無効のステータス。 デフォルトは「無効」です。
  • リポジトリ: webフック通知のイベント・スコープを設定するためのリポジトリ。
  • アセット・タイプ: webフック通知のイベント・スコープを設定するためのアセット・タイプのリスト。 フィルタ機能は、選択したタイプのコンテンツ・アイテムまたはデジタル・アセットに対して公開されたイベントにのみ適用されます。
    • 「すべてのアセット・タイプ」オプションを使用して、リポジトリに割り当てられている、またはリポジトリに割り当てられるタイプのアセットのライフサイクル・イベントに関する通知を受信します。
    • 「個々のアセット・タイプの選択」オプションを使用して、選択したタイプのアセットのライフサイクル・イベントに関する通知のみを受信します。 管理者は、コンテンツとデジタル・アセットの両方のタイプを選択できます。 選択したリポジトリに割り当てられたアセット・タイプのみがアセット・タイプ・ピッカーに表示されます。
  • イベント: 通知を受信するwebフックのイベントのリスト。 webフックに対して「現在および将来のイベントすべて」オプションを使用して、すべてのイベントの通知を受信します。 webフックの「個々のイベントの選択」オプションを使用して、特定のイベントの通知を受信します。
  • ペイロード: エンドポイントに送信するペイロードのタイプ。 (「要約」または「詳細」)
  • ターゲットURL: 通知をポストするエンドポイントのURL。
  • 認証: コールバック・レシーバのセキュリティ(なし、基本、ヘッダー)
  • 自己署名SSL証明書: レシーバは自己署名SSL証明書を受け入れます。
  • シグネチャ・ベースのセキュリティ: 受信側では、サーバーとクライアントの認証トークンが同じである必要があります。

「名前」、「説明」、「Webフックの有効化」、「ターゲットURL」および「認証」は、webフックの標準設定です。 リポジトリ設定で、マネージャ権限を持つリポジトリを選択します。

アセット公開Webフックからのプッシュ通知の受信

アセット公開webフックを使用すると、Oracle Content Managementでアセットおよびタクソノミ公開イベントのプッシュ通知を送信できます。

アセット公開webフックから、次のイベントに関する情報を受け取ることができます:


アセット公開webフックでサポートされるイベント通知

チャネル・マネージャは、REST APIエンドポイントまたはOracle Content Management webインタフェースの「管理>統合>Webフック」設定ページで、新しいアセット公開Webフックを作成できます。 これにより、次のチャネルに公開されたアセットに関する通知が可能になります:

  • 公開またはセキュアなカスタム公開チャネル
  • Oracle Content Managementがパブリックまたはセキュアなエンタープライズ・サイト用に作成する公開チャネル

チャネルのスコープ内にある次のアクティビティに関する通知を受信できます:

  • 公開済: 新しいコンテンツ・アイテム、デジタル・アセットまたはタクソノミが公開されます。
  • 非公開: コンテンツ・アイテム、デジタル・アセットまたはタクソノミは非公開です。
サイト公開Webhookからのプッシュ通知の受信

サイト公開webフックは、サイト公開イベントのプッシュ通知をOracle Content Managementで送信できます。

サイト・マネージャは、REST APIエンドポイントまたはOracle Content Management webインタフェースの「管理>統合>Webフック」設定ページで、新しいサイト公開Webフックを作成できます。 これにより、published、statusおよびunpublishedなどのタイプのサイト・イベントの通知が有効になります。

Prerender Webhookからのプッシュ通知の受信

prerender webhookは、Oracle Content ManagementのPrerenderイベントのプッシュ通知を送信できます。

サイト・マネージャは、REST APIエンドポイントまたはOracle Content Management webインタフェースの「管理>統合>Webフック」設定ページで、新しいレンダーWebフックを作成できます。

この送信webフックは、レンダー・イベントに関する通知を設定できます。これにより、レンダー・サーバーが拡張され、アセットがサイト・チャネルに公開された後、詳細ページのレンダリングとキャッシュが可能になります。

管理者は、サイト詳細ページのリフレッシュWebフックを作成して、詳細ページをレンダリングおよびキャッシュする必要があることをPrerenderに通知できます。

スケジュール済ジョブWebフックからのプッシュ通知の受信

スケジュール済ジョブのwebフックは、Oracle Content Managementのリポジトリにスケジュールされたジョブを公開するためのプッシュ通知を送信できます。

サイト・マネージャは、REST APIエンドポイントを使用して、またはOracle Content Management webインタフェースの「管理」 > 「統合」 > Webhooks設定ページで、新しいスケジュール済ジョブのWebフックを作成できます。 これにより、リポジトリ内のスケジュール済公開ジョブの通知が有効になります。

created, updated, canceled, started、completedなどのタイプのスケジュール済ジョブ・イベントの通知を受信できます。

受信Webフック

webフックを使用して、外部サービスで発生する様々なイベントに基づいてOracle Content Managementが自動的に通知を受信するようにできます。

受信webフック・フレームワークは、外部アプリケーションまたはサービスがOracle Content Managementで必要な様々なイベントについてOracle Content Managementを呼び出して通知する方法を提供します。 webフック・フレームワークは、トークン・ベースの認証で受信リクエストを検証するための手段を提供します。

ノート:

受信webフックは、「プライベート・インスタンス」ではサポートされていません。
  1. 管理者または開発者としてOracle Content Management webアプリケーションにサインインした後、左側のナビゲーション・メニューの「管理」領域の「統合」をクリックします。
  2. webフック・サポートを必要とするOracle Content Managementコンポーネントは、受信Webフック・インスタンスを作成します。 たとえば、Lingotek翻訳コネクタを作成すると、「コンテンツ翻訳のLingotek試行コネクタのリクエスト」のように、バックグラウンドのコネクタ・フレームワークによって、そのコネクタに関連付けられた受信webフックのインスタンスが作成されます。 「統合」メニューで、WebhooksをクリックしてLingotek翻訳コネクタのwebフック・インスタンスのリストを表示します。
  3. webフック・インスタンスの作成時に、フレームワークは有効期間の構成可能なセキュリティ・トークンを生成します。 すべての受信リクエストには、このトークンが必要です。 フレームワークは、トークンとその有効期限を検証して、受信リクエストを検証します。

    コンポーネントは、コールバックURLおよびトークンを外部アプリケーションに送信します。 コンポーネントが外部アプリケーションにサブスクライブしているイベントが発生すると、コンポーネントは同じURLを介してOracle Content Managementにコールバックします。

    受信webフック・インスタンスの横にあるチェック・ボックスをクリックし、アクション・ツールバーから「編集」を選択します。 または、受信webフックのクリック可能な名前をクリックして、「編集」ページに移動できます。 「一般」ページでは、「サービス有効期間」および「セキュリティ」の値を指定できます。 「名前」および「説明」は、受信webフックの作成時に移入されますが、必要に応じてこれらの値を変更できます。「ターゲットURL」フィールドは読取り専用です。 サーバーは、webフック・インスタンスの作成時にURLを生成します。

    チェックボックスをクリックしたら、アクション・ツールバーから「編集」を選択する必要があります。 または、受信webフックのクリック可能な名前をクリックして、「編集」ページに移動できます。
  4. 「イベント・ログ」ページには、すべてのイベントのリストが表示されます。 リストには、ログインID、イベントが発生した日時、ステータス(成功または失敗)およびダウンロード・アイコン(イベント・ログをダウンロード)が表示されます。

受信Webフックの構成

Oracle Content Management webインタフェースを使用して、受信Webフックのアダプタ・フィールドおよびCALアダプタを構成します。

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

  1. 管理者としてOracle Content Management webアプリケーションにサインインしたら、左側のナビゲーション・メニューの「管理」領域の「統合」をクリックします。
  2. 「統合」メニューで、Webhooksをクリックします。
  3. Lingotek-Incoming Webhookの次のフィールドに入力します。

    「名前」および「説明」フィールドは、受信Webフックの作成時に移入されます。 必要に応じて、これらの値を編集および変更できます。


lingotek-incoming-webhook.pngの説明は以下のとおりです
「図lingotek-incoming-webhook.pngの説明」

CALベースのWebフック・アダプタの使用

CALベースのwebフック・アダプタは、着信リクエストの詳細をCALネットワークに公開します。

関心のあるコンポーネントは、イベントを消費し、さらに処理できます。 webフックを消費する必要があるコンポーネントは、プロセッサを実装できます。