はじめに

この記事は chillSAP 夏の自由研究2021 の記事として執筆しています。
この記事では以下について説明します。

Event Meshの概要
APIを使用してEvent Meshを操作する方法

1. Event Meshの概要

Event MeshはSAP BTPのサービスで、イベントを介してアプリケーションやサービスをつなぐハブの役割を果たします。

送信側（イベントが発生する側）では、特定のイベントが発生したときにEvent Meshにメッセージを送信する
受信側（イベントが発生したときに通知してほしい側）は、Event Meshのキューを通じてメッセージを受け取る

図：SAP Event Mesh / Conceptsより引用

1.1. Event Meshの利点と用途

Event Meshの利点

Event Meshの利点は、送信側と受信側の連携が非同期に行えるところだと思います。送信側が受信側のサービスを直接呼び出す構成だと、受信側のサービスがダウンしていると、送信側もエラーになってしまいます。Event Meshをかませることで、受信側の状況にかかわらず送信側は処理を続けることができます。

Event Meshの用途

S/4HANAでは、標準トランザクション（たとえばBPマスタ更新や受注伝票更新）をトリガにEvent Meshにメッセージを送ることができます。イベントを受けてBTP上のアプリケーションで何らかの処理をすることができます。
参考：SAP Enterprise Messaging for S/4HANA On-premises

Workflowで承認完了したタイミングでEvent Meshにメッセージを送り、後続処理を起動するといった使い方もできます。
参考：Sending messages to SAP Event Mesh from a workflow

1.2. 重要なコンセプト

Event Meshを利用する上で知っておく必要があるコンセプトについて説明します。

キュー

キューはメッセージをためる「入れ物」で、受信側のアプリケーションと1:1でひもづきます。キューからメッセージを取り出すと当然ながらキューは空になるため、一つのキューを利用できるアプリケーションは一つ、というのが私の認識です。（上の図ではApp1、App2と2つのアプリが紐づいていますが、そんなことができるのかは疑問）

トピック

送信側のアプリケーションは、キューに直接メッセージを投げることも、トピックに対して投げることもできます。キューが「入れ物」だとするとトピックは「点」のイメージです。トピックにはキューが紐づいており、トピックに投げたメッセージはキューに送られ、各キューに紐づくアプリケーションによって消費されます。トピックを使うと、一つのイベントを起点に複数のキューにメッセージを投げることができます。一つのキューを複数のトピックに紐づけることもできます。
トピックにキューを紐づけることを「キューサブスクリプション」と呼びます。

1.3. Event MeshとEnterprise Messaging

Event MeshはかつてEnterprise Messagingという名前でしたが、今年の2月に名称変更されました。コンセプトは変わっていないのですが、アプリケーションの画面が変わりました。以前は画面からキューを作ったりキューサブスクリプションを作ったりできたのですが、今はAPIを使って作成する必要があるようです。

1.4. Event Meshのトライアル版

BTPのトライアルアカウントで使用できるのは、Event Meshのdevプランです。devプランが通常プランと異なるのは、インスタンスを作成する際にnamespaceが設定できないという点です。

通常プランだとインスタンスを作成する際に、以下のようにnamespaceを指定し、キュー名やトピック名の頭にもnamespaceをつけるルールとなっています。

{
    "emname": "<yourmessageclientname>",
    "namespace": "<yourorgname>/<yourmessageclientname>/<uniqueID>",
    "version": "1.1.0",
    "options": {
        "management": true,
        "messagingrest": true,
        "messaging": true
    },
	"rules": {
        "queueRules": {
            "publishFilter": [
                "${namespace}/*"
            ],
            "subscribeFilter": [
                "${namespace}/*"
            ]
        },
        "topicRules": {
            "publishFilter": [
                "${namespace}/*"
            ],
            "subscribeFilter": [
                "${namespace}/*"
            ]
        }
    },
    "resources" : {
    "units" : "10" //default value is 10//
  }
}

一方、トライアル版だとnamespaceの指定がなく、キュー名、トピック名のルールもありません。

