你当前正在访问 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 属性,例如资源标识符、显示标题和说明。 并非所有属性都是必需的。
元数据 | 说明 | 示例值 |
---|---|---|
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。