使用英语阅读

通过


你当前正在访问 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 APIAzure 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。

    门户中筛选 API 的屏幕截图。