AsyncAPI 仕様の作成およびインポート

Anypoint Exchange にパブリッシュする前に Anypoint Code Builder を使用して AsyncAPI 仕様の設計、インポート、管理、テストを行います。

IDE から Anypoint Code Builder で AsyncAPI 仕様プロジェクトを作成および設計するか、MuleSoft VCS から仕様をインポートして AsyncAPI 仕様プロジェクトを作成します。
- IDE から AsyncAPI 仕様プロジェクトを作成および設計する
- MuleSoft VCS から AsyncAPI 仕様をインポートする
出力パネルで進行状況を追跡します。
API Console で仕様を確認します。

Anypoint Code Builder の機能を調べるには、asyncapi-example API 仕様を使用してください。

始める前に

Web またはデスクトップ IDE をセットアップしてアクセスします。
AsyncAPI 仕様の設計の基礎を理解します。
ビジネスグループに精通します。

API 仕様を Anypoint Code Builder から Exchange にパブリッシュすると、IDE でビジネスグループの名前が要求されます。ビジネスグループを参照してください。

新しい AsyncAPI 仕様プロジェクトを作成および設計する

Anypoint Code Builder で AsyncAPI 仕様プロジェクトを作成および設計する手順は、次のとおりです。

IDE のアクティビティバーで、 (Anypoint Code Builder) アイコンをクリックします。
[Quick Actions (クイックアクション)] から [Design an API (API を設計)] をクリックします。

[API Specification (API 仕様)] フォームに入力します。

項目名項目値

項目名	項目値
Project Name (プロジェクト名)	プロジェクトの一意の名前。この名前は Exchange での AsyncAPI 仕様のタイトル、仕様ファイルの名前、プロジェクトのルートディレクトリの名前として使用されます。たとえば、プロジェクト名が「AsyncAPI Example」 (AsyncAPI 例) の場合、仕様ファイル名は `asyncapi-example` になります。既存のプロジェクト名を再利用するには、その名前をすでに使用しているプロジェクトを最初に削除する必要があります。API 仕様とフラグメントの削除を参照してください。
Project Location (プロジェクトの場所)	ホームディレクトリまたは作成する別のディレクトリ。ホームディレクトリへのフォルダーの追加を参照してください。別のプロジェクトディレクトリ内にプロジェクトを作成しないでください。
API Type (API 種別)	作成する API 仕様のエンティティの種別。使用可能なオプションは、[REST API] と [AsyncAPI] です。この手順でサンプルを使用するには、[AsyncAPI] を選択します。
API Specification Language (API 仕様言語)	「サポートされる AsyncAPI バージョン」を参照してください。この手順でサンプルを使用するには、[AsyncAPI 2.6 (YAML)] を選択します。

Project Name (プロジェクト名)

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

この名前は Exchange での AsyncAPI 仕様のタイトル、仕様ファイルの名前、プロジェクトのルートディレクトリの名前として使用されます。たとえば、プロジェクト名が「AsyncAPI Example」 (AsyncAPI 例) の場合、仕様ファイル名は asyncapi-example になります。

既存のプロジェクト名を再利用するには、その名前をすでに使用しているプロジェクトを最初に削除する必要があります。API 仕様とフラグメントの削除を参照してください。

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

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

ホームディレクトリへのフォルダーの追加を参照してください。

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

API Type (API 種別)

作成する API 仕様のエンティティの種別。

使用可能なオプションは、[REST API] と [AsyncAPI] です。

この手順でサンプルを使用するには、[AsyncAPI] を選択します。

API Specification Language (API 仕様言語)

「サポートされる AsyncAPI バージョン」を参照してください。

この手順でサンプルを使用するには、[AsyncAPI 2.6 (YAML)] を選択します。

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

確認を促されたら、フォルダー内のファイルの作成者を信頼します。

プロジェクトの編集準備が整ったら、API プロジェクトのエディタービューで次の AsyncAPI 2.6 (YAML) 仕様のような仕様が開きます。
引き続き API 仕様を設計します。

要素を入力するときに、オートコンプリート (Ctrl+Space) を使用すると、コンテキスト内で使用可能なオプションが表示されます。