{
    "emname": "<yourmessagingclient>",
    "options": {
        "management": true,
        "messagingrest": true,
        "messaging": true
    }
}

2. APIを使用してEvent Meshを操作する

Event MeshのAPIには、キューやキューサブスクリプションを管理するためのManagement APIと、メッセージを送受信するためのMessaging APIがあります。なぜかAPI Business Hubに載っていないので、以下のリンク先をブックマークしておくとよいと思います。

ここでは、APIを利用して以下の操作を行います。

キューを作成
キューサブスクリプションを作成
トピックにメッセージを送信
キューからメッセージを取得

2.1. Event Meshのインスタンスを作成

Service MarketplaceからEvent Meshを選択し、"Create"をクリックします。

Planに"dev"を指定し、インスタンス名は適当に付けます。

パラメータを以下のように指定します。

{
    "emname": "<yourmessagingclient>",
    "options": {
        "management": true,
        "messagingrest": true,
        "messaging": true
    }
}

2.2. サービスキーを作成

登録されたサービスインスタンスを選択してサービスキーを作成します。

登録されたサービスキーの中身は以下のようになっています。
managementセクションにある情報はManagement APIを呼ぶため、messagingセクションの情報はMessaging APIを呼ぶために使います。messagingセクションには3つのかたまりがありますが、これらはEvent Meshで利用可能な3つのメッセージプロトコル（AMQP, MQTT, REST API）に対応しています。

{
    "xsappname": "clone-xbem-service-broker-bbfc4d3b10754cd8ba9f9722389b3269-clone!b54386|xbem-service-broker-!b2436",
    "management": [
        {
            "oa2": {
                "clientid": "xxxx",
                "clientsecret": "xxxx",
                "tokenendpoint": "https://b736177ctrial.authentication.eu10.hana.ondemand.com/oauth/token",
                "granttype": "client_credentials"
            },
            "uri": "https://enterprise-messaging-hub-backend.cfapps.eu10.hana.ondemand.com"
        }
    ],
    "messaging": [
        {
            "oa2": {
                "clientid": "xxxx",
                "clientsecret": "xxxx",
                "tokenendpoint": "https://b736177ctrial.authentication.eu10.hana.ondemand.com/oauth/token",
                "granttype": "client_credentials"
            },
            "protocol": [
                "amqp10ws"
            ],
            "broker": {
                "type": "sapmgw"
            },
            "uri": "wss://enterprise-messaging-messaging-gateway.cfapps.eu10.hana.ondemand.com/protocols/amqp10ws"
        },
        {
            "oa2": {
                "clientid": "xxxx",
                "clientsecret": "xxxx",
                "tokenendpoint": "https://b736177ctrial.authentication.eu10.hana.ondemand.com/oauth/token",
                "granttype": "client_credentials"
            },
            "protocol": [
                "mqtt311ws"
            ],
            "broker": {
                "type": "sapmgw"
            },
            "uri": "wss://enterprise-messaging-messaging-gateway.cfapps.eu10.hana.ondemand.com/protocols/mqtt311ws"
        },
        {
            "oa2": {
                "clientid": "xxxx",
                "clientsecret": "xxxx",
                "tokenendpoint": "https://b736177ctrial.authentication.eu10.hana.ondemand.com/oauth/token",
                "granttype": "client_credentials"
            },
            "protocol": [
                "httprest"
            ],
            "broker": {
                "type": "saprestmgw"
            },
            "uri": "https://enterprise-messaging-pubsub.cfapps.eu10.hana.ondemand.com"
        }
    ],
    "serviceinstanceid": "bbfc4d3b-1075-4cd8-ba9f-9722389b3269"
}

2.3. Management APIを使用する

Management APIを使用してキュー、およびキューサブスクリプションを作成します。以下ではPostmanを使用しますが、事前に"Authorization"タブで以下を設定しておきます。

