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

Exchange API を使用すると、アセットをパブリッシュおよびコンシュームしたり、ドキュメントページを追加したり、カテゴリを追加または編集したり、公開ポータルを管理したりできます。このページには、Exchange API の使用例がいくつか示されています。完全な API ドキュメントは API ドキュメントポータルにあります。

API では、すべての Exchange アセットタイプがサポートされています。

REST API
SOAP API
HTTP API
AsyncAPI 仕様
API フラグメント
コネクタ
Mule アプリケーション
例
テンプレート
ポリシー
カスタムアセット

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

前提条件

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

アセットをパブリッシュするには、一意のアーティファクト ID と組織 ID が必要です。アーティファクト ID は、グループ ID、アセット ID、バージョンで構成されています。

アセットを Exchange にパブリッシュするために必要なタスク

次のタスクを実行して、アセットを Exchange にパブリッシュし、Exchange API を使用してメタデータを追加します。

組織 ID を見つける
認証
1. アクセストークンを取得する
2. 接続アプリケーション認証を使用する
アセットをパブリッシュする
アセットを説明する
ドキュメントページを追加および更新する
ランタイム情報をアセットに追加する

組織 ID を見つける

組織 ID を見つける手順は、次のとおりです。

Anypoint Platform にログインし、[Access Management (アクセス管理)] をクリックします。
最上位組織またはビジネスグループの名前をクリックし、[organization information (組織情報)] 画面の組織 ID を参照します。
組織 ID をコピーして、例を試すときに使用します。

認証

Exchange API には、アクセストークンまたは接続アプリケーションによる認証が必要です。

アクセストークンを取得する

Anypoint Platform にログインします。
cURL コマンドでアクセストークンを取得します。

Postman や別のアプリケーションを使用して HTTP コマンドを送信することもできます。

ANYPOINT_USERNAME を Anypoint Platform ユーザーアカウント名に置き換えて、ANYPOINT_PASSWORD をそのパスワードに置き換えます。

curl --location --request POST 'https://anypoint.mulesoft.com/accounts/login' \
     --header 'Content-Type: application/json' \
     --header 'Accept: application/json' \
     --data-raw '{
        "username":"ANYPOINT_USERNAME",
        "password":"ANYPOINT_PASSWORD"
     }' | jq -r ".access_token"

API コールでこのアクセストークンを使用します。

組織のシステム管理者は、アクセストークンの有効期限を 15 分～ 180 分の値に設定します。検索やより多くの時間を必要とする他の操作を実行する場合、追加のトークンを要求する必要があります。

接続アプリケーション認証を使用する

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

接続アプリケーションを作成します。
基本認証を指定し、~~~Client~~~ としてユーザー名、clientID~?~clientSecret としてパスワードを定義します。
1. clientID をクライアント ID に置き換えます。
2. clientSecret をクライアントシークレットに置き換えます。

アセットをパブリッシュする

Exchange API バージョン 2 では、マルチパートフォームデータを送信するか、データが含まれる POM ファイルを渡して、アセットを Exchange にパブリッシュできます。

API では、同期または非同期で Exchange にアセットアップロードすることもできます。

API では、サポートされているすべてのアセットタイプ (REST API、SOAP API、HTTP API、AsyncAPI 仕様、API フラグメント、コネクタ、Mule アプリケーション、サンプル、テンプレート、ポリシー、カスタムアセットなど) をアップロードできます。

次の例は、REST API (RAML 仕様) をパブリッシュする方法を示しています。

アセットプロパティを指定する

アセットを作成する API コールごとに、マルチパートプロパティを指定します。

プロパティ説明必須または省略可能