MuleSoft VCS から AsyncAPI 仕様をインポートする

MuleSoft VCS から AsyncAPI 仕様をインポートし、デスクトップまたはクラウド IDE で Git または VS Code と互換性のある別のソース管理システムを使用して、プロジェクトの同期を維持します。詳細は、API 設計プロジェクトのソース制御を参照してください。

コマンドパレットを開きます。
手順を表示
- キーボードショートカットを使用する。
  
  Mac: Cmd+Shift+p
  
  Windows: Ctrl+Shift+p
- デスクトップ IDE で、[View (表示)] > [Command Palette (コマンドパレット)] を選択する。
- クラウド IDE で、 (メニュー) アイコンをクリックし、[View (表示)] > [Command Palette (コマンドパレット)] を選択する。

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

MuleSoft: Import API Specification from MuleSoft VCS

Anypoint Platform にログインするように促されたら、IDE からログインします。
インポートプロセスを完了します。
1. [Select a Business Group (ビジネスグループを選択)] ポップアップからビジネスグループを選択します。
2. [APIs from MuleSoft VCS (MuleSoft VCS から API)] 項目で API 仕様を検索します。
3. 仕様のフォルダーに移動するか、そのフォルダーを作成して、[Select target folder (対象フォルダーを選択)] をクリックします。
  
  インポートが失敗したといったエラー (「Importing project a_project_name has failed (プロジェクト a_project_name のインポートに失敗しました)」) を受け取ったら、同じ名前のプロジェクトの対象フォルダーを確認します。インポートする前に重複する名前の問題に対処するには、設計プロジェクトを別の対象フォルダーにインポートするか、プロジェクトを IDE から削除することができます (API 仕様とフラグメントの削除を参照)。
必要に応じて、仕様を編集するか、引き続き仕様を設計します。

要素を入力するときに、オートコンプリート (Ctrl+Space) を使用すると、コンテキスト内で使用可能なオプションが表示されます。
必要に応じて、Anypoint SCM を使用して変更内容を同期します。

この機能は、MuleSoft VCS からインポートした API プロジェクトでのみ使用できます。作業内容を別の SCM に保存することもできます。SCM オプションについては、ソースファイルの制御を参照してください。

出力パネルで進行状況を追跡する

API を設計しているときに内部処理の進行状況を追跡する手順は、次のとおりです。

出力パネルを開きます。
手順を表示
- キーボードショートカットを使用する。
  
  Mac: Cmd+Shift+u
  
  Windows: Ctrl+Shift+u
- デスクトップ IDE で、[View (表示)] > [Output (出力)] を選択する。
- クラウド IDE で、 (メニュー) アイコンをクリックし、[View (表示)] > [Output (出力)] を選択する。
ドロップダウンから [Mule DX Server (Mule DX サーバー)] を選択します:

API Console で仕様を確認する

コンソールに仕様を表示する手順は、次のとおりです。

エディターで仕様ファイルをクリックします。
(API Console) アイコンをクリックします。

または、コマンドパレットでコマンド MuleSoft: API Console を入力することができます。
API Console にチャネルが表示されるまで待機します。

API Console に仕様のチャネルが表示されます。次に例を示します。

1 チャネルをクリックして詳細を表示します。

2 コンソールメニューを表示します。
コンソールでチャネルをクリックするか、メニューから項目を選択して、仕様のさまざまな部分を表示します。たとえば、[PUBLISH] をクリックすると、次のように表示されます。

AsyncAPI (YAML) API 仕様の例

AsyncAPI 2.6 (YAML) プロジェクトを作成したら、初期仕様を次のコード例で置き換えることができます。

AsyncAPI 2.6 (YAML) 仕様の例

asyncapi: '2.6.0' (1)
info:
  title: Orders AsyncAPI
  version: '1.0.0'
  description: Orders API
  license:
    name: Anypoint MQ
    url: https://license.com
  contact:
    name: Max Muley
    email: max@salesforce.com
    url: http://salesforce.com
defaultContentType: application/json
tags:
  - name: Orders API
    description: API for orders
