Maven を使用したアセットのパブリッシュ

可能な場合は、Equality の会社の値に一致するように、含めない用語を変更しました。顧客の実装に対する影響を回避するために、一部の用語は変更されていません。

Anypoint Exchange の Maven Facade API​ を使用すると、Apache Maven クライアントでは次のアセットタイプを含め Exchange アセットをパブリッシュおよびコンシュームできます。

  • コネクタ

  • Mule アプリケーション

  • テンプレート

  • ポリシー

  • カスタムアセット

Exchange の Maven Facade API では、アセットの削除はサポートされません。アセットを削除するには、Exchange ユーザインターフェースまたは Exchange API を使用します。

Exchange の Maven Facade API では、動的パラメータはサポートされません。たとえば、アセットバージョンを ​1.0.${revision}​ に設定することはできません。

<name>​ と ​<description>​ 以外の項目の動的パラメータはサポートされていません。更新されたアセットに親が定義されている場合、動的パラメータが適切な解釈されるには、親が有効で Exchange アセットがすでにアップロードされている必要があります。

新しいアセットは、組織の​アセット制限​に含まれます。

前提条件

このドキュメントを活用するには、読者は Maven、プログラミングの概念、およびコンピュータやサーバでのコマンドライン操作に精通している必要があります。

POM ファイルに必要なプラグイン ​org.mule.tools.maven.mule-maven-plugin​ を含めてください。POM ファイルまたは設定ファイルにプラグイン ​org.apache.maven.plugins.maven-deploy-plugin​ を含めないでください。必要なプラグインとの互換性がありません。

Anypoint Exchange の Maven Facade API バージョン 3 を使用してアセットを Exchange にパブリッシュする場合、Mule Maven プラグインバージョン 3.5.0 以降が必要です。

アセットをパブリッシュするには、一意のアーティファクト名と組織 ID が必要です。

US クラウドおよび EU クラウドでは、例のように少し異なる URL が使用されます。

組織 ID を参照する

Maven POM ファイルの要素を作成するには、組織 ID を判断する必要があります。

  1. Anypoint Platform にログインし、​[Access Management (アクセス管理)]​ をクリックします。

  2. 最上位組織またはビジネスグループの名前をクリックし、[organization information (組織情報)] 画面の組織 ID を参照します。

  3. 組織 ID をコピーして、次の例でプロジェクトの POM ファイルに組織 ID を追加できるようにします。

Maven を使用して Exchange にアセットをパブリッシュする

https://github.com/mulesoft-labs/exchange-documentation-samples​ にあるリポジトリで、Maven を使用して各アセットタイプをパブリッシュする例を参照してください。

Maven を使用してアセットをパブリッシュする手順はアセットタイプごとに少し異なります。アセットごとに異なる Maven プラグインが使用されるため、リポジトリ内の例を参照して、使用するアセットタイプに一致する例を探してください。たとえば、​exchange-mule-maven-plugin​ を使用してカスタムアセットをパブリッシュし、​mule-maven-plugin​ を使用して拡張機能をパブリッシュします。

