API 管理中的软删除功能

2025-10-30

适用于：所有 API 管理层级

利用 API 管理软删除，你可以恢复和还原最近删除的 API 管理实例。此功能可避免意外删除 API 管理实例。

目前，根据删除 API 管理实例的方式，该实例在保留期内是软删除和可恢复的，也可以永久删除：

使用 Azure 门户或 REST API 版本 2020-06-01-preview 及更高版本删除 API 管理实例时，系统会实施软删除。
使用 2020-06-01-preview 之前的 REST API 版本删除 API 管理实例时，系统会将其永久删除。
在 Azure PowerShell 或 Azure CLI 中使用 API 管理命令删除 API 管理实例时，系统会将其软删除。

支持接口

针对软删除实例的恢复和其他操作可通过以下方式实现：使用 REST API2020-06-01-preview 及更高版本，或面向 .NET、Go 或 Python 的 Azure SDK。

提示

有关调用 Azure REST API 的提示和工具的详细信息，请参阅 Azure REST API 参考，以及特定于 API 管理的信息，请参阅 API 管理 REST。

操作	说明	API 管理命名空间	最低 API 版本
创建或更新	创建或更新 API 管理服务。	API 管理服务	任意
属性设置为 true 的`restore`	恢复（取消删除）API 管理服务（如果之前实施的是软删除）。如果 `restore` 指定并设置为 `true`，则忽略所有其他属性。	API 管理服务	2020-06-01-预览版
删除	删除现有的 API 管理服务。	API 管理服务	2020-06-01-预览版
按名称获取	按名称获取软删除的 API 管理服务。	已删除的服务	2020-06-01-预览版
按订阅列出	列出对于给定的订阅可以取消删除的所有已软删除的服务。	已删除的服务	2020-06-01-预览版
清除	清除 API 管理服务（将其永久删除，没有取消删除的选项）。	已删除的服务	2020-06-01-预览版

软删除行为

可以使用任何 API 版本来创建 API 管理实例。使用 Azure 门户、Azure REST API 或其他使用 API 版本 2020-06-01-preview 或更高版本的 Azure 工具删除 API 管理实例时，会自动软删除该实例。

软删除 API 管理实例后，服务将处于已删除状态，因此无法正常执行 API 管理作。

在软删除状态下：

只能列出、恢复或清除（永久删除）API 管理实例。
在经过预先确定的保留期（48 小时）后，Azure 将指派系统永久删除 API 管理实例所对应的底层数据。
不能重复使用 API 管理实例的名称。

如果在 48 小时内未恢复或清除 API 管理实例，该实例将自动永久删除。

列出已删除的 API 管理实例

可以使用“已删除的服务按名称获取”操作或使用“按订阅列出”操作来验证软删除的 API 管理实例是否可用于还原（取消删除）。

按名称获取已软删除的实例

使用 API 管理按名称获取操作，将 {subscriptionId}、{location} 和 {serviceName} 替换为你的 Azure 订阅、资源位置名称和 API 管理实例名称：

GET https://management.chinacloudapi.cn/subscriptions/{subscriptionId}/providers/Microsoft.ApiManagement/locations/{location}/deletedservices/{serviceName}?api-version=2021-08-01

如果可用于取消删除，Azure 将返回其 API 管理实例的记录，显示其 deletionDate 和 scheduledPurgeDate，例如：

{
    "id": "subscriptions/########-####-####-####-############/providers/Microsoft.ApiManagement/locations/chinanorth/deletedservices/apimtest",
    "name": "apimtest",
    "type": "Microsoft.ApiManagement/deletedservices",
    "location": "China North",
    "properties": {
        "serviceId": "/subscriptions/########-####-####-####-############/resourceGroups/apimtestgroup/providers/Microsoft.ApiManagement/service/apimtest",
        "scheduledPurgeDate": "2021-11-26T19:40:26.3596893Z",
        "deletionDate": "2021-11-24T19:40:50.1013572Z"
    }
}

列出某个给定订阅的所有软删除实例

使用 API 管理按订阅列出操作，将 {subscriptionId} 替换为你的订阅 ID：

GET https://management.chinacloudapi.cn/subscriptions/{subscriptionId}/providers/Microsoft.ApiManagement/deletedservices?api-version=2021-08-01

此命令返回一个列表，列出给定订阅下可用于取消删除的所有软删除服务，其中显示了每个服务的deletionDate和scheduledPurgeDate。

恢复软删除的实例

使用 API 管理创建或更新操作，将 {subscriptionId}、{resourceGroup} 和 {apimServiceName} 替换为你的 Azure 订阅、资源组名称和 API 管理名称：

PUT
https://management.chinacloudapi.cn/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/Microsoft.ApiManagement/service/{apimServiceName}?api-version=2021-08-01

。。。并在请求正文中将 restore 属性设置为 true。（指定此标志并设置为 true 时，将忽略所有其他属性。例如：

{
  "properties": {
    "publisherEmail": "help@contoso.com",
    "publisherName": "Contoso",
    "restore": true
  },
  "sku": {
    "name": "Developer",
    "capacity": 1
  },
  "location": "China North"
}

清除软删除的实例

使用 API 管理清除操作，将 {subscriptionId}、{location} 和 {serviceName} 替换为你的 Azure 订阅、资源位置和 API 管理名称。

注意

若要清除软删除的实例，除了对 API 管理实例的参与者访问权限外，还必须在订阅范围内拥有以下基于角色的访问控制（RBAC）权限：Microsoft.ApiManagement/locations/deletedservices/deletedservices/delete，Microsoft.ApiManagement/deletedservices/read。

DELETE https://management.chinacloudapi.cn/subscriptions/{subscriptionId}/providers/Microsoft.ApiManagement/locations/{location}/deletedservices/{serviceName}?api-version=2021-08-01

此命令从 Azure 永久删除 API 管理实例。

删除后重复使用 API 管理实例名称

可以在新部署中重复使用 API 管理实例的名称：

从 Azure 中被永久删除（彻底清除）实例后。
与原始实例位于同一订阅中。

不能在新部署中重复使用 API 管理实例的名称：

软删除实例后。
在与用于部署原始实例的订阅不同的其他订阅中，即使原始实例已从 Azure 中永久删除（清除）后，情况依然如此。无论使用的新订阅位于相同的还是不同的 Microsoft Entra 租户中，此限制都适用。此限制在删除后的几天或更长时间内有效，具体取决于订阅类型。

此限制是因为 Azure 在预留期内将服务主机名保留给客户的租户，以防止子域接管与悬空域名系统（DNS）条目的威胁。有关详细信息，请参阅阻止无关联的 DNS 项并避免子域接管。若要查看 Microsoft Entra 租户中订阅的所有无关联 DNS 项，请参阅识别无关联的 DNS 项。

了解长期 API 管理备份和恢复选项：

如何使用 Azure API 管理中的服务备份和还原实现灾难恢复

通过