進行中のベータリリース​: クラウド IDE は進行中のベータリリースです​。ベータ状態での Anypoint Code Builder の使用には、IDE で入手できる、該当するベータサービス契約条件が適用されます。

AsyncAPI 仕様の実装

Anypoint Code Builder では、Mule Runtime バージョン 4.6 以降で実行されるプロジェクトでの AsyncAPI 2.6 および 2.0 仕様の実装がサポートされます。プロジェクトを作成して実装すると、Anypoint Code Builder は、Anypoint Exchange でホストされている AsyncAPI 仕様をインポートして、ビジネスニーズに応じてさらに開発可能な実装プロジェクトにスキャフォールディングします。

非同期 API はメッセージブローカーに依存して、異なるサービスまたはコンポーネント間で分離された方法でメッセージを送受信します。このサービスは、受信者または送信者の特定の詳細を知らなくてもメッセージを送受信できるため、非同期の通信が可能になります。受信者および送信者と通信するために、メッセージブローカーは特定のプロトコルを使用します。APIkit for AsyncAPI Module リファレンスの​「サポートされるメッセージブローカー」​を参照してください。

始める前に

スキャフォールディングの基礎

Anypoint Code Builder で AsyncAPI 仕様を実装する前にスキャフォールディングプロセスの概要を理解することが重要です。

AsyncAPI 仕様を Mule プロジェクト (実装またはインテグレーション) にスキャフォールディングすると、Anypoint Code Builder で次の操作が実行されます。

  • AsyncAPI 仕様を調べる

  • 一度に 1 つの仕様を検討する

  • インポートされた仕様を既存の仕様の変更として扱い、再スキャフォールディングのために評価する

  • 仕様内の ​publish​ 操作ごとに個別のフローを使用して新しい Mule プロジェクトを作成する

  • AsyncAPI 仕様に ​publish​ 操作が含まれない場合は、Mule プロジェクトの名前を持つ空の XML ファイルを生成する

  • Mule プロジェクトの ​src/main/resources​ ディレクトリに設定プロパティファイル ​dev-properties.properties​ を生成する

    例: 設定プロパティファイル​を参照してください。

  • APIkit for AsyncAPI モジュール (AsyncAPI モジュール) をプロジェクトで使用できるようにする

    このモジュールでは次の操作が提供されます。

    • Subscribe​ (​<apikit-asyncapi:publish/>​): 仕様内の AsyncAPI ​subscribe​ 操作は AsyncAPI ​Publish​ 操作として設定で使用できます。「例: スキャフォールディング済みフロー」の​実装例​を参照してください。

    • Message Listener​ (​<apikit-asyncapi:message-listener/>​): 仕様内の AsyncAPI ​publish​ 操作は設定可能な ​Message Listener​ 操作です。システムはメッセージをチャネルにパブリッシュし、Mule アプリケーションはこれらのメッセージをリスンします。​例: スキャフォールディング済みフロー​の例を参照してください。

      スキャフォルダーは、各 ​publish​ 操作を ​Message Listener​ 操作に変換し、Mule アプリケーションが指定されたチャネルから読み取り、パブリッシュされたメッセージを処理できるようにします。

  • AsyncAPI モジュールの ​Message Listener​ および ​Publish​ 操作の接続設定と、そのモジュールの基盤となっているコネクタの接続設定が含まれる ​global-configs.xml​ ファイルを生成します。

    例: 接続設定​を参照してください。

スキャフォールディングプロセス中、次の場合にエラーが発生する可能性があります。

  • 仕様でチャネルが定義されていない

  • サポートされないメッセージブローカープロトコルの場合

    サポートされる​プロトコルについては、APIkit for AsyncAPI Module リファレンスの​「サポートされるメッセージブローカー」​を参照してください。

Anypoint Code Builder は、API 仕様から参照される AsyncAPI、Avro、OAS、または JSON スキーマフラグメントファイルのスキャフォールディングをサポートしていません。Exchange から仕様をインポートするときに、スキャフォルダーはこれらのフラグメントをプロジェクトの連動関係として追加しません。ただし、仕様内でインラインで指定されたフラグメントをスキャフォールディングして参照することはできます。Exchange からインポートされた RAML フラグメントは、この制限の影響を受けません。

Mule プロジェクトに AsyncAPI 仕様をスキャフォールディングする

