PAYATHON 2026

如何通过 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。

备注:内容仅供参考。