如何通过 Office 365 API 获取订阅许可证数量?
结论
可以。对于 Microsoft 365(原 Office 365)租户,可以通过 Microsoft Graph 的 subscribedSkus 接口读取订阅 SKU 和许可证数量:
GET https://graph.microsoft.com/v1.0/subscribedSkus
返回结果中的主要字段与管理中心信息对应如下:
| 管理中心显示的信息 | Microsoft Graph 字段 |
|---|---|
| 订阅名称 | skuPartNumber |
| SKU 标识 | skuId |
| 可用/有效许可证总数 | prepaidUnits.enabled |
| 已分配许可证数 | consumedUnits |
| 警告状态许可证数 | prepaidUnits.warning |
| 已暂停许可证数 | prepaidUnits.suspended |
| 已锁定许可证数 | prepaidUnits.lockedOut |
| 订阅当前状态 | capabilityStatus |
Microsoft Graph 不一定会直接返回名为 expiredLicenses 的字段。管理中心里的“expired”属于展示层概念,API 通常使用 capabilityStatus 以及 warning、suspended、lockedOut 等字段表示许可证状态。
调用 Microsoft Graph
先获取具有相应权限的访问令牌,再发送请求:
curl --request GET \
--url "https://graph.microsoft.com/v1.0/subscribedSkus" \
--header "Authorization: Bearer ACCESS_TOKEN" \
--header "Accept: application/json"
典型的响应结构如下:
{
"value": [
{
"id": "tenant-id_sku-id",
"skuId": "00000000-0000-0000-0000-000000000000",
"skuPartNumber": "ENTERPRISEPACK",
"capabilityStatus": "Enabled",
"consumedUnits": 42,
"prepaidUnits": {
"enabled": 50,
"suspended": 0,
"warning": 0,
"lockedOut": 0
}
}
]
}
在这个示例中:
- 已启用许可证:
50 - 已分配许可证:
42 - 尚未分配的许可证:
50 - 42 = 8 - SKU 状态:
Enabled
剩余许可证的计算方式是:
remainingUnits = prepaidUnits.enabled - consumedUnits
这个结果可以用来展示“当前还可分配多少许可证”。如果订阅处于宽限、暂停或锁定状态,还需要结合 capabilityStatus 和 prepaidUnits 中的其他字段判断,不能只看这个差值。
使用 Microsoft Graph PowerShell
安装并登录 Microsoft Graph PowerShell 后,可以直接运行:
Connect-MgGraph -Scopes "LicenseAssignment.Read.All"
Get-MgSubscribedSku -All |
Select-Object SkuPartNumber,
CapabilityStatus,
ConsumedUnits,
@{Name = "EnabledUnits"; Expression = { $_.PrepaidUnits.Enabled }},
@{Name = "WarningUnits"; Expression = { $_.PrepaidUnits.Warning }},
@{Name = "SuspendedUnits"; Expression = { $_.PrepaidUnits.Suspended }},
@{Name = "LockedOutUnits"; Expression = { $_.PrepaidUnits.LockedOut }},
@{Name = "RemainingUnits"; Expression = {
$_.PrepaidUnits.Enabled - $_.ConsumedUnits
}}
输出结果会按 SKU 列出许可证容量、已使用数量和剩余数量。
权限要求
调用 subscribedSkus 需要 Microsoft Graph 的目录许可证读取权限,通常可以使用:
LicenseAssignment.Read.All
实际可用的最小权限还取决于访问方式和租户策略,包括委托访问或应用访问。使用应用程序权限时,需要管理员同意;使用委托权限时,当前登录用户也必须有权读取相关租户信息。
生产环境应只授予实际需要的权限。仅为读取许可证数量,没有必要默认申请范围更大的 Directory.Read.All。
“订阅名称”可能不是购买时的商品名称
skuPartNumber 返回的是 Microsoft 定义的 SKU 技术名称,例如:
ENTERPRISEPACK
STANDARDPACK
SPE_E3
POWER_BI_PRO
这些名称可能与管理中心显示的友好名称不同。如果页面需要显示“Microsoft 365 E3”之类的名称,可以根据 skuId 建立 SKU 名称映射。由于 Microsoft 可能增加新的产品 SKU,这份映射需要定期维护。
同一种产品也可能来自不同的购买渠道或订阅合同。subscribedSkus 主要提供租户级许可证容量,不保证完整复刻 Billing 页面中的订单、合同、续订日期或付款信息。
如果需要精确的到期或计费信息
subscribedSkus 可以用来确认:
- 租户包含哪些许可证 SKU;
- 每个 SKU 有多少已启用许可证;
- 已分配了多少;
- 还有多少可分配;
- SKU 当前处于启用、警告、暂停还是锁定状态。
如果需要合同到期日期、自动续订状态、购买订单、账单金额,或者按订阅合同拆分的数量,就不能只依赖这个接口。这些属于商业订阅和计费数据,能否通过 API 获取取决于订阅类型、购买渠道和调用方身份。管理中心里的 Billing 表格也不保证有一套字段完全对应的公开 API。
如果只需要获取 Office 365 许可证数量,优先使用 Microsoft Graph GET /subscribedSkus。开发新功能时,不要再依赖已经淘汰的 Azure AD Graph 或旧版 Office 365 Reporting API。
备注:内容仅供参考。