次の例は、アプリケーション、例、テンプレートなど、Mule 4 アセットをパブリッシュする方法を示しています。

  1. プロジェクトの POM ファイルで ​groupId​ を組織 ID に設定します。

     ...
     <groupId>ORGANIZATION_ID</groupId>
     ...

    アセットをルート組織にパブリッシュする場合、グループ ID は組織 ID と同じです。 次の URL 形式を使用します。

    https://maven.anypoint.mulesoft.com/api/v3/organizations/ORGANIZATION_ID/maven

    EU では、次の形式を使用します。

    https://maven.eu1.anypoint.mulesoft.com/api/v3/organizations/ORGANIZATION_ID/maven

    MuleSoft Government Cloud を使用している場合、次の形式を使用します。

    https://maven.gov.anypoint.mulesoft.com/api/v2/organizations/ORGANIZATION_ID/maven

    アセットをビジネスグループにパブリッシュする場合、グループ ID はビジネスグループ ID と同じです。 次の URL 形式を使用します。

    https://maven.anypoint.mulesoft.com/api/v3/organizations/BUSINESS_GROUP_ID/maven

    EU では、次の形式を使用します。

    https://maven.eu1.anypoint.mulesoft.com/api/v3/organizations/BUSINESS_GROUP_ID/maven

    MuleSoft Government Cloud を使用している場合、次の形式を使用します。

    https://maven.gov.anypoint.mulesoft.com/api/v2/organizations/BUSINESS_GROUP_ID/maven

  2. プロジェクトの POM ファイルで、​mule-maven-plugin​ を含めて、正しい分類子 (この例では ​mule-application-example​) を設定します。

    この例では、アセットタイプは分類子から推定されるため設定する必要はありません。

    ...
    <name>Hello World Application Example</name>
    <description>A mule application example uploaded using Exchange Maven Facade v3</description>
    <build>
        <plugins>
            <plugin>
                <groupId>org.mule.tools.maven</groupId>
                <artifactId>mule-maven-plugin</artifactId>
                <version>3.5.0</version>
                <extensions>true</extensions>
                <configuration>
                    <classifier>mule-application</classifier>
                </configuration>
            </plugin>
        </plugins>
    </build>
    ...

    <classifier>​ 要素を設定して、アセットを Exchange で表示できるようにする必要があります。

    name​ プロパティは必須です。これは、アセットの表示可能名を表します。GA (GroupId と AssetId の組み合わせ) の最初のバージョンをパブリッシュしている場合、アセット名は POM ファイルから取得されます。GA のバージョンがすでに 1 つ以上ある場合、​name​ プロパティは無視されます。この名前はアセットポータルで変更できます。詳細は、​「アセットの説明」​を参照してください。

    description​ プロパティは省略可能です。これは、アセットの説明を表します。GA (GroupId と AssetId の組み合わせ) の最初のバージョンをパブリッシュしている場合、アセットの説明は POM ファイルから取得されます。GA のバージョンがすでに 1 つ以上ある場合、​description​ プロパティは無視されます。この説明はアセットポータルで変更できます。詳細は、​「アセットの説明」​を参照してください。

    mule-maven-plugin​ が使用されている場合、​mule-maven-plugin​ 設定でプロパティ ​<type>​ を ​app​ に設定し、​<classifier>​ を ​mule-application​ に設定して Mule 3 アプリケーションをデプロイします。

    Anypoint Studio 6.3 以降を使用して、Mule 3 の ​templates​ と ​examples​ をデプロイします。

    Mule 4 アプリケーション場合、​<type>​ 要素を指定しないでください。​mule-maven-plugin​ 設定で、​<classifier>​ を ​mule-application​ (デフォルト)、​mule-application-template​、​mule-application-example​、または ​mule-policy​ に設定します。

    Mule 3 および Mule 4 アプリケーションは、Exchange アセットリストに表示されません。

  3. プロジェクトの POM ファイルの配布管理セクションにリポジトリとして Maven ファサードを追加します。

     ...
      <distributionManagement>
        <repository>
          <id>Repository</id>
          <name>Corporate Repository</name>
          <url>https://maven.anypoint.mulesoft.com/api/v3/organizations/ORGANIZATION_ID/maven</url>
          <layout>default</layout>
        </repository>
      </distributionManagement>
      ...

    EU では、次の形式を使用します。

     ...
      <distributionManagement>
        <repository>
          <id>Repository</id>
          <name>Corporate Repository</name>
          <url>https://maven.eu1.anypoint.mulesoft.com/api/v3/organizations/ORGANIZATION_ID/maven</url>
          <layout>default</layout>
        </repository>
      </distributionManagement>
      ...

    MuleSoft Government Cloud を使用している場合、次の形式を使用します。

     ...
      <distributionManagement>
        <repository>
          <id>Repository</id>
          <name>Corporate Repository</name>
          <url>https://maven.gov.anypoint.mulesoft.com/api/v2/organizations/ORGANIZATION_ID/maven</url>
          <layout>default</layout>
        </repository>
      </distributionManagement>
      ...

    <id>​ および ​<name>​ 要素は、リポジトリやその他の組織識別子を識別するために作成する任意の名前です。​<id>​ の値は ​pom.xml​ ファイル内と ​~/.m2/settings.xml​ ファイル内で同じである必要があります。​<id>​ の値により、​pom.xml​ ファイルが組織の URL にログインするための情報と関連付けられます。

  4. Maven の ​.m2​ ディレクトリにある ​settings.xml​ ファイルを更新します。

    Maven をインストールしたら、​mvn clean​ コマンドで ​.m2​ ディレクトリを作成します。ディレクトリは、macOS または Linux では ​~/.m2​、Windows では ​<default-drive>\Users\YOUR_USER_NAME\.m2​ です。これには Anypoint Platform ログイン情報が含まれます。Maven が実行されると、Maven クライアントは設定ファイルを読み取ります。

    settings.xml​ ファイルの例:

    <?xml version="1.0" encoding="UTF-8"?>
    <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
      <servers>
        <server>
          <id>Repository</id>
          <username>myusername</username>
          <password>mypassword</password>
        </server>
      </servers>
    </settings>
  5. 次の Maven コマンドを使用して、アセットを Exchange にパブリッシュします。

    mvn deploy
  6. Exchange でアセット ID を検索し、アセットを見つけます。