新しいまたは既存の Mule プロジェクトに AsyncAPI 仕様をスキャフォールディングすることができます。

  • 新しい実装プロジェクトに AsyncAPI 仕様をスキャフォールディングするには、​新しいプロジェクトへの AsyncAPI 仕様のスキャフォールディング​の手順を実行します。

  • 既存の Mule プロジェクト (実装またはインテグレーション) に AsyncAPI 仕様をスキャフォールディングまたは再スキャフォールディングするには、​既存のプロジェクトに AsyncAPI 仕様をスキャフォールディングまたは再スキャフォールディングする​を参照してください。再スキャフォールディングは、仕様バージョンを更新して新しい操作やサーバーを導入する場合に役立つ可能性があります。仕様に新しいサーバーが含まれる場合、スキャフォルダーはその新しい設定を Mule プロジェクトに追加します。

    再スキャフォールディングする場合、スキャフォルダーは仕様内のチャネル、サーバー、および ​publish​ 操作と ​subscribe​ 操作のグルーピングの新しい組み合わせに対してアクションを実行しますが、新しくない組み合わせを再スキャフォールディングすることはありません。

新しいプロジェクトへの AsyncAPI 仕様のスキャフォールディング

Anypoint Exchange でホストされている AsyncAPI 仕様から実装プロジェクトを作成します。プロジェクトを作成すると、Anypoint Code Builder は、仕様を、Mule アプリケーションとして実装できるインターフェースにスキャフォールディングします。

  1. 始める前に​の前提条件を満たします。

  2. IDE のアクティビティバーで、​​ (​Anypoint Code Builder​) アイコンをクリックします。

    アクティビティバー内で強調表示されている [Anypoint Code Builder] アイコン
  3. [Quick Actions (クイックアクション)]​ から ​[Implement an API (API を実装)]​ をクリックします。

    *[Getting Started (使用開始)]* セクション内の強調表示された *[Implement an API (API を実装)]*リンク
  4. [Implement an API Specification (API 仕様を実装)]​ フォームに入力します。

    実装プロジェクトの開始フォーム
    項目名 項目値

    Project Name (プロジェクト名)

    プロジェクトの一意の名前。

    この名前はタイトルおよびプロジェクトファイルの名前として使用されます。 たとえば、プロジェクト名が​「My Project (私のプロジェクト)」​の場合、プロジェクトファイル名は ​my-project​ になります。

    Project Location (プロジェクトの場所)

    ホームディレクトリまたは作成する別のディレクトリ。

    別のプロジェクトディレクトリ内にプロジェクトを作成しないでください。

    Search an API Specification from Exchange (Exchange から API 仕様を検索)

    Exchange の仕様の名前。​[Show filters (検索条件を表示)]​ をアクティブ化して、検索結果を絞り込みます。詳細は、『検索結果の絞り込み』を参照してください。

    Mule Runtime

    プロジェクトに使用する Mule Runtime バージョン。

    Java Version (Java バージョン)

    Mule に使用する Java バージョン。

    サポートされている Mule Runtime と Java バージョンのいずれかを選択できます。IDE は、バージョン設定をプロジェクトの ​mule-artifact.json​ ファイルに保存します。

  5. Exchange で API 仕様を検索します。

    1. API 仕様の名前の入力を開始します。

    2. Enter キーを押して、検索結果のリストを表示します。

    3. [Add Asset (アセットを追加)]​ をクリックして、選択した API 仕様を追加します。

      Exchange でサポートされるバージョンの AsyncAPI 仕様のみがスキャフォールディングに使用できます。サポートされないバージョンは検索結果に表示されません。

      Exchange にある AsyncAPI 仕様アセットのリスト

  6. [Create Project (プロジェクトを作成)]​ をクリックします。

    プロジェクトを作成すると、Anypoint Code Builder で次の操作が実行されます。

    • API 仕様を新しい Mule プロジェクトにスキャフォールディングします。この Mule プロジェクトが開き、スキャフォールディング済みフローを含む設定 XML ファイル (​flows.xml​) が表示されます。次に例を示します。

      IDE 内の AsyncAPI 実装プロジェクト

      設定 XML ファイルには、実装プロジェクトのインターフェースが含まれ、フローには仕様内の各 ​publish​ 操作の Message Listener (​<apikit-asyncapi:message-listener/>​) 設定が含まれます。

    • プロジェクトの ​pom.xml​ ファイルに API 仕様を連動関係として追加します。次に例を示します。

      <dependency>
          <groupId>e21dd38b-8231-45bf-aaa7-abde2072d538</groupId>
          <artifactId>my-asyncapi-example</artifactId>
          <version>1.0.0</version>
          <classifier>evented-api</classifier>
          <type>zip</type>
      </dependency>
      xml
    • Mule と Java のバージョンをプロジェクトの ​mule-artifact.json​ ファイルに追加します。次に例を示します。

      {
          "minMuleVersion": "4.7.0",
          "javaSpecificationVersions": [
            "17"
          ]
      }
      json
  7. Mule アプリケーション内でこのインターフェースを実装するためのビジネスロジックを指定します。

    ユースケースのニーズに応じて、コネクタ操作と処理コンポーネントを設定することでビジネスロジックを定義します。設定プロパティ値を ​dev-properties.properties​ ファイルに提供します。必要に応じて、処理要件の追加のフローまたはサブフローを作成および設定します。

    コンポーネントの設定、デバッグ、アプリケーションの単体テストの実行、およびその他のタスクに関する指針については、​『インテグレーションの開発』. For information about connectors and processors for configuring your business logic, see 『参照』​を参照してください。

    Mule アプリケーション内で一部の注文を処理するための AsyncAPI 仕様、スキャフォールディング済みインターフェース、ビジネスロジックの例については、​​を参照してください。