プロパティ	説明	必須または省略可能
name (名前)	Exchange ポータルページに表示されるアセット名。	必須
description (説明)	アセットの説明。	省略可能
type	作成するアセットタイプ。	ファイル拡張子からタイプを推定できない場合は必須
連動関係	`dependencies=GROUP_ID:ASSET_ID:VERSION,GROUP_ID:ASSET_ID:VERSION` のように定義されるカンマ区切りの連動関係の文字列。	省略可能
keywords (キーワード)	アセットの属性として保存されるカンマ区切り値の文字列 (`keywords=api,raml,auth,jwt,token` など)。検索クエリでは、アセットをキーワードで検索できます。	省略可能
tags (タグ)	アセットのタグとして送信するカンマ区切り値の文字列 (`tags=tag1,tag2` など)。タグ項目が要求内に存在しないか空の場合、アセットのタグは変更されません。この文字列は最終バージョンであるため、2 つのタグがあるアセットから 1 つのタグを削除するには、残しておくタグのみを送信します。	省略可能
fields (項目)	プロパティのキーと値が設定されたオブジェクトを項目とする JSON 配列で、カスタム項目を表す。カスタム項目は、組織で設定されている必要があります。カスタムアセットをアップロードする例として、カスタム項目が挙げられます。	省略可能
fields.key	アセットのカスタム項目として送信するカンマ区切り値の文字列。`key` を、追加または置換するカスタム項目のキーに置き換えます。カスタム項目は、組織で設定されている必要があります。項目要素が要求内に存在しないか空の場合、アセットの項目は変更されません。この文字列は最終バージョンであるため、2 つのカスタム項目があるアセットから 1 つのカスタム項目を削除するには、残しておく項目のみを送信します。	省略可能
categories	プロパティのキーと値が設定されたオブジェクトを項目とする JSON 配列で、カスタム項目を表す。カスタム項目は、組織で設定されている必要があります。カスタムアセットをアップロードする例として、カスタム項目が挙げられます。	省略可能
categories.key	アセットのカテゴリとして送信するカンマ区切り値の文字列。`key` を、追加または置換するカテゴリのキーに置き換えます。カテゴリは、組織で設定されている必要があります。カテゴリ項目が要求内に存在しないか空の場合、アセットのカテゴリは変更されません。この文字列は最終バージョンであるため、2 つのカテゴリがあるアセットから 1 つのカテゴリを削除するには、残しておくカテゴリのみを送信します。	省略可能
contactName	アセットについて連絡するユーザーの名前。	省略可能
contactEmail	アセットについて連絡するユーザーのメールアドレス。	省略可能
properties	一部のアセットタイプでは、`apiVersion`、`mainFile`、`assetLink` などのプロパティプレフィックスで追加のプロパティを指定する必要があります (例: `properties.apiVersion = v1`)。	一部のプロパティおよびアセットタイプでは必須

name (名前)

Exchange ポータルページに表示されるアセット名。

必須

description (説明)

アセットの説明。

省略可能

type

作成するアセットタイプ。

ファイル拡張子からタイプを推定できない場合は必須

連動関係

dependencies=GROUP_ID:ASSET_ID:VERSION,GROUP_ID:ASSET_ID:VERSION のように定義されるカンマ区切りの連動関係の文字列。

省略可能

keywords (キーワード)

アセットの属性として保存されるカンマ区切り値の文字列 (keywords=api,raml,auth,jwt,token など)。検索クエリでは、アセットをキーワードで検索できます。

省略可能

tags (タグ)

アセットのタグとして送信するカンマ区切り値の文字列 (tags=tag1,tag2 など)。タグ項目が要求内に存在しないか空の場合、アセットのタグは変更されません。この文字列は最終バージョンであるため、2 つのタグがあるアセットから 1 つのタグを削除するには、残しておくタグのみを送信します。

省略可能

fields (項目)

プロパティのキーと値が設定されたオブジェクトを項目とする JSON 配列で、カスタム項目を表す。カスタム項目は、組織で設定されている必要があります。カスタムアセットをアップロードする例として、カスタム項目が挙げられます。

省略可能

fields.key