可変データを使用したアセットのパブリッシュ

Maven Facade API では、アセットを作成し、同じ要求内でアセットを説明する可変データを設定できます。アセットの可変データには、タグ、カスタム項目、カテゴリ、ドキュメントページが含まれます。

Exchange ドキュメントサンプルの GitHub リポジトリには、 ドキュメントとタグを使用した Mule アプリケーションテンプレート​の完全な作成例が含まれています。

XML プロパティ ​key​ をカスタム項目またはカテゴリのキーに設定して、​pom.xml​ ファイルのプロパティセクションでタグ、カスタム項目、およびカテゴリを宣言します。

    ...
    <properties>
        <categories key="categoryKey">someValue</categories>
        <fields key="fieldKey">someValue</fields>
        <tags>tag1,tag2,tag3</tags>
    </properties>
    ...

ドキュメントページを設定するには、​src/main/resources​ にドキュメントディレクトリを作成します。ドキュメントディレクトリに、各ページを ​Getting Started.md​ などの名前のマークダウンファイルとして含めます。​Getting Started​ をページのタイトルに置き換えます。契約条件ページを含めるには、​terms.md​ というファイルにコンテンツを配置します。省略可能なサブディレクトリ ​resources​ に画像などのリソースを含めます。省略可能なファイル ​config.json​ のメインオブジェクトのルートにあるプロパティ ​pageOrder​ を使用して、ページの順序を指定します。

{
 "pageOrder": ["home", "Getting Started", "Examples"]
}

pom.xml​ プラグインセクションに Maven アセンブリプラグインを追加してドキュメントフォルダをパッケージ化し、次のような Maven アセンブリプラグイン設定ファイルを作成します。

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-assembly-plugin</artifactId>
    <version>2.6</version>
    <configuration>
        <appendAssemblyId>true</appendAssemblyId>
    </configuration>
    <executions>
        <execution>
            <id>create-distribution</id>
            <phase>package</phase>
            <goals>
                <goal>single</goal>
            </goals>
            <configuration>
                <descriptors>
                    <descriptor>/src/main/resources/docs-assembly/assembly.xml</descriptor>
                </descriptors>
            </configuration>
        </execution>
    </executions>
</plugin>

src/main/resources/docs-assembly​ に ​assembly.xml​ ファイルを作成します。

<?xml version="1.0" encoding="UTF-8"?>
<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3 http://maven.apache.org/xsd/assembly-1.1.3.xsd">
   <id>docs</id>
   <formats>
       <format>zip</format>
   </formats>
   <includeBaseDirectory>false</includeBaseDirectory>
   <fileSets>
       <fileSet>
           <directory>${project.basedir}/src/main/resources/docs</directory>
           <outputDirectory>/</outputDirectory>
           <useDefaultExcludes>true</useDefaultExcludes>
       </fileSet>
   </fileSets>
</assembly>

アセットライフサイクル状態

新しいアセットバージョンの状態は ​development​ またはデフォルトの ​stable​ です。

stable​ 状態のアセットバージョンを作成するには、通常どおりに Maven を使用します。

development​ 状態のアセットバージョンを作成するには、Anypoint Exchange Maven Facade API バージョン 3 を使用して、アセットのバージョンを ​SNAPSHOT​ に設定します。この方法では、従来の API との後方互換性が確保されます。

