API ガバナンスのメタデータを使用する
この記事では、メタデータに関する背景と、Azure API Center における API ガバナンスに対するメタデータの使用方法について説明します。 API Center 内の API やその他のエンティティを整理してフィルター処理するために、メタデータを定義して整理します。 メタデータは組み込みにすることもカスタマイズすることもでき、API、環境、デプロイ全体で一貫性を適用するメタデータ スキーマを開発できます。
組み込みメタデータ
API センターで API、環境、デプロイを作成または更新する場合は、API の種類 (REST、WSD など) のような特定の組み込みメタデータ プロパティを設定します。
次の表には、Azure API Center エンティティに提供される組み込みメタデータを一覧表示しています。 詳細については、「API Center REST API リファレンス」を参照してください。 テーブルには、リソース識別子、表示タイトル、説明などの標準的な Azure プロパティは含まれません。 すべてのプロパティが必要なわけではありません。
API
| Metadata | 説明 | サンプル値 |
|---|---|---|
| kind | API の種類 | REST、SOAP、GraphQL |
| ライフサイクル ステージ | API 開発ライフサイクルのステージ | 設計、開発 |
| ライセンス | API のライセンス情報 | SPDX 識別子、ライセンス テキストへのリンク |
| 外部ドキュメント | API の外部ドキュメント向けサイト | ドキュメントを参照する URL |
| 連絡先情報 | API に関するお問い合わせ先 | メール アドレス、名前、URL |
| サービス使用条件 | API のサービス使用条件 | サービス使用条件を参照する URL |
環境
| Metadata | 説明 | サンプル値 |
|---|---|---|
| kind | 環境の種類 | 運用、ステージング、開発 |
| サーバー | 環境のサーバー情報 | 環境サーバーを参照する種類と URL |
| サーバーの種類 | 環境サーバーの種類 | API Management サーバー、Kubernetes サーバー、Apigee サーバー |
| onboarding | 環境のためのオンボード情報 | 環境開発者ポータルを参照する手順と URL |
デプロイ
| Metadata | 説明 | サンプル値 |
|---|---|---|
| サーバー | デプロイのサーバー情報 | デプロイ サーバーを参照する URL |
| 州 | デプロイの状態 | アクティブ、非アクティブ |
カスタム メタデータ
Azure portal、Azure API センター REST API、または Azure CLI を使用してカスタム メタデータを定義し、API Center 内のAPI、環境、デプロイの整理とフィルター処理をサポートします。 Azure API Center は、次の種類のカスタム メタデータをサポートしています。
| 型 | 説明 | 名前の例 |
|---|---|---|
| boolean | true または false | IsInternal |
| 数値 | 数値 | YearOfCreation |
| string | テキスト値 | GitHubRepository |
| 配列 | 値の一覧 | タグ |
| 組み込みの選択 | 組み込みの選択一覧 | 課 |
| オブジェクト | 複数の種類で構成された複合オブジェクト | APIApprover |
重要
定義したメタデータのタイトル (名前) に、機密性の高い、機密性の高い、または個人情報を含めないでください。 これらのタイトルは、サービスの機能を向上させるために Microsoft によって使用される監視ログに表示されます。 ただし、その他のメタデータの詳細と値は、保護された顧客データです。
エンティティへのメタデータの割り当て
カスタム メタデータ プロパティは、API Center の API、環境、またはデプロイに割り当てることができます。 たとえば、API に部署メタデータを定義して割り当て、API が登録されたり、新しい API バージョンが追加されたりしたときに、API の担当部署が指定されるようにします。
エンティティに割り当てられている場合、メタデータは省略可能または必須です。 たとえば、API に対してのみ部署メタデータを設定することを要求し、環境に対しては YearOfCreation をオプションのメタデータとして許可します。
Note
- API Center では、いつでもカスタム メタデータを定義し、API やその他のエンティティに適用できます。
- カスタム メタデータを定義した後、そのエンティティへの割り当てを変更できます (たとえば、API に対して必須から省略可能へなど)。
- メタデータの値を変更することはできますが、API、環境、デプロイに現在設定されているカスタム メタデータの種類を削除または変更することはできません。 最初にカスタム メタデータをエンティティから割り当て解除してから、削除または変更を行うことはできます。
ガバナンスにメタデータを使用する
組み込みメタデータとカスタム メタデータを使用して、API Center 内の API、環境、デプロイを整理します。 次に例を示します。
API、環境、デプロイに特定のメタデータを設定することを要求することで、組織にガバナンス標準を適用します。
API Center の API をメタデータの値で検索し、フィルター処理します。 Azure portal の API ページで直接フィルター処理するか、Azure API Center REST API または Azure CLI を使用して、特定のメタデータの値に基づいて API にクエリを実行できます。