項目	設定値
Type	OAuth 2.0
Grant Type	Client Credentials
Access Token URL	サービスキーのmanagement.oa2.tokenendpoint
Client ID	サービスキーのmanagement.oa2.clientid
Client Secret	サービスキーのmanagement.oa2.clientsecret

上記項目を設定したら、"Get New Access Token"をクリックしてトークンを取得します。

2.3.1. キューを作成

以下のリクエストを発行し、キューを作成します。Management APIでは、登録、更新はいずれもPUTメソッドを使います。

項目	設定値
メソッド	PUT
URL	サービスキーのmanagement.uri + `/hub/rest/api/v1/management/messaging/queues/<キュー名>`
URLの例：`https://enterprise-messaging-hub-backend.cfapps.eu10.hana.ondemand.com/hub/rest/api/v1/management/messaging/queues/q1`

レスポンス

2.3.2. キューサブスクリプションを作成

上で作成したキューをトピックに紐づけます。

項目	設定値
メソッド	PUT
URL	サービスキーのmanagement.uri + `/hub/rest/api/v1/management/messaging/queues/<キュー名>/subscriptions/<トピック名>`
URLの例：`https://enterprise-messaging-hub-backend.cfapps.eu10.hana.ondemand.com/hub/rest/api/v1/management/messaging/queues/q1/subscriptions/topic1`

レスポンス

2.4. Messaging APIを使用する

続いてMessaging APIを使ってメッセージを送受信してみます。"Authorization"タブに指定する認証情報は、Management APIと同じです。

2.4.1. トピックにメッセージを送信

上で作成したトピックにメッセージを送信します。ボディはどのような形式でも構いませんが、ここではJSON形式にします。URLはサービスキーのmessagingセクションの3つ目の、protocolがhttprestとなっているかたまりのuriを使用します。

項目	設定値
メソッド	POST
URL	サービスキーのmessaging[2].uri + `/messagingrest/v1/topics/<トピック名>/messages`
ヘッダ: Content-Type	application/json
ヘッダ: x-qos(※)	0
※Quality of Serviceを表す項目。値は0または1。

0: 受信確認を必要とせず、キューから受信側へ1回送信したらメッセージを削除する
1: 受信確認がされるまでキューから受信側へメッセージを再送する

参考：https://help.sap.com/viewer/bf82e6b26456494cbdd197057c09979f/Cloud/en-US/3f424ff1ae3b4bc084c4f1ea0be96f54.html

URLの例：https://enterprise-messaging-pubsub.cfapps.eu10.hana.ondemand.com/messagingrest/v1/topics/topic1/messages

ボディ

{
    "message": "hello!",
    "anyProperty": "12345"
}

レスポンス

2.4.2. キューからメッセージを取得

キューからメッセージを取得する方法にはAPIを使う、Webhookサブスクリプションを使う、CAPを使うなどがありますが、ここではAPIを使う方法を紹介します。APIを使う方法は「自らメッセージを取りに行く」プル型の取り方です。これに対してWebhookやCAPは「イベントが発生したらメッセージを受け取る」プッシュ型の取り方です。

注目すべきは「メッセージを取得する」アクションなのにメソッドがPOSTになっている点です。メッセージは取得（消費）されるとキューから削除されるため、実際はキューの更新を伴う操作だからです。

項目	設定値
メソッド	POST
URL	サービスキーのmessaging[2].uri + `/messagingrest/v1/queues/<キュー名>/messages/consumption`
ヘッダ: x-qos	0
URLの例：`https://enterprise-messaging-pubsub.cfapps.eu10.hana.ondemand.com/messagingrest/v1/queues/q1/messages/consumption`

レスポンス

もう一度同じリクエストを実行すると、レスポンスは空になります。キューからは先入れ先出しでメッセージが一つずつ取れます。最後のメッセージが取り出されると、それ以降は空のレスポンスが返ってきます。

次回はCAPを使ってメッセージを送受信する方法について紹介します。

参考

Event Meshのコンセプトについて理解するには、DJ Adams氏の以下の動画がおすすめです。

Diving into messaging on SAP Cloud Platform - Part 1 - Setup and overview