既存のプロジェクトに AsyncAPI 仕様をスキャフォールディングまたは再スキャフォールディングする

AsyncAPI 仕様を Exchange から Anypoint Code Builder の既存のプロジェクトにスキャフォールディングまたは再スキャフォールディングします。再スキャフォールディングする前に、どの新しい設定がプロジェクトにスキャフォールディングされるかに関する​重要なメモ​を確認してください。

  1. 始める前に​の前提条件を満たします。

    IDE で AsyncAPI 機能を使用するには、Anypoint Platform 組織のシステム管理者による有効化が必要です。

  2. Anypoint Code Builder でプロジェクトを開きます。

  3. コマンドパレットを開きます。

  4. 次のコマンドを入力します。

    MuleSoft: Import Asset from Exchange
    command
  5. アセットのリストから ​[AsyncAPI]​ を選択します。

  6. Anypoint Platform にログインするように促されたら、ログインし、拡張機能で外部 Web サイトにサインインして開くことおよび Visual Studio Code を開くことを許可します。

  7. 仕様の完全な名前または部分的に一致する名前を入力します。次に例を示します。

    My AsyncAPI Spec
  8. 名前に一致するアセットのリストが IDE に読み込まれるまで待機した後、対象の AsyncAPI 仕様を選択します。

    Exchange でサポートされるバージョンの AsyncAPI 仕様のみがスキャフォールディングに使用できます。サポートされないバージョンは検索結果に表示されません。

  9. バージョンを要求されたら、インポートする API のバージョン (​1.0.0​ または ​2.0.0​ など) を選択します。

  10. API 連動関係をスキャフォールディングするように促されたら、​[Yes (はい)]​ を選択します。

    スキャフォールディングプロセスが完了したら、IDE が開き、スキャフォールディング済みフローを含む設定 XML ファイル (​flows.xml​) が表示されます。仕様を再スキャフォールディングした場合は、どの新しい設定がプロジェクトにスキャフォールディングされるかについての​重要なメモ​を確認してください。

  11. Mule アプリケーション内でこのインターフェースを実装するためのビジネスロジックを指定します。

    ユースケースのニーズに応じて、コネクタ操作と処理コンポーネントを設定することでビジネスロジックを定義します。設定プロパティ値を ​dev-properties.properties​ ファイルに提供します。必要に応じて、処理要件の追加のフローまたはサブフローを作成および設定します。

    コンポーネントの設定、デバッグ、アプリケーションの単体テストの実行、およびその他のタスクに関する指針については、​『インテグレーションの開発』. For information about connectors and processors for configuring your business logic, see 『参照』​を参照してください。

    Mule アプリケーション内で一部の注文を処理するための AsyncAPI 仕様、スキャフォールディング済みインターフェース、ビジネスロジックの例については、​​を参照してください。

