Cloud for Sustainability API（预览）概述

项目
05/15/2024

Microsoft Cloud for Sustainability - 免费试用

重要提示

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

Microsoft Cloud for Sustainability 提供用于访问与 Azure 和 Microsoft 365 使用情况相关的排放数据的 API。

准确的碳核算需要来自合作伙伴、供应商和供应商的有用信息。 Cloud for Sustainability API 为您提供了使用 Azure 和 Microsoft 365 产生的碳排放的透明度。 Microsoft 的碳核算涵盖了所有三个排放范围，使用经过第三方验证的方法。它使用一致且准确的碳核算来量化 Azure 和 Microsoft 365 对客户环境足迹的影响。

Microsoft Cloud for Sustainability API 参考中列出了 API 的详细信息。其中包括有关操作、参数和响应的其他信息。

Cloud for Sustainability API 入门
示例查询
分配权限
管理实例
查看 API 使用情况
常见问题解答

重要提示

该 Microsoft Cloud for Sustainability API 当前处于预览版阶段，并且可能会更改。随着 Microsoft 对数据准确性和完整性的改进，您的历史排放数据也可能会更新。此预览不适用于遵守法律、市场营销或报告目的。

Cloud for Sustainability API 入门

备注

如果您的组织希望访问 Microsoft Cloud for Sustainability API（预览），请提交此注册表单。

通过以下过程开始使用 API：

查看支持的帐户
注册和创建实例
配置数据源并启用 API
试用 API

支持帐户

Azure：Azure 的 Microsoft Cloud for Sustainability API 支持与 Microsoft 有直接计费关系的 EA Direct、MCA 和 MPA 帐户。从云解决方案提供商 (CSP) 购买 Azure 的客户不受支持，必须直接与其 CSP 合作以了解其云排放。不支持旧帐户、基于信用的帐户、中国注册和 Azure 政府帐户。要检查帐户类型，请转到检查帐户的类型。

备注

Azure 混合权益使用情况当前不会被捕获或反映在排放中。
Microsoft 365：Microsoft 365 的 Microsoft Cloud for Sustainability API 支持 Microsoft 365 或 Office 365 的商业、企业或教育订阅。不支持国家/区域云部署，包括但不限于 Microsoft 的美国政府云和世纪互联运营的 Office 365。

从 Microsoft 获得对 Microsoft Cloud for Sustainability API 的访问权限后，使用您的 Azure Microsoft Entra ID 凭据登录。

您必须创建一个实例才能访问 Microsoft Cloud for Sustainability API。创建实例后，您将成为该实例的管理员。实例管理员可以向实例添加用户、组和应用程序。

观看此视频，概括了解如何使用 Cloud for Sustainability API 和门户：

配置数据源并启用 API

重要提示

要成功启用对组织数据的访问，此步骤必须由相关管理员执行。对于 Azure MCA 帐户，需要具有计费帐户读者、参与者或负责人角色的计费帐户管理员。对于 Azure EA 帐户，需要企业管理员或企业管理员 - 只读。检查您在 Azure 门户中的角色。对于 Microsoft 365，需要以下角色之一：全局管理员、Exchange 管理员、Skype For Business 管理员、SharePoint 管理员、全局读取者、报表读者。 Azure 和 Microsoft 365 管理员可以创建实例或添加到实例中，以启用数据源和 API。如果您没有启用数据所需的管理员角色，则只能使用演示数据来探索 API。

在数据源选项卡上，打开连接以连接 Azure 或 Microsoft 365 排放数据。在使用 API 之前，请确保状态列为可用。此操作启用与您有权访问的所有注册或计费帐户相关的排放数据。如果您无权访问任何排放数据，继续时请仅使用演示数据。

备注

启用数据源后，Microsoft 365 排放数据最长可能需要 48 小时可以使用。禁用 Microsoft 365 数据源将永久删除 Microsoft 365 历史排放数据。
选择 API 管理选项卡，然后选择启用。

启用 API 会生成主要和次要 API 密钥，供您的实例在 API 请求中使用。要重新生成密钥，请选择。要复制密钥，请选择。

对配置应用来调用 Cloud for Sustainability API 感兴趣？观看此演示：

试用 API

在 API 管理选项卡上，选择试用 API 来探索 OData 和导出 API。通过将低延迟 OData API 连接到仪表板，交互式查询排放数据。或者，通过使用导出 API 将排放数据直接传输到 Azure Data Lake Storage，进行您自己的批量处理。开发人员门户在一个新的选项卡中打开，您可以在其中探索请求和响应架构，并针对 Microsoft Cloud for Sustainability API 发起实时请求。

试用 OData API

在左侧导航中，确保启用了按标记分组，然后选择 OData 分组查看 Azure 和 Microsoft 365 OData API。
若要发出实时请求，请选择试用。输入所有必填字段：
- 授权：自动填充授权令牌
- 订阅密钥：使用 API 管理选项卡中的 API 密钥自动填充
- enrollmentId：您的注册 ID，也称为计费帐户 ID。仅 Azure。如果您没有注册权限，可以通过在此字段中输入 demodata 来使用演示数据探索 API。
- instanceId：位于 Microsoft Cloud for Sustainability API 门户的 URL 中
- tenantId：Microsoft 365 租户 ID。
添加所有必要的查询参数。滚动到侧窗格底部并选择发送。 HTTP 响应显示在窗格底部。

