你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
使用元数据进行 API 治理
本文提供有关元数据的背景以及如何在 Azure API 中心将其用于 API 治理。 定义和设置元数据以组织和筛选 API 中心中的 API 和其他实体。 元数据可以内置或自定义，并且可以开发元数据架构，以在 API、环境和部署中强制实施一致性。
内置元数据
在 API 中心创建或更新 API、环境和部署时，可以设置某些内置元数据属性，例如 API 类型（REST、WSDL 等）。
下表列出了为 Azure API 中心实体提供的内置元数据。 有关详细信息，请参阅 API 中心 REST API 参考。 表不包括标准 Azure 属性，例如资源标识符、显示标题和说明。 并非所有属性都是必需的。
API
| 元数据 | 说明 | 示例值 |
|---|---|---|
| kind | API 的种类（类型） | REST、SOAP、GraphQL |
| 生命周期阶段 | API 开发生命周期的阶段 | 设计、开发 |
| license | API 的许可证信息 | SPDX 标识符、指向许可证文本的链接 |
| 外部文档 | API 的外部文档的网站 | 指向文档的 URL |
| 联系信息 | API 的联系人 | 电子邮件地址、姓名、URL |
| 服务条款 | API 的服务条款 | 指向服务条款的 URL |
环境
| 元数据 | 说明 | 示例值 |
|---|---|---|
| kind | 环境的种类（类型） | 生产、过渡、开发 |
| 服务器 | 环境的服务器信息 | 类型和指向环境服务器的 URL |
| 服务器类型 | 环境服务器的类型 | API 管理服务器、Kubernetes 服务器、Apigee 服务器 |
| 加入 | 环境的载入信息 | 说明和指向环境的开发人员门户的 URL |
部署
| 元数据 | 说明 | 示例值 |
|---|---|---|
| 服务器 | 部署的服务器信息 | 指向部署服务器的 URL |
| state | 部署的状态 | 活动、非活动 |
自定义元数据
使用 Azure 门户、Azure API 中心 REST API 或 Azure CLI 定义自定义元数据，以帮助在 API 中心组织和筛选 API、环境和部署。 Azure API 中心支持以下类型的自定义元数据。
| 类型 | 描述 | 示例名称 |
|---|---|---|
| boolean | True 或 False | IsInternal |
| 数字 | 数值 | YearOfCreation |
| string | 文本值 | GitHubRepository |
| array | 值列表 | 标记 |
| 内置选项 | 内置的选项列表 | Department |
| object | 由多个类型组成的复杂对象 | APIApprover |
重要
不要在你定义的元数据的标题（名称）中包含任何敏感、机密或个人信息。 这些标题在 Microsoft 用于改进服务功能的监视日志中可见。 但是，其他元数据详细信息和值则是受保护的客户数据。
将元数据分配给实体
可以将自定义元数据属性分配给 API 中心中的 API、环境或部署。 例如，定义 Department 元数据并将其分配给API，以便在注册 API 或添加新 API 版本时，指定负责 API 的部门。
如果分配给实体，则元数据为可选或必需的。 例如，你可能要求仅针对 API 设置 Department 元数据，但允许 YearOfCreation 作为环境的可选元数据。
注意
- 随时定义自定义元数据，并应用于 API 中心的 API 和其他实体。
- 定义自定义元数据后，可以将其分配更改为实体，例如，将 API 从必需更改为可选。
- 可以更改元数据值，但不能删除或更改当前在 API、环境和部署中设置的自定义元数据的类型。 首先从实体中取消分配自定义元数据，然后便可以删除或更改它们。
使用元数据进行治理
使用内置和自定义元数据在 API 中心组织 API、环境和部署。 例如：
通过要求为 API、环境和部署设置某些元数据，在组织中强制实施治理标准。
按元数据值在 API 中心搜索和筛选 API。 可以直接在 Azure 门户中的 API 页上进行筛选，或使用 Azure API 中心 REST API 或 Azure CLI 根据特定元数据的值查询 API。
