1. Homepage
  2. Exchange
  3. API カタログ CLI を使用した API の自動カタログ化

  4. 手動による記述子ファイルの作成または更新

手動での記述子ファイルの作成または更新

可能な場合は、Equality の会社の値に一致するように、含めない用語を変更しました。顧客の実装に対する影響を回避するために、一部の用語は変更されていません。
手動で記述子ファイルを作成または更新するには、UTF-8 文字エンコーディング形式を使用してファイルを保存する必要があります。記述子ファイルのエンコーディングが想定される API カタログ CLI のエンコーディングと一致しないと、エンコーディングの問題が発生する場合があります。

create-descriptor​ および ​update-descriptor​ コマンドは、カタログ化する API を識別し、カタログ化に必要な情報を出力します。記述子情報を追加する最も効率的なアプローチは、まず CLI を使用して記述子ファイルを作成または更新し、次に自動的に生成できない情報を使用して手動でファイルを更新することです。記述子 YAML スキーマに関する次の情報を使用して、何を追加するのかを決定します。

記述子 YAML スキーマ

カタログ化する API を記述するために使用される YAML タグを次に示します。

カタログ記述子行

記述子ファイルは、次の行で始まる必要があります。記述子のバージョンは、実行する API カタログ CLI のバージョンに対応します。次の例は、API カタログ CLI 1.0.0 の必須の開始行を示しています。

#%Catalog Descriptor 1.0

triggerConditions

YAML ファイルの ​triggerConditions​ セクションでは、記述子ファイルで記述された API のどのセットをパブリッシュするのかを決定する条件を設定できます。このセクションを記述子ファイルに追加すると、​--trigger-criteria​ フラグの各トリガー条件の値が一致する ​api-catalog publish-asset​ コマンドが実行された場合にのみ API がパブリッシュされます。これにより、各分岐または環境の CI/CD スクリプトで同じ ​api-catalog publish-asset​ を使用し、コマンドにパラメーターを渡して、パブリッシュされる API を制御できます。

特定の API のトリガー条件や、記述子ファイルで記述されたすべての API (グローバル) のトリガー条件を設定できます。両方の条件種別が使用されている場合、特定の条件がグローバル条件よりも優先されます。

次に ​triggerConditions​ セクションの例を示します。

triggerConditions:
  branches:
    - main
    - release/(.*)
  tags:
    - support
    - release/(.*)

前の例では、​api-catalog publish-asset​ コマンドに次のすべての ​--trigger-criteria​ フラグ値がある場合にのみ、コマンドを実行して記述子ファイルで記述された API をパブリッシュできます。

  • branches​ が ​main​ であるか、テキストに ​release/​ がある

  • tags​ が ​support​ であるか、テキストに ​release/​ がある

triggerConditions​ セクションは、次のように ​--trigger-criteria​ フラグに一致します。

  • グローバル ​triggerConditions​ セクションが記述子ファイルに含まれている場合、​--trigger-criteria​ フラグ値のすべてのトリガー条件が一致しない限り、​api-catalog publish-asset​ コマンドで API はパブリッシュされません。

  • 特定の API の ​triggerConditions​ セクションが含まれている場合、​--trigger-criteria​ フラグ値のトリガー条件が一致した場合にのみ特定の API がパブリッシュされます。

  • グローバルレベルと API レベルの両方のトリガー条件が含まれている場合、API レベルの条件がグローバルレベルの条件よりも優先されます。

--trigger-criteria​ フラグを使用する ​publish-asset​ コマンドの例については、​「条件を使用してパブリッシュをトリガーする」​を参照してください。

versionStrategyConditions

YAML ファイルの ​versionStrategyConditions​ セクションでは、記述子ファイルで記述された API のセットのバージョン戦略を決定できます。このセクションを記述子ファイルに追加すると、​--version-strategy-criteria​ フラグで ​api-catalog publish-asset​ コマンドが実行された場合に API のバージョン戦略が設定されます。これにより、各分岐または環境の CI/CD スクリプトで同じ ​api-catalog publish-asset​ を使用し、コマンドにパラメーターを渡して、パブリッシュされる API のバージョン戦略を制御できます。

特定の API のバージョン戦略や、記述子ファイルで記述されるすべての API (グローバル) のバージョン戦略を設定できます。両方の条件種別が使用されている場合、特定の条件がグローバル条件よりも優先されます。

次に ​versionStrategyConditions​ セクションの例を示します。

    versionStrategyConditions:
      minorIncrease:
        branches:
          - main
        tags:
          - support
      snapshot:
        branches:
          - develop

versionStrategyConditions​ セクションは、次のように ​--version-strategy-criteria​ フラグに一致します。

  • publish-asset​ コマンドに設定された ​--version-strategy-criteria​ フラグが ​versionStrategyConditions​ と一致した場合、そのバージョン戦略が使用されます。

  • グローバルレベルと API レベルの両方で ​versionStrategyConditions​ の一致がある場合、API レベルの条件がグローバルレベルの条件よりも優先されます。

  • 一致する条件がない場合、記述子ファイルに ​versionStrategy​ オプションが設定されていれば、そのバージョン戦略が使用されます。

  • versionStrategy​ オプションが設定されておらず、​versionStrategyConditions​ の一致がない場合は、デフォルトのバージョン戦略である ​patchIncrease​ が使用されます。

--version-strategy-criteria​ フラグを使用する ​publish-asset​ コマンドの例については、​「条件を使用したバージョン戦略の設定」​を参照してください。

contact

