Azure API Center のプラットフォーム API カタログを有効にして表示する
この記事では、エンタープライズ開発者が Azure API Center の Visual Studio Code 拡張機能で Azure API Center のプラットフォーム API カタログ (プレビュー) にアクセスできるようにする方法について説明します。 プラットフォーム API カタログを使用すると、開発者は、API センター自体を管理したり、API をインベントリに追加したりするためのアクセス権がない場合に、Azure API センターで API を検索し、API 定義を表示し、必要に応じて API クライアントを生成できます。 プラットフォーム API カタログへのアクセスは、Microsoft Entra ID と Azure ロールベースのアクセス制御を使用して管理されます。
ヒント
Visual Studio Code 拡張機能は、Azure API センターを管理するアクセス許可を持つ API 開発者にさらに多くの機能を提供します。 たとえば、API 開発者は、API センターで直接、または CI/CD パイプラインを使用して API を登録できます。 詳細情報
前提条件
API センター管理者の場合
Azure サブスクリプション内の API センター。 まだ作成していない場合は、「クイック スタート: API センターを作成する」を参照してください。
Azure サブスクリプションに関連付けられている Microsoft Entra テナントでアプリ登録を作成するためのアクセス許可と、API センター内のデータへのアクセス権を付与するためのアクセス許可。
アプリ開発者の場合
Visual Studio Code 用 Azure API Center 拡張機能
重要
現在、プラットフォーム API カタログへのアクセスは、拡張機能のプレリリース バージョンでのみ使用できます。 Visual Studio Code Marketplace から拡張機能をインストールする場合、リリース バージョンまたはプレリリース バージョンを選択してインストールできます。 拡張機能ビューで拡張機能の [管理] ボタンのコンテキスト メニューを使用して、いつでも 2 つのバージョンを切り替えることができます。
次の Visual Studio Code 拡張機能はオプションです。
- Microsoft Kiota 拡張機能 - API クライアントを生成する
API センター管理者がカタログへのアクセスを有効にする手順
次のセクションでは、API センター管理者がエンタープライズ開発者をプラットフォーム API カタログにアクセスできるようにする手順について説明します。
Microsoft Entra アプリ登録を作成する
まず、Microsoft Entra ID テナントでアプリ登録を構成します。 アプリの登録により、Azure API Center の Visual Studio Code 拡張機能が、サインインしているユーザーに代わってプラットフォーム API カタログにアクセスできるようになります。
Azure portal で、[Microsoft Entra ID]>[アプリの登録] の順に移動します。
[+ 新規登録] を選択します。
[アプリケーションを登録] ページで、次のように値を設定します。
- 名前を、platform-api-catalog などのわかりやすい名前に設定します
- [サポートされているアカウントの種類] で、[この組織ディレクトリに含まれるアカウント (シングル テナント)] を選択します。
- [リダイレクト URI] で、[シングルページ アプリケーション (SPA)] を選択し、URI を API センターのランタイム URI に設定します。 たとえば、
https://<service name>.data.<region>.azure-apicenter.msのようにします。 例:https://contoso-apic.data.eastus.azure-apicenter.ms。 - 登録 を選択します。
ヒント
同じアプリ登録を使用して、さらに多くの API センターにアクセスできます。 [リダイレクト URI] で、プラットフォーム API カタログに表示する他の API センターに対するリダイレクト URI の追加を続けます。
[概要] ページのアプリケーション (クライアント) ID とディレクトリ (テナント) ID をコピーします。 これらの値は、後で Visual Studio Code 拡張機能から API センターに接続するときに設定します。
左側のメニューの [管理] で、[認証]>[+ プラットフォームの追加] を選択します。
[プラットフォームの構成] ページで、[モバイル アプリケーションとデスクトップ アプリケーション] を選択します。
[デスクトップとデバイスの構成] ページで、次のリダイレクト URI を入力し、[構成] を選択します。
https://vscode.dev/redirect左側のメニューにある [管理] で、[API のアクセス許可]>[+ アクセス許可の追加] を選択します。
[API アクセス許可の要求] ページで、次の操作を行います。
- [所属する組織で使用している API] タブを選択します。
- [Azure API センター] を検索して選択します。 また、アプリケーション ID
c3ca1a77-7a87-4dba-b8f8-eea115ae4573を検索して選択することもできます。 - [アクセス許可の選択] ページで、[user_impersonation] を選択します。
- アクセス許可の追加 を選択します。
Azure API センターのアクセス許可は、[構成されたアクセス許可] に表示されます。
Microsoft Entra ユーザーとグループによるプラットフォーム API カタログへのサインインを有効にする
エンタープライズ開発者は、API センターのプラットフォーム API カタログを表示するには、Microsoft アカウントでサインインする必要があります。 必要に応じて、Microsoft Entra テナントに開発者を追加または招待します。
次に、サインインを有効にするには、API センターをスコープとするテナント内のユーザーまたはグループに Azure API Center データ閲覧者ロールを割り当てます。
重要
既定では、API センターの管理者は、API Center 拡張機能のプラットフォーム API カタログ内の API にアクセスできません。 管理者に Azure API センター データ閲覧者ロールを必ず割り当ててください。
ユーザーとグループにロールを割り当てるための詳細な前提条件と手順については、「Azure portal を使用して Azure ロールを割り当てる」を参照してください。 簡単な手順を次に示します。
- Azure portal で、API センターに移動します。
- 左側のメニューで、[アクセス制御 (IAM)]>[+ ロールの割り当ての追加] の順に選択します。
- [ロールの割り当ての追加] ペインで、次のように値を設定します。
- [ロール] ページで、[Azure API センター データ閲覧者] を検索して選択します。 [次へ] を選択します。
- [メンバー] ページの [アクセスの割り当て先] で、[ユーザー、グループ、またはサービス プリンシパル]>[+ メンバーの選択] の順に選択します。
- [メンバーの選択] ページで、ロールを割り当てるユーザーまたはグループを検索して選択します。 [選択]、[次へ] の順にクリックします。
- ロールの割り当てを確認し、[レビューと割り当て] を選択します。
- 上記の手順を繰り返して、他の API センターのプラットフォーム API カタログへのサインインを有効にします。
Note
新しいユーザーのアクセス構成を効率化するには、Microsoft Entra グループにロールを割り当て、動的グループのメンバーシップの規則を構成することをお勧めします。 詳細については、「Microsoft Entra ID で動的グループを作成または更新する」を参照してください。
エンタープライズ開発者がプラットフォーム API カタログにアクセスするための手順
開発者は、次の手順に従って接続してサインインし、Visual Studio Code 拡張機能を使用してプラットフォーム API カタログを表示できます。 API センターに接続するための設定は API センター管理者が行う必要があります。
API センターに接続する
Visual Studio Code 用 Azure API Center 拡張機能のプレリリース バージョンを Visual Studio Code に対してインストールします。
Visual Studio Code の左側の [アクティビティ] バーで、[API Center] を選択します。
Ctrl + Shift + P のキーボード ショートカットを使ってコマンド パレットを開きます。 「Azure API Center: Connect to an API Center」と入力し、Enter を押します。
プロンプトに応答して、次の情報を入力します。
- API センターのランタイム URL で、形式は
<service name>.data.<region>.azure-apicenter.ms(先頭にhttps://を付けないでください)。 例:contoso-apic.data.eastus.azure-apicenter.ms。 このランタイム URL は、Azure portal の API センターの [概要] ページに表示されます。 - 前のセクションで管理者によって構成されたアプリ登録のアプリケーション (クライアント) ID。
- 前のセクションで管理者によって構成されたアプリ登録のディレクトリ (テナント) ID。
ヒント
API センター管理者は、これらの接続の詳細を開発者に提供するか、次の形式で直接リンクを提供する必要があります。
vscode://apidev.azure-api-center?clientId=<Client ID>&tenantId=<tenant ID>&runtimeUrl=<service-name>.data.<region>.azure-apicenter.msAPI センターに接続すると、API センターの名前が API Center プラットフォーム API カタログに表示されます。
- API センターのランタイム URL で、形式は
API センターの API を表示するには、API センター名の下で [Azure にサインイン] を選択します。 サインインは、API センターで Azure API Center データ閲覧者ロールが割り当てられた Microsoft アカウントで可能です。
サインインした後、[API] を選択して API センターの API を一覧表示します。 [API] を展開して、そのバージョンと定義について確認します。
アクセスが構成されている場合は、上記の手順を繰り返して、他の API センターに接続します。
カタログ内の API を検索して利用する
プラットフォーム API カタログは、エンタープライズ開発者が API の詳細を検索し、API クライアント開発を開始するのに役立ちます。 開発者は、プラットフォーム API カタログ内の API 定義を右クリックして、次の機能にアクセスできます。
- API 仕様ドキュメントのエクスポート - 定義から API 仕様をエクスポートし、ファイルとしてダウンロードします
- API クライアントの生成 - Microsoft Kiota 拡張機能を使用して、好みの言語の API クライアントを生成します
- Markdown の生成 - API ドキュメントを Markdown 形式で生成します
- OpenAPI ドキュメント - API 定義のドキュメントを表示し、Swagger UI で操作を試すことができます (OpenAPI 定義でのみ使用可能)
トラブルシューティング
エラー: 未定義のプロパティを読み取れません ("nextLink" の読み取り)
特定の条件下では、API Center プラットフォーム API カタログにサインインし、API センターの API 一覧を展開した後、次のエラー メッセージが表示される場合があります。
Error: Cannot read properties of undefined (reading 'nextLink')
ユーザーに API センターの Azure API Center データ閲覧者ロールが割り当てられていることを確認します。 必要に応じて、ユーザーにロールを再割り当てします。 次に、Visual Studio Code 拡張機能で API Center プラットフォーム API カタログを更新します。
Azure にサインインできない
Azure API Center データ閲覧者ロールが割り当てられているユーザーが、プラットフォーム API カタログで [Azure にサインイン] を選択した後、サインイン フローを完了できない場合は、接続の構成に問題がある可能性があります。
Microsoft Entra ID で構成したアプリ登録の設定を確認します。 アプリ登録のアプリケーション (クライアント) ID とディレクトリ (テナント) ID の値と API センターのランタイム URL を確認します。 その後、API センターへの接続をもう一度設定します。
Microsoft Entra ID アプリの登録で Azure API Center のアクセス許可を選択できない
API センター ポータルの Microsoft Entra アプリ登録で Azure API センターへの API のアクセス許可を要求できない場合は、[Azure API センター] (またはアプリケーション ID c3ca1a77-7a87-4dba-b8f8-eea115ae4573) を検索していることを確認します。
アプリが存在しない場合は、サブスクリプションでの Microsoft.ApiCenter リソース プロバイダーの登録に問題がある可能性があります。 リソース プロバイダーの再登録が必要になることがあります。 これを行うには、Azure CLI で次のコマンドを実行します。
az provider register --namespace Microsoft.ApiCenter
リソース プロバイダーを再登録した後、もう一度 API のアクセス許可を要求してみてください。