本文介绍如何导入 https://conferenceapi.azurewebsites.net?format=json 中的“OpenAPI 规范”后端 API。 此后端 API 由 Microsoft 提供并托管在 Azure 上。 此外,介绍如何测试 APIM API。
https://conferenceapi.azurewebsites.net?format=json
在本文中,学习如何:
API 导入限制和已知问题 中记录了 API 导入限制。
API 管理实例。 如果你还没有 API 管理服务实例,请完成以下快速入门: 创建 Azure API 管理实例 。
Azure CLI
在 Azure Cloud Shell 中使用 Bash 环境。 有关详细信息,请参阅 Azure Cloud Shell 中的 Bash 快速入门 。
如需在本地运行 CLI 参考命令,请 安装 Azure CLI。 如果在 Windows 或 macOS 上运行,请考虑在 Docker 容器中运行 Azure CLI。 有关详细信息,请参阅 如何在 Docker 容器中运行 Azure CLI 。
如果使用的是本地安装,请使用 az login 命令登录到 Azure CLI。 若要完成身份验证过程,请遵循终端中显示的步骤。 有关其他登录选项,请参阅 使用 Azure CLI 登录 。
出现提示时,请在首次使用时安装 Azure CLI 扩展。 有关扩展详细信息,请参阅 使用 Azure CLI 的扩展 。
运行 az version 以查找安装的版本和依赖库。 若要升级到最新版本,请运行 az upgrade 。
以下示例使用 az apim api import 命令将 OpenAPI 规范从指定的 URL 导入到名为 apim-hello-world 的 API 管理实例。 若要使用规范的路径而不是 URL 进行导入,请使用 --specification-path 参数。
--specification-path
# API Management service-specific details APIMServiceName="apim-hello-world" ResourceGroupName="myResourceGroup" # API-specific details APIId="demo-conference-api" APIPath="conference" SpecificationFormat="OpenAPI" SpecificationURL="https://conferenceapi.azurewebsites.net/?format=json" # Import API az apim api import --path $APIPath --resource-group $ResourceGroupName \ --service-name $APIMServiceName --api-id $APIId \ --specification-format $SpecificationFormat --specification-url $SpecificationURL 导入 API 后,如果需要,可以使用 az apim api update 命令更新设置。 以下示例使用 Import-AzApiManagementApi Azure PowerShell cmdlet 将 OpenAPI 规范从指定的 URL 导入到名为 apim-hello-world 的 API 管理实例。 若要使用规范的路径而不是 URL 进行导入,请使用 -SpecificationPath 参数。 # API Management service-specific details $apimServiceName = "apim-hello-world" $resourceGroupName = "myResourceGroup" # API-specific details $apiId = "demo-conference-api" $apiPath = "conference" $specificationFormat = "OpenAPI" $specificationUrl = "https://conferenceapi.azurewebsites.net/?format=json" # Get context of the API Management instance. $context = New-AzApiManagementContext -ResourceGroupName $resourceGroupName -ServiceName $apimServiceName # Import API Import-AzApiManagementApi -Context $context -ApiId $apiId -SpecificationFormat $specificationFormat -SpecificationUrl $specificationUrl -Path $apiPath 导入 API 后,如果需要,可以使用 Set-AzApiManagementApi cmdlet 更新设置。 在门户中测试新的 API 可直接从管理门户调用操作,这为管理员查看和测试 API 的操作提供了一种方便的方式。 选择上一步中创建的 API。 选择“测试”选项卡。 选择操作。 该页将显示查询参数的字段和标头的字段。 在测试控制台中,API 管理自动填充 Ocp-Apim-Subscription-Key 标头,并配置内置全访问订阅的订阅密钥。 此密钥允许访问 API 管理实例中的每个 API。 可选择性地通过选择 HTTP 请求旁的“眼睛”图标来显示 Ocp-Apim-Subscription-Key 标头。 根据操作,输入查询参数值、标头值或请求正文。 选择“发送”。 当测试成功时,后端会使用成功的 HTTP 响应代码和某些数据进行响应。 默认情况下,测试控制台会将请求发送到 API 管理的 CORS 代理,该代理将请求转发到 API 管理实例,后者又将请求转发到后端。 此代理使用公共 IP 地址 13.91.254.72,并且只能访问公共终结点。 如果要将请求直接从浏览器发送到API 管理服务,请选择“绕过 CORS 代理”。 如果要使用测试控制台,并且 API 管理网关与网络隔离或不允许来自 CORS 代理的流量,请使用此选项。 若要调试 API,请参阅教程:使用请求跟踪调试 API。 追加其他 API 可以为不同服务公开的 API 撰写 API,包括: OpenAPI 规范 SOAP API GraphQL API Azure 应用服务中托管的 Web 应用 Azure 函数应用 Azure 逻辑应用 Azure Service Fabric 按照以下步骤将其他 API 追加到现有 API。 导入另一个 API 时,操作将追加到当前 API 后面。 在 Azure 门户中转到自己的 Azure API 管理实例。 在概述页面上或左侧的菜单上选择“API” 。 单击要将另一个 API 追加到的 API 旁边的“...”。 从下拉菜单中选择“导入”。 选择要从中导入 API 的服务。 根据 OpenAPI 规范进行验证 可以配置 API 管理验证策略,以根据 OpenAPI 规范中的架构验证请求和响应(或其元素)。 例如,使用 validate-content 策略来验证请求或响应正文的大小或内容。 创建和发布产品 转换和保护已发布的 API
导入 API 后,如果需要,可以使用 az apim api update 命令更新设置。
以下示例使用 Import-AzApiManagementApi Azure PowerShell cmdlet 将 OpenAPI 规范从指定的 URL 导入到名为 apim-hello-world 的 API 管理实例。 若要使用规范的路径而不是 URL 进行导入,请使用 -SpecificationPath 参数。
-SpecificationPath
# API Management service-specific details $apimServiceName = "apim-hello-world" $resourceGroupName = "myResourceGroup" # API-specific details $apiId = "demo-conference-api" $apiPath = "conference" $specificationFormat = "OpenAPI" $specificationUrl = "https://conferenceapi.azurewebsites.net/?format=json" # Get context of the API Management instance. $context = New-AzApiManagementContext -ResourceGroupName $resourceGroupName -ServiceName $apimServiceName # Import API Import-AzApiManagementApi -Context $context -ApiId $apiId -SpecificationFormat $specificationFormat -SpecificationUrl $specificationUrl -Path $apiPath 导入 API 后,如果需要,可以使用 Set-AzApiManagementApi cmdlet 更新设置。 在门户中测试新的 API 可直接从管理门户调用操作,这为管理员查看和测试 API 的操作提供了一种方便的方式。 选择上一步中创建的 API。 选择“测试”选项卡。 选择操作。 该页将显示查询参数的字段和标头的字段。 在测试控制台中,API 管理自动填充 Ocp-Apim-Subscription-Key 标头,并配置内置全访问订阅的订阅密钥。 此密钥允许访问 API 管理实例中的每个 API。 可选择性地通过选择 HTTP 请求旁的“眼睛”图标来显示 Ocp-Apim-Subscription-Key 标头。 根据操作,输入查询参数值、标头值或请求正文。 选择“发送”。 当测试成功时,后端会使用成功的 HTTP 响应代码和某些数据进行响应。 默认情况下,测试控制台会将请求发送到 API 管理的 CORS 代理,该代理将请求转发到 API 管理实例,后者又将请求转发到后端。 此代理使用公共 IP 地址 13.91.254.72,并且只能访问公共终结点。 如果要将请求直接从浏览器发送到API 管理服务,请选择“绕过 CORS 代理”。 如果要使用测试控制台,并且 API 管理网关与网络隔离或不允许来自 CORS 代理的流量,请使用此选项。 若要调试 API,请参阅教程:使用请求跟踪调试 API。 追加其他 API 可以为不同服务公开的 API 撰写 API,包括: OpenAPI 规范 SOAP API GraphQL API Azure 应用服务中托管的 Web 应用 Azure 函数应用 Azure 逻辑应用 Azure Service Fabric 按照以下步骤将其他 API 追加到现有 API。 导入另一个 API 时,操作将追加到当前 API 后面。 在 Azure 门户中转到自己的 Azure API 管理实例。 在概述页面上或左侧的菜单上选择“API” 。 单击要将另一个 API 追加到的 API 旁边的“...”。 从下拉菜单中选择“导入”。 选择要从中导入 API 的服务。 根据 OpenAPI 规范进行验证 可以配置 API 管理验证策略,以根据 OpenAPI 规范中的架构验证请求和响应(或其元素)。 例如,使用 validate-content 策略来验证请求或响应正文的大小或内容。 创建和发布产品 转换和保护已发布的 API
导入 API 后,如果需要,可以使用 Set-AzApiManagementApi cmdlet 更新设置。
可直接从管理门户调用操作,这为管理员查看和测试 API 的操作提供了一种方便的方式。
选择上一步中创建的 API。
选择“测试”选项卡。
选择操作。 该页将显示查询参数的字段和标头的字段。
在测试控制台中,API 管理自动填充 Ocp-Apim-Subscription-Key 标头,并配置内置全访问订阅的订阅密钥。 此密钥允许访问 API 管理实例中的每个 API。 可选择性地通过选择 HTTP 请求旁的“眼睛”图标来显示 Ocp-Apim-Subscription-Key 标头。
根据操作,输入查询参数值、标头值或请求正文。 选择“发送”。
当测试成功时,后端会使用成功的 HTTP 响应代码和某些数据进行响应。
默认情况下,测试控制台会将请求发送到 API 管理的 CORS 代理,该代理将请求转发到 API 管理实例,后者又将请求转发到后端。 此代理使用公共 IP 地址 13.91.254.72,并且只能访问公共终结点。 如果要将请求直接从浏览器发送到API 管理服务,请选择“绕过 CORS 代理”。 如果要使用测试控制台,并且 API 管理网关与网络隔离或不允许来自 CORS 代理的流量,请使用此选项。
若要调试 API,请参阅教程:使用请求跟踪调试 API。
可以为不同服务公开的 API 撰写 API,包括:
按照以下步骤将其他 API 追加到现有 API。
导入另一个 API 时,操作将追加到当前 API 后面。
在 Azure 门户中转到自己的 Azure API 管理实例。
在概述页面上或左侧的菜单上选择“API” 。
单击要将另一个 API 追加到的 API 旁边的“...”。
从下拉菜单中选择“导入”。
选择要从中导入 API 的服务。
可以配置 API 管理验证策略,以根据 OpenAPI 规范中的架构验证请求和响应(或其元素)。 例如,使用 validate-content 策略来验证请求或响应正文的大小或内容。