你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

使用 Azure CLI 管理 API 清单

本文介绍如何使用 Azure CLI 中的 az apic api 命令在 API 中心清单中添加和配置 API。 使用 Azure CLI 中的命令编写操作脚本,以管理 API 中心的 API 清单和其他方面。

先决条件

  • Azure 订阅中的 API 中心。 如果尚未创建 API 中心,请参阅快速入门:创建 API 中心

  • 对于 Azure CLI:

    注意

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

    请参阅最新更改的发行说明apic-extension 中的更新。

注册 API、API 版本和定义

以下步骤演示如何创建 API 并关联单个 API 版本和 API 定义。 有关 Azure API 中心中数据模型的背景信息,请参阅关键概念

创建 API

使用 az apic api create 命令在 API 中心创建 API。

以下示例会在 myResourceGroup 资源组和 myAPICenter API 中心中创建一个名为 Petstore API 的 API。 该 API 是一个 REST API。

az apic api create  --resource-group myResourceGroup \
    --service-name myAPICenter --api-id petstore-api \
    --title "Petstore API" --type "rest"

注意

创建 API 后,可以使用 az apic api update 命令更新 API 的属性。

创建 API 版本

使用 az apic api version create 命令为 API 创建版本。

以下示例会为在上一部分中创建的 petstore-api API 创建一个名为 v1-0-0 的 API 版本。 版本设置为测试生命周期阶段。

az apic api version create --resource-group myResourceGroup \
    --service-name myAPICenter --api-id petstore-api \
    --version-id v1-0-0 --title "v1-0-0" --lifecycle-stage "testing"

创建 API 定义并添加规范文件

使用 az apic api definition 命令为 API 版本添加定义和随附的规范文件。

创建定义

以下示例使用 az apic api definition create 命令为在上一部分中创建的 petstore-api API 版本创建一个名为 openapi 的定义。

az apic api definition create --resource-group myResourceGroup \
    --service-name myAPICenter --api-id petstore-api \
    --version-id v1-0-0 --definition-id openapi --title "OpenAPI"

导入规范文件

使用 az apic api definition import-specification 命令将规范文件导入定义。

以下示例将 OpenAPI 规范文件从可公开访问的 URL 导入到在上一步中创建的 openapi 定义。 规范资源的 nameversion 属性作为 JSON 传递。

az apic api definition import-specification \
    --resource-group myResourceGroup --service-name myAPICenter \
    --api-id petstore-api --version-id v1-0-0 \
    --definition-id openapi --format "link" \
    --value 'https://petstore3.swagger.io/api/v3/openapi.json' \
    --specification '{"name":"openapi","version":"3.0.2"}'

提示

可以通过将 --format 参数设置为 inline 并使用 --value 参数传递文件内容来内联导入规范文件。

导出规范文件

若要将 API 规范从 API 中心导出到本地文件,请使用 az apic api definition export-specification 命令。

以下示例将在上一部分中创建的 openapi 定义中的规范文件导出到名为 specificationFile.json 的本地文件。

az apic api definition export-specification \
    --resource-group myResourceGroup --service-name myAPICenter \
    --api-id petstore-api --version-id v1-0-0 \
    --definition-id openapi --file-name "/Path/to/specificationFile.json"

从规范文件注册 API - 单个步骤

可以使用 az apic api register 命令从本地规范文件注册 API,只需一步即可。 使用此选项,会自动为 API 创建默认 API 版本和定义。

以下示例通过名为 specificationFile.json 的本地 OpenAPI 定义文件在 API 中心 myAPICenter 中注册一个 API。

az apic api register --resource-group myResourceGroup \
    --service-name myAPICenter --api-location "/Path/to/specificationFile.json"
  • 该命令会设置定义文件中值的 API 属性(例如名称和类型)。
  • 默认情况下,该命令将 API 的“生命周期阶段”设置为“设计”。
  • 它会创建一个根据 API 定义中的 version 属性命名的 API 版本(默认为 1-0-0 ),以及一个根据规范格式命名的 API 定义(例如 openapi)

注册 API 后,可以使用 az apic api updateaz apic api version updateaz apic api definition update 命令来更新 API 的属性。

删除 API 资源

使用 az apic api delete 命令删除 API 及其所有版本和定义资源。 例如:

az apic api delete \
    --resource-group myResoureGroup --service-name myAPICenter \
    --api-id petstore-api

若要删除单个 API 版本和定义,请分别使用 az apic api version deleteaz apic api definition delete