API 中心入门

10 分钟

通过学习本练习，你将能够：

创建 API 中心服务。
定义元数据属性。
将 API 添加到 API 中心。
添加部署和环境。

先决条件

若要开始通过 API 中心管理 API，需要：

Azure 订阅。
订阅中注册的Microsoft.ApiCenter资源提供程序。
在 Azure 订阅中至少拥有参与者角色分配或等效权限。

注意

如果尚未注册，则需要在订阅中注册 Microsoft.ApiCenter 资源提供程序。

登录 Azure 门户。
在搜索栏中输入订阅。
选择要在其中创建 API 中心的订阅。
在左侧菜单的“资源”下，选择“资源提供程序”。
在资源提供程序列表中，搜索“Microsoft.ApiCenter”。如果尚未注册，请选择“注册”。

步骤 1：创建 API 中心服务

登录 Azure 门户。
在搜索栏中输入“API 中心”。
选择“+ 新建”。
在“基本信息”选项卡上，选择或输入以下设置：

a. 选择 Azure 订阅。

b. 选择现有资源组，或选择“新建”创建一个新资源组。

c. 输入 API 中心的名称。在创建 API 中心的区域中，它必须是唯一的。

d. 在“区域”中，为 API 中心选择其中一个可用区域。

e. 对于定价计划，请选择“免费试用（90 天 0 美元）”。

f. 选择“查看 + 创建”。

h.如果该值不存在，请单击“添加行”。验证完成后，选择“创建”。

部署后，API 中心可供你使用！

若要在本地运行 CLI 引用命令，请安装 Azure CLI，并使用以下命令登录。

az login

注意

如果尚未注册，则需要在订阅中注册 Microsoft.ApiCenter 资源提供程序。

运行以下命令，注册资源提供程序

az provider register –namespace Microsoft.ApiCenter

步骤 1：创建 API 中心服务

通过运行以下命令创建资源组，传递：

资源组名称示例 --name。 Contoso
location 示例 --location。 Eastus

az group create –-name contoso –-location eastus

显示成功的 az group create CLI 命令的屏幕截图

注意

az apic命令需要apic-extension Azure CLI 扩展。如果尚未使用az apic命令，则运行第一个az apic命令时，该扩展将动态安装，也可以手动安装该扩展。详细了解 Azure CLI 扩展。

通过运行以下命令创建 API 中心，传递：

API 中心服务名称示例 -n。 contoso-apis
资源组示例 -g。 Contoso
location 示例 --l。 Eastus

az apic create -n contoso-apis -g contoso -l eastus

注意

默认情况下，API 中心将在“免费定价层”下创建。

注意

VS Code 目前不支持创建 API 中心服务。请使用 Azure CLI 或 Azure 门户创建一个。

步骤 2：定义元数据属性

API 中心使用元数据属性在清单中组织 API，并启用筛选、搜索等操作。

注意

不要在元数据属性标题/名称中包含任何敏感、机密或个人信息。

与其他许多组织一样，Contoso 也希望让其所有 API 在可供使用之前通过审批者的审批，并确保对所有 API 进行合规性评审。该组织还具有面向公众的 API，以及专为内部使用而构建的 API。为了在所有 API 之间大规模强制实施此操作，我们添加了三个自定义元数据属性：

“字符串”类型的“API 审批者”
“预定义选项”类型的“合规性评审”
“布尔”类型的“面向公众”

在左侧菜单中，依次选择“资产”>“元数据”>“+ 新建元数据”。
在“详细信息”选项卡上，输入有关属性的信息。

a. 在“标题”中，输入“API 审批者”

b. 在“说明”中，输入“默认 API 审批者”

c. 选择“字符串”类型，然后选择“下一步”
在“分配”选项卡上，为 API 选择“必需”。为“部署和环境”选择“可选”。选择下一个
选择“创建”
对“面向公众”属性重复相同的步骤，如下图所示。对于类型，请选择“布尔”
在“分配”选项卡上，为 API 选择“必需”。为“部署和环境”选择“不适用”。选择下一个
选择“创建”
对“合规性评审”属性重复相同的步骤，如下图所示。对于类型，请选择“预定义选项”并添加 3 个选项：“未启动”、“正在进行”和“已完成”
在“分配”选项卡上，为 API 选择“必需”。为“部署和环境”选择“不适用”
选择下一个

API 的 JSON 元数据架构现在可供查看、编辑和下载。若要查看，请选择“查看元数据架构”，并从下拉列表中选择“API”。

