通过

Cloud for Sustainability API（预览）OData 查询示例

  • 项目

免费试用

重要提示

此功能的部分或全部属于预览版内容。 相关内容和功能可能会发生更改。

Open Data Protocol (OData) 是一种基于 HTTP 等核心协议构建的数据访问协议。 它使用普遍接受的方法，例如适用于 Web 的 REST。 您可以使用各种库和工具来使用 OData 服务。

为了帮助您基于 Microsoft Cloud for Sustainability API 构建您自己的实施，您可以查看一些经常请求的示例查询。

修改查询示例，使其在目标环境中能够正常工作：

  • {serviceRoot}: https://api.mcfs.microsoft.com/api/v1.0/instances/{instanceId}

  • {instanceId}：要查询的 Cloud for Sustainability 环境的 GUID，例如 20aec369-f1c8-4814-a89d-4d449dd7e8a1。

  • {serviceRootM365}: {serviceRoot}/m365

  • {serviceRootAzure}: {serviceRoot}/enrollments/{enrollmentId}

  • {enrollmentId}：注册 ID，也称为计费帐户 ID。 示例：12345678。

  • {tenantId}： Microsoft 365 tenant ID 的 ID 中。

备注

某些 API 查询将包含多个结果并拆分为多个页面。 API 每页最多返回 1000 个结果。 如果提供了更多结果，API 会返回包含指向下一页结果的 URL 的 @odata.nextLink 属性。

EnrollmentEmission 实体（对于 Azure 排放）

表示计费帐户的排放数据，也称为注册。

属性 类型​​ 注释
dateKey int32 yyyymmdd 格式的日期；dd 始终为 01。
enrollmentId 字符串 也称为计费帐户 ID。
orgName 字符串 与 TP 名称或顶级父级名称相同。
subscriptionId 字符串 订阅的 ID。
subscriptionName 字符串 订阅的名称。
azureServiceName 字符串 Azure 服务的名称，例如，应用服务
subService 字符串 例如，Azure 存储或 Azure 计算。
azureRegionName 字符串 部署服务的 Azure 区域。
范围 字符串 温室气体范围，例如，范围 1、范围 2 或范围 3。
scopeId int32 范围的 ID。
totalEmissions 双精度 记录的总排放量 (mtCO2e)。

EnrollmentEmission 实体的示例查询（对于 Azure 排放）

查询类型 示例
按注册列出的排放 {serviceRootAzure}/排放
选择某些字段 {serviceRootAzure}/排放？$选择=注册 Id，总排放，范围 Id
包含计数 {serviceRootAzure}/emissions？$count=true
限制结果计数 {serviceRootAzure}/排放量？$top=100
分页 {serviceRootAzure}/排放量？$skip=100&$top=50
按范围筛选 {serviceRootAzure}/emissions？$filter=ScopeId eq 1
筛选并聚合 {serviceRootAzure}/emissions？$apply=filter（ScopeId eq 1）/aggregate（$count 作为 Count，totalEmissions 作为平均值，totalEmissions 和 sum 作为 Sum）
筛选并分组 {serviceRootAzure}/emissions？$apply=filter（totalEmissions gt 0.05）/groupby（（ScopeId），aggregate（$count as Count））'

Microsoft365Emission 实体（对于 Microsoft 365 排放）

表示与以下应用程序关联的 Microsoft 365 数据中心排放量：

  • Exchange Online
  • SharePoint
  • OneDrive
  • Microsoft Teams
  • Word
  • Excel
  • PowerPoint
  • Outlook
属性 类型​​ 注释
dateKey int32 yyyymmdd 格式的日期；dd 始终为 01。
tenantId 字符串 租户的 ID。
tenantName 字符串 租户的名称。
officeRegionName 字符串 Microsoft 365 数据中心区域。
范围 字符串 温室气体范围，例如，范围 1、范围 2 或范围 3。
totalEmissions 双精度 记录的总排放量 (mtCO2e)。

Microsoft365Emission 实体的示例查询（对于 Microsoft 365 排放）