アセットのカスタム項目として送信するカンマ区切り値の文字列。key を、追加または置換するカスタム項目のキーに置き換えます。カスタム項目は、組織で設定されている必要があります。項目要素が要求内に存在しないか空の場合、アセットの項目は変更されません。この文字列は最終バージョンであるため、2 つのカスタム項目があるアセットから 1 つのカスタム項目を削除するには、残しておく項目のみを送信します。

省略可能

同期公開または非同期公開を指定する

同期メソッドを使用するには、ヘッダー x-sync-publication:true を追加します。

非同期メソッドを使用するには、ヘッダー x-sync-publication:false を追加するか、x-sync-publication ヘッダーなしで要求を送信します。

アセットが非同期でパブリッシュされる場合、次のような応答が返されます。

{
"publicationStatusLink":"https://anypoint.mulesoft.com/exchange/api/v2/organizations/67ac7cde-c02c-457f-b826-da2474e63d5a/assets/67ac7cde-c02c-457f-b826-da2474e63d5a/wsdl-asset/1.0.0/publication/status/d47a22a5-90f6-49eb-bfd0-d9fff575e022"
}

エンドポイント publicationStatusLink では、アセットのパブリッシュ状況が提供されます。

可変データの設定

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

アセットのパブリッシュエンドポイントで、新しいアセットが作成されます。アセットがすでに存在する場合、要求はエラー 409 (競合) で失敗します。既存のバージョンの可変データは変更しないでください。代わりに、更新された可変データを使用して新しいパッチバージョンを作成します。たとえば、現在のバージョンが 1.2.3 の場合、バージョン 1.2.4 を作成します。

この例では、キー categoryKey と fieldKey を使用するカテゴリとカスタム項目をパブリッシュします。組織にカテゴリまたはカスタム項目が設定されていない場合、パブリッシュは失敗します。

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

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

curl --location --request POST 'https://anypoint.mulesoft.com/exchange/api/v2/organizations/:organizationId/assets/:groupId/:assetId/:version' \
--header 'Authorization: bearer YOUR_TOKEN' \
--header 'x-sync-publication: true' \
--form 'type="custom"' \
--form 'name="Comprehensive Test"' \
--form 'tags="1, 2, 3, 4"' \
--form 'categories.categoryKey="value1, value2"' \
--form 'fields.fieldKey="value1, value2"' \
--form 'contactName="Max Mule"' \
--form 'contactEmail="maxmule@example.com"' \
--form 'files.docs.zip=@"/file-path/docs.zip"'

カテゴリと項目を JSON コレクションとして設定

マルチパートフォーム内で JSON 形式のカテゴリやカスタム項目を設定または変更するには、プロパティのキーと値を含むオブジェクトの配列を送信します。

組織にカテゴリやカスタム項目が設定されていない場合は要求が失敗します。

カテゴリやカスタム項目をすべて削除するには、空の配列を送信します。

--form 'categories="[]"'
--form 'fields="[]"'

マルチパートフォームでは JSON 形式のデータが優先されるため、この例では categoryKey2 または fieldKey2 が設定されません。

例:

curl --location --request POST 'https://anypoint.mulesoft.com/exchange/api/v2/organizations/:organizationId/assets/:groupId/:assetId/:version' \
--header 'Authorization: bearer YOUR_TOKEN' \
--header 'x-sync-publication: true' \
--form 'type="custom"' \
--form 'name="Comprehensive Test"' \
--form 'tags="1, 2, 3, 4"' \
--form 'categories="[{"key":"categoryKey", "value":"value1, value2"}]"' \
--form 'categories.categoryKey2="value3"' \
--form 'fields="[{"key":"fieldKey", "value":"value1, value2"}]"' \
--form 'fields.fieldKey2="value3"' \
--form 'files.docs.zip=@"/file-path/docs.zip"'

ライフサイクル状態を設定する

新しいアセットバージョンは、development 状態またはデフォルトの stable 状態 (published とも呼ばれる) のいずれかになります。非推奨にする前のアセットバージョンは stable である必要があります。