スキーマの ​contact​ セクションには、自動カタログ化のために主連絡先の名前とメール ID が含まれます。何も含まれていない場合、これらはデフォルトの ​unknown​ になります。

projects

スキーマの ​projects​ セクションには、カタログ化される API プロジェクトがカタログ化に必要な詳細と共にリストされます。

main

API を記述する仕様ファイルの場所。

assetId

Exchange でパブリッシュされるアセットの ID を指定します。

documentation

ドキュメントページの名前と API のファイルの場所を指定するキー-値のペアのリスト。 これらのペアにより、Anypoint Platform のドキュメントページの順序が定義されます。

形式: <ドキュメントページの名前>:<ファイルの場所>

このオプションが指定されていない場合、ドキュメントページはインポートされません。

categories

カテゴリ名と値を指定するキー-値のペアのリスト。これらのペアは、Anypoint Platform 組織に存在するカテゴリに対して検証されます。

形式: <カテゴリ名>: <値>

このオプションが指定されていない場合、カテゴリは追加されません。

customFields

項目と値を指定するキー-値のペアのリスト。これらのペアは、Anypoint Platform 組織に存在するカスタム項目とデータ型に対して検証されます。

形式: <項目>: <値>

このオプションが指定されていない場合、カスタム項目は追加されません。

tags

自由テキスト文字列のリスト。

このオプションが指定されていない場合、タグは追加されません。

version

API のバージョン。

これが指定されていない場合、バージョン戦略でバージョンが設定されます。

versionStrategy

グローバルプロジェクトレベルまたは API プロジェクトレベルでアセットのバージョン戦略を設定できます。バージョン戦略が指定されていない場合、パッチバージョンは 1 つずつ増分します。

使用可能な値を次に示します。

  • majorIncrease:​ 記述子の ​version​ 項目と一致する最新バージョンを検索し、メジャーバージョンを増分します。アセットが development ライフサイクル状態である場合、バージョンが増分し、アセットは development のままになります。アセットが stable バージョンである場合、新しい stable バージョンがパブリッシュされます。

  • minorIncrease:​ 記述子の ​version​ 項目と一致する最新バージョンを検索し、マイナーバージョンを増分します。アセットが development ライフサイクル状態である場合、バージョンが増分し、アセットは development のままになります。アセットが stable バージョンである場合、新しい stable バージョンがパブリッシュされます。

  • patchIncrease (デフォルト):​ 記述子の ​version​ 項目と一致する最新バージョンを検索し、パッチバージョンを増分します。アセットが development ライフサイクル状態である場合、バージョンが増分し、アセットは development のままになります。アセットが stable バージョンである場合、新しい stable バージョンがパブリッシュされます。

  • Snapshot​: 記述子ファイルで指定されたバージョンで development 状態のアセットをパブリッシュします。アセットが存在しない場合は、​development​ 状態で作成します。アセットが存在する場合、パブリッシュして ​development​ のままにします。

  • Fixed​: 記述子ファイルで指定されたバージョンで stable 状態のアセットをパブリッシュします。アセットが存在しない場合は作成します。アセットが存在し、development である場合、​stable​ に昇格します。アセットが ​stable​ 状態で、このバージョンがすでにパブリッシュされている場合、失敗します。

    Exchange でのアセットのバージョン設定についての詳細は、​「API アセットのバージョンの変更」​を参照してください。

apiVersion

アセットの API バージョン。

記述子ファイルで API バージョンが指定されていない場合、仕様ファイルのバージョンが使用されます。両方のファイルで API バージョンが指定されている場合、記述子ファイルの値が使用されます。値はいずれかのファイルで指定されている必要があります。

例: v1

ref

projects​ セクションで前述のタグを使用してプロジェクトの API を記述する代わりに、次の例のように ​ref​ タグを使用して各 API の ​exchange.json​ ファイルを参照できます。

projects:
  - ref: api-spec/async-spec.exchange.json
  - ref: api-spec/codat.exchange.json
  - ref: api-spec/oas-3-spec.exchange.json
  - ref: api-spec/oas-spec.exchange.json

記述子ファイル (手動更新) の例

2 つの API のカタログ情報を記述する記述子ファイル (手動更新) の例を次に示します。

#%Catalog Descriptor 1.0 (1)
triggerConditions: (2)
  branches:
    - main
    - release/(.*)
  tags:
    - support
    - release/(.*)

contact: (3)
  name: 'John Doe'
  email: 'john.doe@org.com'

versionStrategyConditions:
  majorIncrease:
    branches:
      - master
    tags:
      - support
  fixed:
    branches:
      - develop

projects: (4)
  - main: api-spec/codat.json
    assetId: my-awesome-api
    contact:
      name: 'Jane Doe'
      email: 'jane.doe@org.com'
    documentation:
      add: documentation/add.md
    customFields:
      custom: value
      another: field
    tags:
      - codat
      - gcp
    version: 2.0.0
    versionStrategy: majorIncrease
    versionStrategyConditions:
      minorIncrease:
        branches:
          - main
        tags:
          - support
      snapshot:
        branches:
          - develop
    apiVersion: v3

  - main: api-spec/billing-api.json
    assetId: my-awesome-billing-api
    triggerConditions:
      user:
        - admin
    tags:
      - finance
      - aws
    categories:
      API Type:
        - System API
        - Experience API
      Organization:
        - Finance
        - Billing
    version: 1.0.0
    versionStrategy: minorIncrease
    apiVersion: v1
1 記述子ファイルの開始行を入力する
2 トリガー条件を設定する
3 連絡先の名前とメール ID を入力する
4 パブリッシュされる API 情報を指定する

関連情報