查询类型 示例
租户排放 {serviceRootM365}/tenant 排放
选择某些字段 {serviceRootM365}/排放？$选择=租户 Id，总排放，范围
包含计数 {serviceRootM365}/tenantemissions？$count=true
限制结果计数 {serviceRootM365}/tenantemissions？$top=100
分页 {serviceRootM365}/tenantemissions？$skip=100&$top=50
按范围筛选 {serviceRootM365}/tenantemissions？$filter=范围 eq 'FILLMEIN'
筛选并聚合 {serviceRootserviceRootM365Azure}/tenantemissions？$apply=filter（scope eq 'FILLMEIN'）/aggregate（$count 作为 Count，totalEmissions 和 average 作为 Average，totalEmissions 和 sum 作为 Sum）
筛选并分组 {serviceRootM365}/tenantemissions？$apply=filter（totalEmissions gt 0.05）/groupby（（范围），aggregate（$count as Count））'

EnrollmentUsage 实体（对于 Azure 排放）

表示 Microsoft Cloud 资源的计算使用系数。

属性 类型​​ 注释
dateKey int32 yyyymmdd 格式的日期；dd 始终为 01。
enrollmentId 字符串 也称为计费帐户 ID。
orgName 字符串 与 TP 名称或顶级父级名称相同。
subscriptionId 字符串 订阅的 ID。
subscriptionName 字符串 订阅的名称。
subService 字符串 例如，Azure 存储或 Azure 计算。
azureRegionName 字符串 部署服务的 Azure 区域。
使用量 双精度 记录的总使用量。 没有单位，因为它表示指定区域内服务的规范化使用情况。

有关 Microsoft 计算方法的更多信息，请转到 Microsoft Cloud for Sustainability API 计算方法。|

EnrollmentUsage 实体的示例查询

查询类型 示例 备注
所有使用情况数据 {serviceRootAzure}/用法
每个订阅每月的总使用量 {serviceRootAzure}/usage？$apply=groupby（（SubscriptionName，DateKey），aggregate（总和为 TotalUsage））&$orderby=SubscriptionName，DateKey

EnrollmentProjection 实体（对于 Azure 排放）

表示根据前五个月的滚动平均值计算的日历年剩余时间的预计排放量。 用于年度可视化。

属性 类型​​ 注释
dateKey int32 yyyymmdd 格式的日期；dd 始终为 01。
enrollmentId 字符串 也称为计费帐户 ID。
actualEmissions 双精度 仅包括过去日期的情况 (mtCO2e)。
projectedEmissions 双精度 基于前五个月或更短时间的滚动平均值，基于当前年度的实际数据 (mtCO2e)。
actualUsage 双精度 仅针对过去日期包括在内。
projectedUsage 双精度 基于前五个月或更短时间的滚动平均值，基于当前年度的实际数据。

EnrollmentProjection 实体的示例查询（对于 Azure 排放）

查询类型 示例 备注
2022 年 7 月后的预测 {serviceRootAzure}/projections？$filter=dateKey gt 20220701
年度的所有预测 {serviceRootAzure}/预测

重要提示

该 Microsoft Cloud for Sustainability API 当前处于预览版阶段，并且可能会更改。 随着 Microsoft 对数据准确性和完整性的改进，您的历史排放数据也可能会更新。

常见问题

Microsoft 如何计算排放量和使用量？

有关 Microsoft 计算方法的信息，请转到 Microsoft Cloud for Sustainability API 计算方法。

什么是行号？

API 使用行号实现一致的分页。 该值可能会发生变化，因此您的应用程序不应依赖于它。

什么是注册 ID？

注册 ID 是指计费帐户 ID。 在 Azure 门户中查找注册 ID 和计费帐户 ID 。

如何为我的目标环境获取授权令牌？

此 API 需要 OAuth 授权令牌。 我们建议使用 Microsoft 身份验证库 (MSAL)。

如果结果多于当前响应中返回的结果，API 将返回 @odata.nextLink 属性。 您的应用应在此 nextLink 上执行另一个 GET 来获取结果的下一页。 最后一页不包含 nextLink。 探索此代码示例，了解有关使用 OData 客户端库分页的更多详细信息。

📄 培训产品页面
🎓

✅ 免费试用
🎥 YouTube 频道

💻 社区
LinkedIn 图标。LinkedIn 组