Exchange API バージョン 2 を使用してアセットを作成し、そのライフサイクル状態を設定するには、プロパティ status をマルチパート要求に追加します。状態が指定されていない場合、アセットはデフォルトの stable 状態で作成されます。

次の REST API アセットの例は、アセットの作成方法とそのライフサイクル状態の設定方法を示しています。

Anypoint Platform にログインし、サンプルファイルをダウンロードします。
/file-path/training-american-flights-api-1.0.0-raml.zip をダウンロードしたファイルのローカルパスに置き換えます。
ANYPOINT_TOKEN、:organizationId、:groupId、:assetId、:version を実装に固有の値に置き換えます。
プロパティ status を development または published に設定します。
Execute (実行):

curl -v \
    -H 'Authorization: bearer ANYPOINT_TOKEN' \
    -H 'x-sync-publication: true' \
    -F 'name=RAML asset name' \
    -F 'description=Description of the asset' \
    -F 'keywords=best, raml' \
    -F 'status=development' \
    -F 'properties.mainFile=american-flights-api.raml' \
    -F 'properties.apiVersion=v1' \
    -F 'files.raml.zip=@/file-path/training-american-flights-api-1.0.0-raml.zip' \   https://anypoint.mulesoft.com/exchange/api/v2/organizations/:organizationId/assets/:groupId/:assetId/:version

Exchange API バージョン 1 を使用してアセットを作成し、そのライフサイクル状態を設定するには、項目として status プロパティを設定します。

アセットアイコンとして使用する画像のアップロード

パブリッシュエンドポイントを使用して、アセットアイコンとして使用する画像をアップロードします。Exchange ポータルに表示されるアイコンは、ユーザーがアセットを探すときに役立ちます。アイコンは会社のログやその他の画像にできます。次のファイルの種類がサポートされています。

GIF
JPG
JPEG
PNG
SVG

アセットアイコンは、バージョンに依存しません。これらは、アセットがバージョン設定されても新しいアイコンに置き換わることはありません。

+ 次の例は、png ファイル画像をアップロードし、アセットアイコンとして使用する方法を示しています。アセットを指定するには、識別子 :groupId、:assetId、:version 実装に固有の値に置き換えます。files.icon.png が my-asset-icon.png と同じファイルの種類であることを確認します。

curl -v \
    -H 'Authorization: bearer ANYPOINT_TOKEN' \
    -H 'x-sync-publication: true' \
    -F 'name=My asset name' \
    -F 'description=Asset with an uploaded icon' \
    -F 'files.raml.zip=@/file-path/training-american-flights-api-1.0.0-raml.zip' \
    -F 'files.icon.png=@/file-path/my-asset-icon.png' \
https://anypoint.mulesoft.com/exchange/api/v2/organizations/:organizationId/assets/:groupId/:assetId/:version

アセットを説明する

アセットをパブリッシュしたら、省略可能なタグ、カテゴリ、カスタム項目を追加して、メタデータを強化し、アセットを見つけやすくします。

タグを追加する

次の例は、アセットのタグを挿入または置き換える方法を示しています。各アセットは、グループ ID、アセット ID、バージョンの組み合わせで一意に識別されます。アセットを指定するには、識別子 :groupId、:assetId、:version を置き換えます。

次のコマンドでは、アセットの既存のタグが置き換えられます。

curl 'https://anypoint.mulesoft.com/exchange/api/v2/assets/:groupId/:assetId/:version/tags' \
  -X 'PUT' \
  -H 'accept: application/json' \
  -H 'authorization: bearer ANYPOINT_TOKEN' \
  -H 'content-type: application/json' \
  -d '[{"value":"rest-api"}, {"value":"documentation"}]'

カテゴリを追加する

カテゴリは、組織のシステム管理者が追加および管理する管理項目です。

