Cloud for Sustainability API（预览）OData 查询示例
Microsoft Cloud for Sustainability
重要提示
此功能的部分或全部属于预览版内容。 相关内容和功能可能会发生更改。
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 租户 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}/emissions?$select=enrollmentId,totalEmissions,scopeId |
| 包含计数 | {serviceRootAzure}/emissions?$count=true |
| 限制结果计数 | {serviceRootAzure}/emissions?$top=100 |
| 分页 | {serviceRootAzure}/emissions?$skip=100&$top=50 |
| 按范围筛选 | {serviceRootAzure}/emissions?$filter=ScopeId eq 1 |
| 筛选并聚合 | {serviceRootAzure}/emissions?$apply=filter(ScopeId eq 1)/aggregate($count as Count, totalEmissions with average as Average, totalEmissions with sum as Sum) |
| 筛选并分组 | {serviceRootAzure}/emissions?$apply=filter(totalEmissions gt 0.05)/groupby((ScopeId), aggregate($count as Count))` |
Microsoft365Emission 实体（对于 M365 排放）
表示与以下应用程序关联的 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 实体的示例查询（对于 M365 排放）
| 查询类型 | 示例 |
|---|---|
| 租户排放 | {serviceRootM365}/tenantemissions |
| 选择某些字段 | {serviceRootM365}/emissions?$select=tenantId,totalEmissions,scope |
| 包含计数 | {serviceRootM365}/tenantemissions?$count=true |
| 限制结果计数 | {serviceRootM365}/tenantemissions?$top=100 |
| 分页 | {serviceRootM365}/tenantemissions?$skip=100&$top=50 |
| 按范围筛选 | {serviceRootM365}/tenantemissions?$filter=Scope eq 'FILLMEIN' |
| 筛选并聚合 | {serviceRootserviceRootM365Azure}/tenantemissions?$apply=filter(scope eq 'FILLMEIN')/aggregate($count as Count, totalEmissions with average as Average, totalEmissions with sum as Sum) |
| 筛选并分组 | {serviceRootM365}/tenantemissions?$apply=filter(totalEmissions gt 0.05)/groupby((Scope), 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}/usage | |
| 每个订阅每月的总使用量 | {serviceRootAzure}/usage?$apply=groupby((SubscriptionName,DateKey),aggregate(usage with sum as 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}/projections |
重要提示
该 Microsoft Cloud for Sustainability API 当前处于预览版阶段，并且可能会更改。 随着 Microsoft 对数据准确性和完整性的改进，您的历史排放数据也可能会更新。
常见问题
Microsoft 如何计算排放量和使用量？
有关 Microsoft 计算方法的信息，请转到 Microsoft Cloud for Sustainability API 计算方法。
什么是行号？
API 使用行号实现一致的分页。 该值可能会发生变化，因此您的应用程序不应依赖于它。
什么是注册 ID？
注册 ID 是指计费帐户 ID。 在 Azure 门户中查找您的注册 ID 和计费帐户 ID。
如何为我的目标环境获取授权令牌？
该 API 需要 OAuth 授权令牌。 我们建议使用 Microsoft 身份验证库 (MSAL)。
你们能否提供更多关于如何使用 nextLink 进行分页的信息？
如果结果多于当前响应中返回的结果，API 将返回 @odata.nextLink 属性。 您的应用应在此 nextLink 上执行另一个 GET 来获取结果的下一页。 最后一页不会包含 nextLink。
探索此代码示例，了解有关使用 OData 客户端库分页的更多详细信息。