这将在右侧打开包含元数据详细信息的模式，其中包括 API 中心的内置属性，例如 LifecycleStage、Name、Description、TermsOfService 等。如果滚动到文件底部，你将看到在前面步骤中添加的自定义元数据，如下所示。显示在 Azure 门户中查看元数据架构的步骤的屏幕截图

注意

可以随时在架构中添加和编辑属性，并立即将其应用到 API 中心中的所有 API

运行以下命令以新建元数据架构，从而设置：

元数据名称为api 审批者
架构，属性类型为字符串，标题为API 审批者
分配对于API是必需项，对于环境和部署是可选项

az apic metadata create -g contoso -n contoso-apis --metadata-name "api-approver" --schema '{"type":"string","title":"API Approver"}' --assignments '[{entity:api,required:true,deprecated:false},{entity:environment,required:true,deprecated:false}]'

对以下内容重复相同的步骤：

元数据名称为面向公众
架构，属性类型为布尔，标题为面向公众
分配对于API是必需项，对于环境和部署是可选项

通过运行以下命令：

az apic metadata create -g contoso -n contoso-apis --metadata-name "public-facing" --schema '{"type":"boolean", "title":"Public Facing"}' --assignments '[{entity:api,required:true,deprecated:false},{entity:environment,required:true,deprecated:false}]'

最后，对以下内容重复相同的步骤：

元数据名称为合规性评审
架构，属性类型为字符串，标题为合规性评审
分配对于API是必需项，对于环境和部署是可选项

通过运行以下命令：

az apic metadata create -g contoso -n contoso-apis --metadata-name "compliance-review" --schema '{"type":"string","title":"Compliance Review", "oneOf":[{"const":"Not Started","description":""},{"const":"In Progress","description":""},{"const":"Completed","description":""}]}' --assignments '[{entity:api,required:true,deprecated:false},{entity:environment,required:true,deprecated:false}]'

可以运行以下命令，以在 API 中心内查看所有已定义元数据的列表。

az apic metadata list -g <resource-group-name> -n <api-center-name>

注意

可以随时在架构中添加和编辑属性，并立即将其应用到 API 中心中的所有 API

注意

VS Code 中当前不支持此操作。请使用 Azure CLI 或 Azure 门户创建一个。

步骤 3：将 API 添加到清单

Contoso 组织希望为其工程团队推荐技术会议，作为内部技能提升的一部分。我们将添加具有演讲者、会话和主题的会议 API。

会议 API URL：https://bigconference.azurewebsites.net/

对于以下步骤，可以从上述网站复制 OpenAPI 定义并以 JSON 文件格式将其保存在本地计算机。或者，在将 API 添加到库存时替换不同的 API 定义。

在门户中，导航到你的 API 中心。
在左侧菜单中，依次选择“资产”>“API”>“+ 注册 API”。
在“注册 API”页中，添加 API 的以下必需信息。你将在页面底部看到在前面步骤中定义的自定义元数据属性：“API 审批者”、*“面向公众”和“合规性评审”。

若要查看创建的 API，请在左侧菜单中依次选择“资产”>“API”>“会议 API”。

“概述”选项卡提供了 API 配置的视图。展开“详细信息”以查看和编辑其他信息，例如 API 版本和部署（目前没有部署）。

通常需要为 API 版本添加 API 定义，API 中心支持文本规范格式，包括 OpenAPI 2、OpenAPI 3 for REST。

若要添加定义，请执行以下操作：

在左侧菜单中，依次选择“资产”>“API”> 选择 API（会议 API）。
展开“详细信息”并选择“版本”。
选择版本 (v1)，然后展开“详细信息”。
在“详细信息”下，依次选择“定义”>“添加定义”。

可以使用适用于 Visual Studio Code 的 Azure API 中心扩展将 API 注册到 API 实例。

步骤 1：安装扩展

步骤 2：打开命令托盘，按“Ctrl + Shift + P”并键入“API 中心：注册 API”

按照提示提供 API 的以下信息：

注册 API	分步操作
选择 API 中心服务	选择 API 中心实例
API 标题	输入 API 的名称（会议 API）
API 类型	REST
API 版本标题	输入 API 的版本名称 (v1)
API 版本生命周期	从下拉列表中选择一个生命周期（开发）
API 定义标题	输入定义的名称（会议 API 定义）
API 规范名称	从下拉列表中选择一个规范 (OpenAPI 2)
选择要导入的 API 定义文件	从存储中浏览并选择定义文件

显示在 VS Code 上注册 API 的步骤的屏幕截图

刷新 API 中心扩展选项卡，新创建的 API 将显示在相应的 APIC 实例/资源中。

使用以下命令创建新的 API，传入：