次の例では、以前に作成した apiType という名前のカテゴリを使用し、アセットのそのカテゴリの値を System API に設定します。各アセットは、グループ ID、アセット ID、バージョンの組み合わせで一意に識別されます。アセットを指定するには、識別子 :groupId、:assetId、:version を置き換えます。

curl -X PUT \
https://anypoint.mulesoft.com/exchange/api/v2/assets/:groupId/:assetId/:version/tags/categories/apiType \
  -H 'Authorization: bearer ANYPOINT_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "tagValue": ["System API"]
  }'

カスタム項目を追加する

次の例では、以前に作成した subType という名前のカスタム項目を使用して、アセットのそのカテゴリの値を OAS に設定します。各アセットは、グループ ID、アセット ID、バージョンの組み合わせで一意に識別されます。アセットを指定するには、識別子 :groupId、:assetId、:version を置き換えます。

curl -X PUT \
https://anypoint.mulesoft.com/exchange/api/v2/assets/:groupId/:assetId/:version/tags/fields/subType \
  -H 'Authorization: bearer ANYPOINT_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "tagValue": ["OAS"]
  }'

ライフサイクル状態を昇格する

考えられる 3 つのアセットライフサイクル状態の昇格を次に示します。

development から stable
stable から deprecated
deprecated から stable

stable 状態は published とも呼ばれます。

この例では、ANYPOINT_TOKEN、:groupId、:assetId、:version を実装に固有の値に置き換え、:status を development、published、deprecated のいずれかに置き換えます。

curl -X https://anypoint.mulesoft.com/exchange/api/v2/assets/:groupId/:assetId/:version/status \
    -H 'Authorization: bearer ANYPOINT_TOKEN' \
    -d '{"status": ":status"}'

アセットメタデータの更新

この例は、バージョン番号を変更したり、アセットの新しいバージョンを作成したりせずに、既存のアセットを説明する可変メタデータを更新する方法を示しています。この可変データには、カテゴリ、カスタム項目、タグ、ドキュメントページが含まれます。

キー categoryKey はカテゴリをパブリッシュし、キー fieldKey はカスタム項目をパブリッシュします。組織にカテゴリまたはカスタム項目が設定されていない場合、パブリッシュは失敗します。

files.docs.zip というドキュメントファイルをアップロードすると、アセットのドキュメントが更新されます。アーカイブのルートディレクトリには、Getting Started.md などの名前のマークダウンファイルとして各ドキュメントページが含まれています。他の各ページは、ファイル名の Getting Started がページのタイトルに置き換えられます。省略可能な契約条件ページには、ファイル名 terms.md が使用されます。省略可能なサブディレクトリ resources には、画像などのリソースが含まれます。省略可能なファイル config.json のメインオブジェクトのルートにあるプロパティ pageOrder では、ページの順序が指定されます。

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

curl --location --request PATCH 'https://anypoint.mulesoft.com/exchange/api/v2/organizations/:organizationId/assets/:groupId/:assetId/:version/mutabledata' \
--header 'Authorization: bearer YOUR_TOKEN' \
--form 'tags="1, 2, 3, 4"' \
--form 'categories.categoryKey="value1, value2"' \
--form 'fields.fieldKey="value1, value2"' \
--form 'files.docs.zip=@"/file-path/docs.zip"'

可変データは非同期で更新され、要求は次のような応答を返します。

{ "mutableDataStatusLink":"https://anypoint.mulesoft.com/exchange/api/v2/organizations/:organizationId/assets/:groupId/:assetId/:version/mutabledata/status/170d1e6f-d567-48e2-a2f4-00b2e3951be6" }

mutableDataStatusLink へのコールで、パブリッシュの状況が表示されます。

curl https://anypoint.mulesoft.com/exchange/api/v2/organizations/:organizationId/assets/:groupId/:assetId/:version/mutabledata/status/170d1e6f-d567-48e2-a2f4-00b2e3951be6 \
--header 'Authorization: bearer YOUR_TOKEN'

要求で認証ヘッダーが提供されない場合、エラー「Unauthorized (未認証)」で失敗します。