SNAPSHOT​ アセットは永続的に ​development​ 状態であり、他の状態に昇格することはできません。

Anypoint Exchange Maven Facade API バージョン 1 またはバージョン 2 でパブリッシュされたバージョン ​SNAPSHOT​ のアセットの状態は ​stable​ です。

development​ 状態の ​SNAPSHOT​ テンプレートアセットのアップロードの例を次に示します。

ターミナルで次の操作を実行します。

  1. Execute (実行): git clone https://github.com/mulesoft-labs/exchange-documentation-samples.git

  2. Execute (実行): cd exchange-documentation-samples/template-snapshot

  3. ファイル ​pom.xml​ を編集し、値 ​YOUR_ORG_ID​、​YOUR_GROUP_ID​、​YOUR_ASSET_ID​ をアセットの organizationId、groupId、assetId に置き換えます。

  4. Execute (実行): mvn clean deploy

  5. Exchange ホームページを開き、​development​ 状態のテンプレートを表示します。

mvn clean deploy​ を複数回実行すると、アセットはエラーなしで上書きされます。

注意: development 状態のアセットのうち SNAPSHOT バージョンでないアセットは Maven を介してコンシュームできません。

カスタムアセットのパブリッシュ

exchange-mule-maven-plugin​ プラグインを使用して、カスタムアセットをパブリッシュします。このプラグインの最新バージョンは 0.0.13 です。

この例は、​pom.xml​ の ​build​ セクションを示しています。

<build>
    <plugins>
        <plugin>
            <groupId>org.mule.tools.maven</groupId>
            <artifactId>exchange-mule-maven-plugin</artifactId>
            <version>0.0.13</version>
            <executions>
                <execution>
                    <id>validate</id>
                    <phase>validate</phase>
                    <goals>
                        <goal>exchange-pre-deploy</goal>
                    </goals>
                </execution>
                <execution>
                    <id>deploy</id>
                    <phase>deploy</phase>
                    <goals>
                        <goal>exchange-deploy</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

トラブルシューティング

ビルドがデプロイメントフェーズで状況コード 412 (前提条件失敗) で失敗した場合、​<goal>exchange-pre-deploy</goal>​ は実行されていません。このエラーを修正するには、目標がプラグインの実行セクション内で設定されていることを確認します。

エラーは次のようになります。