実装のデプロイ

実装を CloudHub および CloudHub 2.0 または別のホストにデプロイします。CloudHub または CloudHub 2.0 には ​『Anypoint Code Builder』​ からデプロイすることができます。他のデプロイメントオプションについては、『デプロイメントオプション』を参照してください。

この例では、注文を処理し、注文状況の通知をメールと Slack で送信するための API 仕様と実装について説明します。

  • 例: AsyncAPI 2.6 仕様

    AsyncAPI 仕様では、Anypoint MQ と Kafka プロトコルを使用する注文処理 API を定義します。

  • 例: スキャフォールディング済みフロー

    スキャフォルダーは、AsyncAPI 仕様内の各 ​publish​ 操作のフローが含まれる ​flow.xml​ ファイルを生成します (再スキャフォールディングについては、​Mule プロジェクトに AsyncAPI 仕様をスキャフォールディングする​を参照)。この例では、生成されたフローについて説明し、注文処理ロジックをいくつかのフローに提供するコンポーネントを設定します。

  • 例: 接続設定

    スキャフォルダーは、フロー内の ​Message Listener​ および ​Publish​ 操作の接続設定と、Apache Kafka 用 Anypoint Connector (Apache Kafka Connector) や Anypoint MQ 用 Anypoint Connector (Anypoint MQ Connector) などのコネクタの接続設定を含む ​global-configs.xml​ ファイルを生成します。この例では、ファイルのコンテンツについて説明し、Email Connector および Slack Connector 操作の接続設定を追加します。

  • 例: 設定プロパティファイル

    スキャフォルダーは Mule プロジェクトの ​src/main/resources​ ディレクトリに ​dev-properties.properties​ ファイルを生成します。この例では、生成されたファイルについて説明し、メール通知と Slack 通知で使用する設定プロパティをファイルに追加します。

  • 例: 通知サブフロー

    notifications.xml​ のサブフロー (​<sub-flow/>​) では、​『メール用 Anypoint Connector (Email Connector)』​ と ​『Slack 用 Anypoint Connector (Slack Connector)』​ を使用して、メールと Slack で注文確認メッセージを送信するビジネスロジックを実装します。

例: AsyncAPI 2.6 仕様

次の例では、Anypoint MQ と Kafka プロトコルを使用する API 仕様を定義します。この仕様では、Anypoint MQ を使用する注文 (新規、確認済み、およびキャンセル済み注文) 用の チャネルLeaving the Site​と、取り寄せ注文 (在庫にない品目) 用に Kafka を使用するチャネルを定義します。各チャネルに ​publish​ および ​subscribe​ 操作が含まれます。仕様の サーバーLeaving the Site​設定では、AsyncAPI モジュールの操作を介してイベントをパブリッシュまたはサブスクライブするときに (​間接的に​) 使用するコネクタを決定するメッセージブローカーを定義します。

1 AMQ-prod​ では、Anypoint MQ ブローカーを設定します。

MQ ブローカーの URL は、キューを作成するときに選択したリージョンで見つけることができます。​「キューを作成する」​の​コピー​ボタンと、『クライアントアプリケーションの設定』を参照してください。

2 Kafka-prod​ では、ローカルでホストされた Kafka ブローカーを設定します。
3 order-placed​ では、注文をパブリッシュ (リスン) およびサブスクライブ (パブリッシュ) するための Anypoint MQ チャネルを設定します。​order-cancelled​ チャネルと ​order-confirmed​ チャネルは同様に設定されます。
4 order-backordered​ では、取り寄せ注文をパブリッシュ (リスン) およびサブスクライブ (パブリッシュ) するための Kafka チャネルを設定します。
5 components​ では、​OrderPlaced​、​OrderCancelled​、​OrderConfirmed​、​BackOrder​ を含むさまざまな注文種別のメッセージの構造を定義します。

例: スキャフォールディング済みフロー

仕様を実装プロジェクトにスキャフォールディングすると、Anypoint Code Builder は各 ​publish​ 操作のフロー (​<flow/>​) を作成し、​publish​ 操作を APIkit の AsyncAPI モジュールの ​Message Listener​ ソース (​<apikit-asyncapi:message-listener/>​) に変換します。各フローには ​Logger​ コンポーネントも含まれます。このモジュールについての詳細は、『APIkit for AsyncAPI モジュールリファレンス』を参照してください。