ドキュメントページを追加および更新する

各 Exchange アセットには、アセットに関する概要やその他の情報を提供するドキュメントが関連付けられています。Exchange API でドキュメントを追加または更新するには、「Exchange administrator (Exchange 管理者)」権限またはる「Exchange Contributor (Exchange コントリビューター)」権限が必要です。

Exchange API を使用してドキュメントを追加または更新する手順は、次のとおりです。

ドラフトモードで新しいページを追加します。
コンテンツをページに追加します。
ドラフトをパブリッシュします。

ドラフトモードで新しいページを追加する

新しいドキュメントページを追加するには、次のコマンドを使用して :groupId、:assetId、:version をアセットの値に置き換えます。

curl https://anypoint.mulesoft.com/exchange/api/v2/assets/:groupId/:assetId/:version/portal/draft/pages \
  -X POST \
  -H 'Authorization: bearer ANYPOINT_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "pagePath": "Security" }'

コマンドが成功したら、新しく作成されたページの pageId 値が返されます。

Exchange では、アセットの Exchange ポータルページのデフォルトのホームページに新しいドラフトページが表示されます。このページを編集してドラフトをパブリッシュするには、ポータルユーザーインターフェースまたは Exchange API を使用します。

コンテンツをページに追加する

ドキュメントページは、GitHub マークダウンで作成されます。詳細は、「マークダウンに関する注意」を参照してください。

マークダウンコンテンツを追加するには、次のコマンドを使用して、:pageId を前に取得したページ ID に置き換えます。

curl https://anypoint.mulesoft.com/exchange/api/v2/assets/:groupId/:assetId/:version/portal/draft/pages/:pageId \
  -X PUT \
  -H 'Authorization: bearer ANYPOINT_TOKEN' \
  -H 'Content-Type: text/markdown' \
  -d 'markdown *content* for this page'

ドラフトをパブリッシュする

ドラフトをパブリッシュすると、アセットに関連付けられていて現在 [draft (ドラフト)] 状況のすべてのページとコンテンツがパブリッシュされます。コンテンツの準備ができたら場合、ページの状況を [draft (ドラフト)] から [published (パブリッシュ済み)] に変更します。

curl https://anypoint.mulesoft.com/exchange/api/v2/assets/:groupId/:assetId/:version/portal \
  -X PATCH  \
  -H 'Authorization: bearer ANYPOINT_TOKEN'

ランタイム情報をアセットに追加する

API アセットにコンシューマーが API を検出、学習、理解するために必要なすべての情報が追加されたら、コンシューマーが API を呼び出すことができるようにサーバーまたはインスタンス情報を追加します。:groupId、:assetId、:versionGroup を API アセットのグループ ID、アセット ID、バージョン ID に置き換えます。

curl https://anypoint.mulesoft.com/exchange/api/v2/assets/:groupId/:assetId/versionGroups/:versionGroup/instances/external \
  -X POST \
  -H 'Authorization: bearer ANYPOINT_TOKEN' \
  -d '{
    "name": "Production - US",
    "endpointUri": "http://dog.domain.tld.com/much/doge",
    "isPublic": false
  }'

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

前提条件

アセットを Exchange にパブリッシュするために必要なタスク

組織 ID を見つける

認証

アクセストークンを取得する

接続アプリケーション認証を使用する

アセットをパブリッシュする

アセットプロパティを指定する

同期公開または非同期公開を指定する

可変データの設定

カテゴリと項目を JSON コレクションとして設定

ライフサイクル状態を設定する

アセットアイコンとして使用する画像のアップロード

アセットを説明する

タグを追加する

カテゴリを追加する

カスタム項目を追加する

ライフサイクル状態を昇格する

アセットメタデータの更新

ドキュメントページを追加および更新する

ドラフトモードで新しいページを追加する

コンテンツをページに追加する

ドラフトをパブリッシュする

ランタイム情報をアセットに追加する

関連情報