观看此视频，了解更多关于 Cloud for Sustainability API 与 OData 的信息：

尝试导出 API

在左侧导航中，确保启用按标记分组，然后选择导出分组，开始将排放和使用数据导出到数据湖。选择 RunExportJob。
选择试用。输入所有必填字段并选择发送。
- 授权：自动填充授权令牌
- 订阅密钥：使用 API 管理选项卡中的 API 密钥自动填充
- instanceId：位于 Microsoft Cloud for Sustainability API 门户的 URL 中
- exportJobType：选择 Azure 或 Microsoft 365 指定要导出的排放和使用情况数据的数据源。
- demodata：如果您想通过导出演示数据来探索此功能，输入“true”。
选择发送后，向下滚动查看 HTTP 响应。如果您在导出 Azure 数据，响应会列出导出数据的注册 ID。如果您没有访问 Azure 或 Microsoft 365 数据的权限，此操作不会成功。确保已经正确配置了数据源。

最初，响应指示作业 NotStarted。导出作业需要 2-3 分钟完成，您可以使用 jobID 使用 ExportJobStatus API 检查导出的状态。确保作业已成功，这表示导出的数据现在可以在暂存 blob 存储中使用。

您可以使用 LatestExportJob 查看有关上次导出作业的信息。

您可以使用 ExportJobs API 查看有关历史导出的信息。
使用 ExportLocation API 获取 SAS URL。 SAS URL 会在两个小时后过期。复制 SAS URL 访问暂存 blob 存储中的导出数据。
数据将设置为在运行导出作业后 28 天过期，必须在过期前进行复制。否则，数据将被从暂存位置删除。用户可以随时重新运行导出作业，以获得另一批具有 28 天过期时间的数据，包括最新的数据集。有几种方法可以访问导出的数据。
1. Azure 存储资源管理器
  
  安装和打开 Azure 存储资源管理器。选择打开连接对话按钮，然后选择 ADLS Gen2 容器或目录。选择共享访问签名 URL (SAS)，将步骤 4 中的 SAS URL 粘贴到 Blob 容器或目录 SAS URL 输入中。选择下一步，然后选择连接。您需要在新的或现有的存储帐户中查找或创建一个容器，以用于存储此导出的数据。将 Azure 或 Microsoft 365 数据从暂存 blob 存储复制并粘贴到您选择的容器中。
2. 使用 azcopy。使用步骤 4 中的 SAS URL 和存储导出排放的存储帐户的 URL（目标 URL），运行 azcopy.exe 命令：
  - azcopy login
  - azcopy list <SAS URL>
  - azcopy cp <SAS URL> <destination URL>
3. Spark 脚本
  
  在 Microsoft Fabric 或 Synapse 中使用 mssparkutils。您可以选择使用备用库和环境。
```
import subprocess
from notebookutils import mssparkutils

result = subprocess.run(['pip', 'install', 'azure-storage-blob'], capture_output=True)

# replace with SAS URI from API request
source_sas_url = 'https://<account_name>.blob.windows.net/<container_name>/<path>?<sas_token>'

start_index = source_sas_url.find('https://') + len('https://')
end_index = source_sas_url.find('.blob', start_index)
account_name = source_sas_url[start_index:end_index]
split = source_sas_url.split('?', 1)
domain_path = split[0]
sas_token = split[1]
container_name = domain_path.split('/')[3]

source_mount_point = '/src'
destination_mount_point = '/dest'

mssparkutils.fs.unmount(source_mount_point)
mssparkutils.fs.mount(
    f'abfss://{container_name}@{account_name}.blob.core.windows.net',
    source_mount_point,
    { 'sasToken': sas_token })

mssparkutils.fs.unmount(destination_mount_point)
mssparkutils.fs.mount( 
    'abfss://<destinationPath>', # replace with destination connection string
    destination_mount_point)

mssparkutils.fs.cp(src_path, dest_path, True)
```

示例查询

有关使用 API 的 OData 示例查询的简短列表，请转到OData 查询示例。

分配权限

对 Microsoft Cloud for Sustainability API 的访问仅限于组织中实例管理员添加到应用程序中的用户。用户可以是单个用户、组或应用程序。不支持来宾帐户。可以分配三种类型的角色：

观看者：可以查看 Microsoft Cloud for Sustainability API 内的所有页面。
参与者：可与 Microsoft Cloud for Sustainability API 门户内的所有页面交互。无法添加或删除用户。
管理员：所有可用权限，包括添加或移除用户的能力。

备注

参与者和管理员不能禁用或启用 Microsoft 365 数据源，除非他们是全局管理员、Exchange 管理员、Skype for Business 管理员、SharePoint 管理员、全局读取者或报表读者。

若要以管理员身份添加用户、组或应用，请执行以下操作：