servers: (2)
  AMQ-prod:
    url: https:://your_MQ_server_URL_here
    protocol: anypointmq
    protocolVersion: v1
    description: Anypoint MQ broker
  kafka-prod:
    url: your_kafka_URL_here
    protocol: kafka
    description: kafka broker
  sfpubsub-prod:
      protocol: salesforcepubsub
      protocolVersion: v1
      url: api.pubsub.salesforce.com
      description: Salesforce pub sub for Platform events production
  solace-server:
    protocol: solace
    variables:
      port:
        enum:
        - '1000'
    bindings:
      solace:
        msgVpn: your_solace_vpn_here
        bindingVersion: 0.4.0
    protocolVersion: 1.0.0
    url: mySolaceURL
channels: (3)
  order-placed:
    description: new orders channel
    servers:
      - AMQ-prod
    publish:
      operationId: listen-order-placed
      description: listen for new order events
      summary: Order Placed Event
      message:
        $ref: '#/components/messages/OrderPlaced'
    subscribe:
      operationId: publish-order-placed
      description: publish new order events
      summary: Order Placed Event
      message:
        $ref: '#/components/messages/OrderPlaced'
  order-updated:
    description: updated orders channel
    servers:
      - solace-server
    publish:
      operationId: listen-order-updated
      description: listen for updated order events
      summary: Order updated Event
      bindings:
        solace:
          bindingVersion: 0.3.0
          destinations:
          - destinationType: queue
            queue:
              name: listen-order-updated
              topicSubscriptions:
              - acmeretail/onlineservices/order/updated/v1/*/*
              - acmeretail/onlineservices/order/updated/v2/*/*
      message:
        $ref: '#/components/messages/OrderUpdated'
    subscribe:
      operationId: publish-order-updated
      description: publish updated order events
      summary: Order updated Event
      bindings:
        solace:
          bindingVersion: 0.3.0
          destinations:
          - destinationType: queue
            queue:
              name: C360.CUSTOMERS
              topicSubscriptions:
              - acmeretail/onlineservices/order/updated/v1/*/*
              - acmeretail/onlineservices/order/updated/v2/*/*
      message:
        $ref: '#/components/messages/OrderUpdated'
  order-cancelled:
    description: orders cancelled channel
    servers:
      - AMQ-prod
    publish:
      operationId: listen-order-cancellations
      description: listen for order cancellation events
      summary: Order Cancelled Event
      message:
        $ref: '#/components/messages/OrderCancelled'
    subscribe:
      operationId: publish-order-cancellations
      description: publish order cancellation events
      summary: Order Cancelled Event
      message:
        $ref: '#/components/messages/OrderCancelled'
  order-confirmed:
    description: orders confirmed channel
    servers:
      - sfpubsub-prod
    publish:
      operationId: listen-order-confirmations
      description: listen for order confirmation events
      summary: Order Confirmed Event
      message:
        $ref: '#/components/messages/OrderConfirmedSub'
    subscribe:
      operationId: publish-order-confirmations
      description: publish order confirmation events
      summary: Order Confirmed Event
      message:
        $ref: '#/components/messages/OrderConfirmedPub'
  order-backordered:
    servers:
      - kafka-prod
    description: orders backordered channel
    publish:
      operationId: listen-order-backordered
      description: listen for backorder events
      summary: Backorder Event
      message:
        $ref: '#/components/messages/BackOrder'
    subscribe:
      operationId: publish-order-backordered
      description: publish backorder events
      summary: Backorder Event
      message:
        $ref: '#/components/messages/BackOrder'
