チュートリアル: API インベントリに API を登録する

  • [アーティクル]

このチュートリアルでは、Azure portal を使って API を登録し、メタデータを割り当てることで、組織の API センターで API インベントリを開始します。

Azure API センターでインベントリを作成できる API、API バージョン、定義、その他のエンティティの背景情報については、「主要な概念」を参照してください。

このチュートリアルでは、ポータルを使用して次のことを行う方法を説明します。

  • 1 つまたは複数の API を登録する
  • API 定義を含む API バージョンを追加する

前提条件

API の登録

API センターに API を登録 (追加) する場合、API の登録には以下が含まれます。

  • タイトル (名前)、種類、説明
  • バージョン情報
  • ドキュメントと連絡先への省略可能なリンク
  • 組み込みとカスタムのメタデータ (自分で定義したもの)

API を登録した後、API にバージョンと定義を追加できます。

以下の手順では、Swagger Petstore API と Conference API という 2 つのサンプル API を登録します (「前提条件」を参照してください)。 必要に応じて、独自の API を登録します。

  1. ポータルで、API Center に移動します。

  2. 左側のメニューにある [資産] で、[API]>[+ API の登録] を選びます。

  3. [API の登録] ページで、Swagger Petstore API に関する次の情報を追加します。 前のチュートリアルで定義したカスタムの "業種" および "一般向け" メタデータがページの下部に表示されます。

    設定 値 説明
    API タイトル 「Swagger Petstore API」と入力します。 API に対して選択した名前。
    [識別] 上記のタイトルを入力すると、Azure API Center によってこの識別子が生成され、この識別子はオーバーライドできます。 API に対する Azure リソース名。
    [API の種類] ドロップダウン リストから [REST] を選択します。 API の種類。
    まとめ 必要に応じて、概要を入力します。 API の説明の概要。
    説明 任意で説明を入力します。 API の説明。
    Version
    バージョン タイトル v1 など、任意のバージョン タイトルを入力します。 API バージョンに対して選択した名前。
    バージョン ID 上記のタイトルを入力すると、Azure API Center によってこの識別子が生成され、この識別子はオーバーライドできます。 バージョンの Azure リソース名。
    バージョンのライフサイクル ドロップダウンから [テスト] や [運用] などの選択を行います。 API バージョンのライフサイクル ステージ。
    外部ドキュメント 必要に応じて、外部ドキュメントへの 1 つ以上のリンクを追加します。 API のドキュメントの名前、説明、および URL。
    ライセンス 必要に応じて、ライセンス情報を追加します。 API のライセンスの名前、URL、ID。
    連絡先情報 必要に応じて、1 つ以上の連絡先の情報を追加します。 API の連絡先の名前、電子メール、URL。
    基幹業務 前のチュートリアルでこのメタデータを追加した場合は、ドロップダウンから選びます (マーケティングなど)。 API を所有する部署を識別するカスタムのメタデータ。
    一般向け このメタデータを追加した場合は、チェックボックスをオンにします。 API が一般向けか社内専用かを識別するカスタムのメタデータ。

    ポータルでの API の登録のスクリーンショット。

  4. ［作成］ を選択します API が登録されます。

  5. 上記の 3 つの手順を繰り返して、Conference API などの別の API を登録します。

ヒント

ポータルで API を登録する場合は、事前に定義された API の種類のいずれかを選択するか、別の種類の API を入力できます。

API は、ポータルの [API] ページに表示されます。 API センターに多数の API を追加したら、このページの検索ボックスとフィルターを使用して、目的の API を見つけます。

ポータルの API ページのスクリーンショット。

API を登録すると、API のプロパティを表示または編集できます。 [API] ページで API を選び、API 登録を管理するためのページを表示します。

API バージョンを追加する

そのライフサイクル全体を通して、API には複数のバージョンを含めることができます。 必要に応じて、1 つまたは複数の定義ファイルを使用して、API センターの既存の API にバージョンを追加できます。

ここでは、次のいずれかの API にバージョンを追加します。

  1. ポータルで、API センターに移動します。

  2. 左側のメニューで、[API] を選択した後、たとえば Swagger Petstore などの API を選択します。

  3. [API] ページの [詳細] で、[バージョン]>[+ バージョンの追加] を選択します。

    ポータルでの API バージョンの追加を示すスクリーンショット。

  4. [API バージョンの追加] ページで、次のことを行います。

    1. 次の情報を入力または選択します。

      設定 値 説明
      バージョン タイトル [v2] など、任意のバージョン タイトルを入力します。 API バージョンに対して選択した名前。
      バージョン ID 上記のタイトルを入力すると、Azure API Center によってこの識別子が生成され、この識別子はオーバーライドできます。 バージョンの Azure リソース名。
      バージョンのライフサイクル [運用] などのドロップダウンから選択します。 API バージョンのライフサイクル ステージ。

    2. ［作成］ を選択します バージョンが追加されます。

バージョンに定義を追加する

通常は、API 定義を API バージョンに追加する必要があります。 Azure API Center では、REST API の OpenAPI 2 や 3 など、一般的なテキスト仕様形式の定義がサポートされています。

バージョンに API 定義を追加するには:

  1. API の [バージョン] ページで、API のバージョンを選びます。

  2. API バージョンの左側のメニューにある [詳細] で、[定義]>[+ 定義の追加] を選びます。

  3. [定義の追加] ページで、次のことを行います。

    1. 次の情報を入力または選択します。

      設定 値 説明
      Title 「v2 定義」など、任意のタイトルを入力します。 API 定義に対して選択する名前。
      [識別] 上記のタイトルを入力すると、Azure API Center によってこの識別子が生成され、この識別子はオーバーライドできます。 定義用の Azure リソース名。
      説明 任意で説明を入力します。 API 定義の説明。
      仕様名 Petstore API の場合は、[OpenAPI] を選択します。 API の仕様形式。
      仕様バージョン 3.0 など、任意のバージョン識別子を入力します。 仕様バージョン。
      Document Petstore API のローカル定義ファイルを参照するか、URL を入力します。 URL の例: https://raw.githubusercontent.com/swagger-api/swagger-petstore/refs/heads/master/src/main/resources/openapi.yaml API 定義ファイル。

      ポータルでの API 定義の追加のスクリーンショット。

    2. ［作成］ を選択します 定義が追加されます。

このチュートリアルでは、ポータルを使用して次のことを行う方法を説明します。

  • 1 つまたは複数の API を登録する
  • API 定義を含む API バージョンを追加する

API インベントリを構築するときは、自動ツールを利用して API を登録します。たとえば、Visual Studio Code 用の Azure API Center 拡張機能や、Azure CLI などです。

次のステップ

API インベントリが形になり始めています。 これで、API 環境とデプロイに関する情報を追加できます。

API 環境とデプロイを追加する