资源组示例 -g。 Contoso
API 中心服务名称示例 -n。 contoso-api-center
标题示例 --title。会议 API
API ID 示例 --api-id。 conference-api
类型示例 --type。 REST

az apic api create -g contoso -n contoso-apis --title "Conference API" --api-id conference-api --type REST

使用以下命令创建 API 版本，传入：

资源组示例 -g。 contoso
API 中心服务名称示例 -n。 contoso-apis
API ID 示例 --api-id。 conference-api
标题示例 --title。 v1.2.2
版本 ID 示例 --version-id。 2024-07-03
生命周期阶段示例 --lifecycle-stage。设计

az apic api version create -g contoso -n contoso-apis --api-id conference-api --title v1.2.2 --version-id 2024-07-03 --lifecycle-stage design

还可以为 API 版本添加 API 定义，API 中心支持文本规范格式，包括 OpenAPI 2、OpenAPI 3 for REST。

若要获取定义，请使用以下命令，传入：

资源组示例 -g。 contoso
API 中心服务名称示例 -n。 contoso-apis
API ID 示例 --api-id。 conference-api
版本 ID 示例 --version-id。 2024-07-03
标题示例 --title。 OpenAPI
定义 ID 示例 --definition-id。 openapi

az apic api definition create -g contoso -n contoso-apis --api-id conference-api --version-id 2024-07-03 --title OpenAPI --definition-id openapi

若要从 URL 导入 OpenAPI 定义文件，请使用 az apic api definition import-specification 命令导入。示例： https://learn.microsoft.com/cli/azure/apic/api/definition?view=azure-cli-latest#az-apic-api-definition-import-specification-examples

az apic api definition import-specification -g contoso -n contoso-apis --api-id conference-api --version-id 2024-07-03 --definition-id openapi --format "link" --value 'https://petstore3.swagger.io/api/v3/openapi.json' --specification '{"name":"openapi","version":"3.0.2"}'

步骤 4：添加部署和环境

环境

环境（开发、测试、暂存或生产）表示部署 API 运行时的位置。 Contoso 的 API 平台工程师在其 API 中心实例中定义两个环境：测试和生产，用于管理和跟踪其组织中的不同 API 运行时。

若要创建环境，请执行以下操作：

在左侧菜单中，依次选择“资源”>“环境”>“+ 新建环境”。
添加以下信息。
选择创建。
对生产环境重复相同的步骤。

要创建环境，请运行以下 CLI 命令

az apic environment create -g contoso -n contoso-apis --title ContosoTesting --environment-id contosotesting --type testing

对生产环境重复相同的操作

az apic environment create -g contoso -n contoso-apis-new --title ContosoProduction --environment-id contosoproduction --type production

注意

VS Code 目前不支持创建环境。请对此步骤使用 Azure CLI 或 Azure 门户选项。

部署

将为给定环境中的每个 API 运行时提供一个唯一位置（地址），供用户与 API 交互。此位置称为部署，单个 API 版本可以有两个部署：一个暂存部署和一个生产部署。

Contoso 有一个 API，即会议 API，我们将其与创建的环境相关联。

在门户中，导航到你的 API 中心。
在左侧菜单中，选择“API”，然后选择一个 API，例如“会议 API”。
在“会议 API”页上，依次展开“详细信息”>“部署”>“+ 添加部署”。
添加以下信息：

a. 从“环境”字段的下拉列表中选择“Contoso 测试”。

b. 对于定义，请单击“选择”，从下拉列表中选择 API 版本“v1”，然后选择前面添加的定义。单击“选择”。

c. 成功添加定义后，添加一个特定于所选环境中的 API 的基本运行时 URL。

要创建部署并将其与在上述步骤中创建的环境相关联，请运行以下 CLI 命令

az apic api deployment create -g contoso-corporation -s contoso-api-center --deployment-id "v1-conference-api" --title "Conference OpenAPI 2" --description "Conference Demo API deployment." --api-id conference-api --environment-id "/workspaces/default/environments/contoso-testing" --definition-id "/workspaces/default/apis/conference-api/versions/v1/definitions/conference-openapi-2" --server '{"runtimeUri":["https://conferenceapi.azurewebsites.net/"]}'

显示用于创建部署的 CLI 命令的屏幕截图

注意

VS Code 目前不支持创建部署。请对此步骤使用 Azure CLI 或 Azure 门户选项。

API 中心入门

先决条件

步骤 1：创建 API 中心服务

步骤 1：创建 API 中心服务

步骤 2：定义元数据属性

步骤 3：将 API 添加到清单

步骤 4：添加部署和环境

环境

部署

反馈