スキャフォルダーは仕様から ​flow.xml​ ファイルを生成します。キャフォルダーは ​AsyncAPI 仕様例​から次の XML を生成します。

1 <apikit-asyncapi:server value="AMQ-prod" />​ の ​AMQ-prod​ は Anypoint MQ サーバー接続を識別します。詳細は、​例: 接続設定​を参照してください。
2 <apikit-asyncapi:server value="Kafka-prod" />​ の ​Kafka-prod​ は Kafka サーバー接続を識別します。詳細は、​例: 接続設定​を参照してください。

次の例では、ビジネスロジックをスキャフォールディング済みフローに追加します。

  • LISTEN:listen-order-placed​ は注文をリスンします。トリガーされると、DataWeave 式を使用して十分な在庫があるかどうかを確認します。在庫に十分な品目が存在する場合、フローで注文データを ​order-confirmed​ チャネルにパブリッシュする ​Publish​ 操作が設定され、​LISTEN:listen-order-confirmations​ フローがトリガーされます。存在しない場合、フローで注文データを ​order-backordered​ チャネルにパブリッシュする ​Publish​ 操作が追加され、​LISTEN:listen-order-backordered​ フローがトリガーされます。

  • LISTEN:listen-order-confirmations​ は注文確認をリスンします。トリガーされると、注文情報を ​notification-flow​ サブフローに送信し、このサブフローで Slack とメールを介して確認通知が送信されます (​例: 通知サブフロー​を参照)。

1 注文によりフロー ​LISTEN:listen-order-placed​ 内の Message Listener がトリガーされると、HTTP 要求操作 (​<http:request/>​) で在庫データが要求されて対象変数 ​inventory​ に保存されます。
2 Choice コンポーネント (​<choice/>​) では、対象変数 (​vars.inventory.stockDetails.availableStock​) の ​availableStock​ 値を注文ペイロード (​payload.items.quantity[0]​) の ​quantity​ 値と照合します。​quantity​ 値は、フローをトリガーする ​OrderPlaced​ メッセージから取得されます。

十分な在庫がある場合、Set Payload コンポーネント (​<set-payload/>​) で確認メッセージを設定します。この確認メッセージは ​Publish​ 操作 (​<apikit-asyncapi:publish/>​) で ​order-confirmed​ チャネルに送信され、そのチャネルで ​LISTEN:listen-order-confirmations​ フローがトリガーされます。ない場合、フローでメッセージが ​order-backordered​ チャネルにパブリッシュされ、そのチャネルでフロー ​LISTEN:listen-order-backordered​ がトリガーされます。

3 フロー ​LISTEN:listen-order-confirmations​ の Message Listener は Anypoint MQ チャネル ​order-confirmed​ のアクティビティをリスンします。トリガーされると、フローでその ​<set-payload/>​ コンポーネントが設定されて注文確認メッセージが作成されます。Flow Reference (​<flow-ref/>​) でこのメッセージが ​notification-flow​ サブフローでの処理のために送信されます。
4 在庫が十分でない場合、​LISTEN:listen-order-placed​ によってフロー ​LISTEN:listen-order-backordered​ がトリガーされます。

例: 接続設定

スキャフォールディングプロセスでは、仕様で定義されたサーバー接続設定用の ​global-configs.xml​ を生成します。

<apikit-asyncapi:config/>​ 内の AsyncAPI モジュールの接続設定は Kafka Cnnector および Anypoint MQ Cnnector の接続設定を参照します。スキャフォールディングプロセスでは、AsyncAPI 仕様内の serverLeaving the Site​ および channelLeaving the Site​ 設定に基づいてコネクタをプロジェクトに追加します。

  • 指定されたチャネルとサーバーの組み合わせにパブリッシュする場合、フローの ​Publish​ 操作 (​<apikit-asyncapi:publish/>​) で接続設定が使用されます。フローで ​Kafka-prod​ または ​AMQ-prod​ サーバーの Kafka および Anypoint MQ チャネルにパブリッシュします。

  • フローの ​Message Listener​ 操作 (​<apikit-asyncapi:message-listener/>​) は、サーバーの ​value​ 設定 (​Kafka-prod​ または ​AMQ-prod​) に基づいて指定されたチャネルをリスンするように自動的に設定されます。この値は、AsyncAPI 接続設定 (​<apikit-asyncapi:config/>​) の ​serverKey​ 設定のいずれかに一致します。