components: (4)
  messages:
    OrderPlaced:
      payload:
        type: object
        properties:
          orderId:
            type: string
          customerName:
            type: string
          email:
            type: string
          items:
            type: array
            items:
              type: object
              properties:
                productId:
                  type: string
                productName:
                  type: string
                quantity:
                  type: integer
                price:
                  type: number
              required: [productId, productName, quantity, price]
              additionalProperties: false
        required: [orderId, customerName, email, items]
        additionalProperties: false
    OrderConfirmedPub:
      summary: order message pub
      contentType: application/json
      payload:
        type: array
        orderconfirmation:
          type: object
          properties:
            orderId__c:
              type: string
            email__c:
              type: string
            required: [orderId, email]
            additionalProperties: false
    OrderConfirmedSub:
      summary: order message sub
      contentType: application/json
      payload:
        type: object
        properties:
          event:
            type: object
            properties:
              orderId__c:
                type: string
              email__c:
                type: string
        required: [orderId, email]
        additionalProperties: false
    OrderCancelled:
      payload:
        type: object
        properties:
          orderId:
            type: string
          email:
            type: string
          reason:
            type: string
        required: [orderId, email, reason]
        additionalProperties: false
    BackOrder:
      payload:
        type: object
        properties:
          orderId:
            type: string
          email:
            type: string
        required: [orderId, email]
        additionalProperties: false
    OrderUpdated:
      contentType: application/json
      description: Shows changes to customer information including name, address and
        loyalty status
      payload:
        "$ref": "#/components/schemas/Order_JSON"
      schemaFormat: application/vnd.aai.asyncapi+json;version=2.0.0
      x-ep-application-domain-id: p4oo2ehrcpf
      x-ep-application-domain-name: OnlineServices
      x-ep-custom-attr-confidential: 'true'
      x-ep-event-id: 66gdcid5pht
      x-ep-event-name: Customer Created
      x-ep-event-state-id: '2'
      x-ep-event-state-name: RELEASED
      x-ep-event-version: 2.0.2
      x-ep-event-version-displayname: ''
      x-ep-event-version-id: 29btjydowi0
      x-ep-shared: 'true'
  schemas:
    Order_JSON:
      "$schema": http://json-schema.org/draft-07/schema#
      properties:
        customer_id:
          description: The unique identifier of the customer
          type: string
        insight_description:
          description: A brief description of the insight
          type: string
        insight_type:
          description: The type of insight (e.g., demographic, behavioral, transactional)
          type: string
        insight_value:
          description: The value or result of the insight
          type: string
        timestamp:
          description: The timestamp when the insight was generated
          format: date-time
          type: string
      required:
      - customer_id
      - insight_type
      - insight_description
      - insight_value
      - timestamp
      title: CustomerInsight
      type: object
      x-ep-application-domain-id: a3hbbd7unz2
      x-ep-application-domain-name: Customer360
      x-ep-schema-id: 6dqkacw0k70
      x-ep-schema-name: Customer Insight
      x-ep-schema-state-id: '1'
      x-ep-schema-state-name: DRAFT
      x-ep-schema-version: 0.1.0
      x-ep-schema-version-displayname: ''
      x-ep-schema-version-id: u15ylfss2qx
      x-ep-shared: 'false'

1	AsyncAPI API モデルを AsyncAPI として識別し、API 仕様のタイトルとバージョンを指定します。
2	サーバー AsyncAPI モジュールの操作を介してイベントをパブリッシュまたはサブスクライブするときに (間接的に) 使用するコネクタを決定するメッセージブローカーを定義します。 `AMQ-prod` では、Anypoint MQ ブローカーを設定します `Kafka-prod` では、ローカルでホストされた Kafka ブローカーを設定します `sfpubsub-prod` では、Salesforce Pub/Sub ブローカーを設定します `solace-server` では Solace PubSub+ ブローカーを設定します
3	Channels (チャネル) バインドを定義します。 `order-placed` では、新しい注文をパブリッシュおよびサブスクライブするための Anypoint MQ チャネルを設定します。 `order-updated` では、注文の更新をパブリッシュおよびサブスクライブするための Solace PubSub+ チャネルを設定します `order-cancelled` では、キャンセル済み注文をパブリッシュおよびサブスクライブするための Anypoint MQ チャネルを設定します `order-confirmed` では、注文確認イベントをパブリッシュおよびサブスクライブするための Salesforce Pub/Sub チャネルを設定します `order-backordered` では、取り寄せ注文をパブリッシュおよびサブスクライブするための Kafka チャネルを設定します
4	コンポーネント `OrderPlaced`、`OrderConfirmedPub`、`OrderConfirmedSub`、`OrderCancelled`、`BackOrder`、`OrderUpdated` を含むさまざまな注文種別のメッセージの構造を定義します