选择权限选项卡，然后选择添加用户。
使用搜索字段查找要添加的 Microsoft Entra ID 用户、应用程序或组。
选择角色分配，然后选择保存。

管理实例

导航到实例图标，以查找所有实例的列表、创建实例或删除实例。

查看 API 使用情况

查看有关实时 API 使用情况的详细信息。

导航到 API 管理选项卡，然后选择使用情况。
选择要查看的时间范围。

API 使用情况页包含三个部分：

API 调用：一个显示选定期限内的 API 调用总数的图表。
数据传输：一个显示在选定期限内通过 API 传输的数据量的图表。
操作：一个表，其中包含每个可用 API 操作的行以及操作使用情况的详细信息。

常见问题

Microsoft 如何计算 API 提供的云碳排放？

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

我在哪里可以了解有关使用 OData 编写查询的更多信息？

若要了解有关 OData 的详细信息，请转到查询选项概述。

用于生成此报表的数据存储在哪里？

数据存储在美国。

为什么我看不到上个月的排放数据？

给定月份的排放数据将在该月结束后的第 14 天提供（包括非工作日）。

我无法创建实例。为什么？

您可能在尝试使用与加入窗体上提供的主机租户 ID 不同的主机租户 ID 关联的帐户访问 Cloud for Sustainability API 门户。当您使用来宾帐户时，可能会出现这种情况。不支持来宾帐户。如果您希望我们加入另一个租户，请重新提交加入窗体。

我有一个不同的 Microsoft 365 和 Azure 的租户 ID。我是否仍可以使用 Microsoft Cloud for Sustainability API？

您仍然可以访问 API，但门户不支持每个实例有多个租户。您需要将这些租户单独加入 API。

如何配置应用来调用 Microsoft Cloud for Sustainability API？

对配置应用来调用 Cloud for Sustainability API 感兴趣？观看此演示：

在 Azure 门户中，转到您的 Microsoft Entra ID，选择应用注册和 + 新注册。在新注册页面中，为您的应用注册提供一个名称，根据您的需要自定义选项，然后选择注册。转到 Microsoft Entra ID 页面，选择企业应用程序边栏，将应用程序类型设置为 Microsoft 应用程序，然后按应用程序名称 MCFS SDS 进行搜索。您在 New-AzADServicePrincipal 命令中传递的 ApplicationId 参数是您在自己的租户中创建 Microsoft Cloud for Sustainability API 应用注册实例（企业应用程序）时使用的 Microsoft Cloud for Sustainability API (c3163bf1-092f-436b-b260-7ade5973e5b9) 的 ApplicationId。

完成后，您现在可以转到应用注册页面，选择 API 权限边栏。要为应用注册添加权限以调用 Microsoft Cloud for Sustainability API，选择 + 添加权限，然后选择我的组织使用的 API 选项。然后，搜索 Microsoft Cloud for Sustainability API (c3163bf1-092f-436b-b260-7ade5973e5b9) 的 ApplicationId，选择 MCFS SDS，然后选择应用程序权限边栏的 App.Emissions.Read 权限。

此应用程序类型权限需要通过选择为 {your-tenant} 授予管理员同意来获得管理员同意。

最后，访问 Microsoft Cloud for Sustainability API 主页，导航到到权限边栏，然后选择 + 添加。在出现的侧面板中，选择查看器作为用户、组或应用程序输入中的角色，然后继续搜索应用程序注册。选择保存。

我在为我的应用程序获取访问令牌，资源 URL 是什么？

c3163bf1-092f-436b-b260-7ade5973e5b9/.default

有多少历史数据可用？

Azure：使用和排放数据包含过去五年与注册相关的数据。
Microsoft 365：排放数据包含过去 12 个月与 Microsoft 365 订阅相关的数据。

免责声明

Microsoft Cloud for Sustainability API（预览）基于服务器碳计算的行业标准，提供一般估算，以帮助组织深入了解与 Azure 云服务使用相关的 IT 基础设施的碳排放。 Microsoft Cloud for Sustainability API（预览）提供的调查结果、解释和结论（包括计算）不是具体的建议。所表达的信息和观点可能会发生变化，恕不另行通知。 Microsoft Cloud for Sustainability API（预览）按原样提供，无任何明示或暗示的陈述或保证，包括但不限于关于 Microsoft Cloud for Sustainability API（预览）的使用、结果或性能、其适当性、准确性、可靠性或正确性的任何陈述或背书。使用 Microsoft Cloud for Sustainability API（预览）的全部风险由您承担。 Microsoft 不承担使用 API（预览）Microsoft Cloud for Sustainability 的责任。在任何情况下，Microsoft 都不对额外的直接或间接损害承担责任，包括任何利润损失、储蓄损失，或任何缺陷引起的任何附带或间接损害，或使用或无法使用 Microsoft Cloud for Sustainability API（预览），即使 Microsoft 已被告知可能发生此类损害。

另请参见

Microsoft Cloud for Sustainability API OData 查询示例
 Microsoft Cloud for Sustainability API 计算方法
 Microsoft Cloud for Sustainability API

产品页面免费试用社区

Share via

Cloud for Sustainability API（预览）概述

Cloud for Sustainability API 入门