[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  2.871 s
[INFO] Finished at: 2020-11-09T12:11:54-03:00
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-deploy-plugin:2.7:deploy (default-deploy) on project hello-world-pom: Failed to deploy artifacts: Could not transfer artifact 1da12ec1-7614-43a3-bf24-ff754cab8ddf:hello-world-pom:pom:1.0.3 from/to repository-id ([https://maven.anypoint.mulesoft.com/api/v3/organizations/orgId/maven/](http://localhost:8088/api/v3/organizations/1da12ec1-7614-43a3-bf24-ff754cab8ddf/maven/)): Transfer failed for [https://maven.anypoint.mulesoft.com](http://localhost:8088/api/v3/organizations/1da12ec1-7614-43a3-bf24-ff754cab8ddf/maven/)[/api/v3/organizations/](http://localhost:8088/api/v3/organizations/1da12ec1-7614-43a3-bf24-ff754cab8ddf/maven/1da12ec1-7614-43a3-bf24-ff754cab8ddf/hello-world-pom/1.0.3/hello-world-pom-1.0.3.pom)[orgId](http://localhost:8088/api/v3/organizations/1da12ec1-7614-43a3-bf24-ff754cab8ddf/maven/)[/maven/groupId/assetId/version/filename](http://localhost:8088/api/v3/organizations/1da12ec1-7614-43a3-bf24-ff754cab8ddf/maven/1da12ec1-7614-43a3-bf24-ff754cab8ddf/hello-world-pom/1.0.3/hello-world-pom-1.0.3.pom) 412 -> [Help 1]

統合アセットをパブリッシュおよびコンシュームする

統合アセットのパブリッシュとコンシュームには、トークン認証または接続アプリケーション認証が必要です。

トークン認証を使用する手順は、次のとおりです。

  1. SAML アサーションを使用して API ベアラートークンを取得します​。

    これが自分のアクセストークンになります。

  2. C:\Users\YOUR_USER_NAME\.m2\settings.xml​ (Windows) または ​~/.m2/settings.xml​ (macOS または Linux) で ​settings.xml​ ファイルを開きます。

  3. <username>​ の値は変更しないでください。

    この値はプラットフォームにトークンを使用していることを伝えます。

  4. <password>​ の値を自分のアクセストークンに設定します。

    <?xml version="1.0" encoding="UTF-8"?>
    <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
              http://maven.apache.org/xsd/settings-1.0.0.xsd">
      <servers>
        <server>
          <id>Repository</id>
          <username>~~~Token~~~</username>
          <password>01234567-89ab-cdef-0123-456789abcdef</password>
        </server>
      </servers>
    </settings>
  5. settings.xml​ ファイルを保存します。

接続アプリケーション認証を使用する手順は、次のとおりです。

  1. 接続アプリケーションを作成​します。

  2. 基本認証を指定し、​~~~Client~~~​ としてユーザ名、​clientID~?~clientSecret​ としてパスワードを定義します。

    1. clientID​ をクライアント ID に置き換えます。

    2. clientSecret​ をクライアントシークレットに置き換えます。

接続アプリケーションをリポジトリのファイル ​settings.xml​ に含めます。

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <servers>
    ...
    <server>
      <id>Repository</id>
      <username>~~~Client~~~</username>
      <password>clientID~?~clientSecret</password>
    </server>
  </servers>
</settings>

Exchange 外部の連動関係

Java ライブラリと POM ファイルを Exchange カスタムアセットとしてパブリッシュします。

Maven Central または MuleSoft Maven リポジトリに存在しない連動関係を宣言する Mule 4 拡張機能は現在サポートされていません。

Exchange アセットを文書化する

Maven Facade を使用して、アセットを Exchange にパブリッシュすると、Exchange にドキュメントポータルが自動的に作成され、​通常どおりにアセットを文書化​できます。

Maven を使用して Exchange アセットをコンシュームする

Maven Facade を使用して、コネクタ、Mule アプリケーション、REST API を含め、Exchange にパブリッシュされたアセットをコンシュームできます。Exchange アセットをコンシュームするには、アセットのグループ ID、アーティファクト ID、およびバージョンをプロジェクトの ​pom.xml​ ファイルの ​dependencies​ セクションに追加し、Maven ファサードをリポジトリとして ​repositories​ セクションに追加します。

<project xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                      http://maven.apache.org/xsd/maven-4.0.0.xsd">
 ...

  <dependencies>
    <dependency>
      <groupId>org.mule.modules</groupId>
      <artifactId>mule-module-metoo</artifactId>
      <version>1.0.0</version>
    </dependency>
  </dependencies>

 ...

  <repositories>
    <repository>
      <id>Repository</id>
      <name>Corporate Repository</name>
      <url>https://maven.anypoint.mulesoft.com/api/v3/organizations/ORGANIZATION_ID/maven</url>
      <layout>default</layout>
    </repository>
  </repositories>
 ...
</project>

ORGANIZATION_ID​ を組織 ID に置き換えます。

https://maven.anypoint.mulesoft.com/api/v3/maven​ はルート組織にパブリッシュするデフォルトであるため、​<url>​ 値で有効な URL として使用できます。EU では、URL として ​https://maven.eu1.anypoint.mulesoft.com/api/v3/maven​ を使用します。MuleSoft Government Cloud を使用している場合、URL として ​https://maven.gov.anypoint.mulesoft.com/api/v2/maven​ を使用します。

EU では、​<repositories>​ セクションは次のようになります。

  <repositories>
    <repository>
      <id>Repository</id>
      <name>Corporate Repository</name>
      <url>https://maven.eu1.anypoint.mulesoft.com/api/v3/organizations/ORGANIZATION_ID/maven</url>
      <layout>default</layout>
    </repository>
  </repositories>

MuleSoft Government Cloud を使用している場合、​<repositories>​ セクションは次のようになります。

  <repositories>
    <repository>
      <id>Repository</id>
      <name>Corporate Repository</name>
      <url>https://maven.gov.anypoint.mulesoft.com/api/v2/organizations/ORGANIZATION_ID/maven</url>
      <layout>default</layout>
    </repository>
  </repositories>