ビジネスロジックをスキャフォールディング済みプロジェクトに追加する場合、アプリケーション内のフローまたはサブフローに追加するコネクタ操作など、他の接続設定を ​global-configs.xml​ に追加できます。次の例では、​『HTTP』​、​『Email』​、​『Slack』​ Connector 操作の接続設定を追加します。これらの設定プロパティ (​${email.password}​ など) は​プロパティファイル​で定義できます。

<!-- additional connection configuration examples -->
  <http:request-config name="HTTP_Request_config" basePath="path" > (1)
    <http:request-connection protocol="HTTP" host="example.com" />
  </http:request-config>

  <http:listener-config name="HTTP_Listener_config" > (2)
    <http:listener-connection host="0.0.0.0" port="8081" />
  </http:listener-config>

  <email:smtp-config name="Email_SMTP"> (3)
    <email:smtps-connection host="smtp.gmail.com" password="${email.password}" user="${email.username}">
      <tls:context>
        <tls:trust-store insecure="true"></tls:trust-store>
      </tls:context>
    </email:smtps-connection>
  </email:smtp-config>

  <slack:config name="Slack_Config"> (4)
    <slack:token-connection token="${slack.token}" />
  </slack:config>
xml
1 HTTP 要求接続設定例
2 HTTP リスナー接続設定例
3 メール SMTP 接続設定例
4 Slack 接続設定例

例: 設定プロパティファイル

Anypoint Code Builder は実装プロジェクトの ​src/main/resources​ ディレクトリに ​dev-properties.properties​ ファイルを生成します。

仕様例​では、Anypoint MQ ブローカーのサーバー設定を定義します。Anypoint MQ キューをリスンし、Anypoint MQ キューにメッセージをパブリッシュするには、​『MQ クライアントアプリケーション』​の ​clientAppId​ と ​clientSecret​ を指定する必要があります。スキャフォールディングプロセス中に、関連付けられた ​api-path​ 設定が自動的に生成されます。

#Fri Jun 07 09:32:50 PDT 2024
anypointmq.server.AMQ-prod.clientAppId=
anypointmq.server.AMQ-prod.clientSecret=
api.path=resource\:\:e21dd38b-8231-45bf-aaa7-abde2072d538\:my-asyncapi-example\:1.0.0\:evented-api\:zip\:anypointmq-kafka-orders-demo-final.yaml
properties

このファイルに他のプロパティを追加できます。​email​ と ​slack​ の例は、​通知サブフロー​の Email Connector および Slack Connector 操作用です。

#Fri Jun 07 17:05:33 PDT 2024
anypointmq.server.AMQ-prod.clientAppId=my_client_app_id_here
anypointmq.server.AMQ-prod.clientSecret=my_client_app_secret_here
slack.token=my_slack_token_here
email.host=smtp.gmail.com
email.username=me@gmail.com
email.password=my_gmail_password_here
api.path=resource\:\:8dbc2756-83d6-4a1c-91c4-6eafbe7d7ae0\:async-amq-kafka-orders\:1.0.2\:evented-api\:zip\:anypointmq-kafka-orders-demo-compliant.yaml
properties

パスワードや他の機密データのセキュアプロパティを含む設定プロパティについての詳細は、『Mule アプリケーションのプロパティの定義および保護』を参照してください。

例: 通知サブフロー

notifications.xml​ のサブフロー (​<sub-flow/>​) では、メールおよび Slack で注文確認メッセージを送信するためのビジネスロジックを実装します。このファイルはスキャフォルダーでは生成されません。

LISTEN:listen-order-confirmations​ フローの Flow Reference コンポーネント (​<flow-ref/>​) によってトリガーされた場合、通知サブフローで注文確認メッセージが送信されます。

1 LISTEN:listen-order-confirmations​ フローから出力されたペイロードを、確認メッセージデータを取得する Mule 変数に変換します。
2 Slack Connector から ​<slack:post-message/>​`* 操作を使用して Slack 確認メッセージを投稿します。
3 Email Connector から ​<email:send/>​ 操作を使用して確認メッセージをメール送信します。