Cloud for Sustainability API (預覽版) 概觀

發行項
08/20/2024

重要

這其中部分或所有的功能會做為預覽版本的一部分來提供。內容和功能隨時可能變更。

Microsoft Cloud for Sustainability 提供 API 以存取與您使用 Azure 和 Microsoft 365 情況相關的排放資料。

準確的碳會計需要合作夥伴、廠商和供應商提供的正確資訊。 Cloud for Sustainability API 為您提供因使用 Azure 和 Microsoft 365 所產生碳排放的透明度。 Microsoft 的碳會計透過經第三方驗證的方法延伸至所有三個範圍的排放。這會使用一致且準確的碳會計來量化 Azure 和 Microsoft 365 對客戶環境足跡的影響。

此 API 的詳細資料已列於 Microsoft Cloud for Sustainability 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 Government 帳戶。若要檢查您的帳戶類型，請移至檢查帳戶的類型。

注意

目前並未在排放中擷取或反映Azure Hybrid Benefit 使用情況。
Microsoft 365 ：Microsoft 365 的 Microsoft Cloud for Sustainability API 支援 Microsoft 365 或 Office 365 的商務、企業或教育版訂閱。不支援國家/地區雲端部署，包括但不限於由 21Vianet 營運之 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 管理員、SharePoint 管理員、全域讀者、報表讀者。 Azure 和 Microsoft 365 系統管理員可能會建立執行個體，或將其本身新增至執行個體，以啟用資料來源並啟用 API。如果您沒有啟用的必要管理員角色，則只能使用示範資料來探索 API。

在資料來源索引標籤上，將連接切換為開啟，以連接 Azure 或 Microsoft 365 排放資料。請確定狀態在使用 API 之前已列示為可用。此動作會啟用所有與您有權存取之註冊或計費帳戶相關的排放資料。如果您無法存取任何排放資料，請僅使用範例資料繼續進行。

注意

啟用資料來源之後，Microsoft 365 排放資料最多可能需要 48 小時才能使用。停用 Microsoft 365 資料來源會永久刪除歷史 Microsoft 365 排放資料。
選取 API 管理索引標籤，然後選取啟用。

啟用 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：您的註冊識別碼，也稱為計費帳戶識別碼。僅限 Azure。如果您無法存取註冊，則可在此欄位中輸入 demodata，以使用示範資料來探索 API。
- instanceId：可在 Microsoft Cloud for Sustainability API 入口網站的 URL 中找到
- tenantId：Microsoft 365 租用戶識別碼。
新增所有必要的查詢參數。滾動到側窗格底端後選取傳送。窗格底端會顯示 HTTP 回應。

觀看此影片，深入了解與 OData 搭配的 Cloud for Sustainability API：

試用匯出 API

在左側導覽上，確定已啟用依標籤組成群組，並選取匯出群組，開始將排放和使用方式資料匯出至您的資料湖。選取 RunExportJob。
選取試用。輸入所有必要欄位，然後選取傳送。
- 授權：自動填入的授權權杖
- 訂閱金鑰：自動以 API 管理索引標籤中的 API 金鑰填入
- instanceId：可在 Microsoft Cloud for Sustainability API 入口網站的 URL 中找到
- exportJobType：選取 Azure 或 Microsoft 365 以指定要匯出之排放和使用方式資料的資料來源。
- demodata：如果您想要匯出示範資料來探索此功能，請輸入 "true"。
選取傳送之後，向下捲動以查看 HTTP 回應。如果您匯出的是 Azure 資料，則回應會列出所匯出資料的註冊識別碼。如果您無法存取 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 儲存體總管。選取開啟 Connect 對話方塊按鈕，然後選取 ADLS Gen2 容器或目錄。選取共用存取簽章 URL (SAS)，然後將 SAS URL 從步驟 4 貼入至 Blob 容器或目錄 SAS URL 輸入。選取下一步，然後選取連線。您必須在新的或現有的儲存體帳戶中找到或建立容器，以用於儲存此匯出資料。從暫存 Blob 儲存體中複製 Azure 或 Microsoft 365 資料，並在您選擇的容器中貼上該資料。
2. 使用 azcopy。使用步驟 4 中的 SAS URL 以及您要儲存已匯出排放的儲存體帳戶 URL (目的地 URL)，執行 azcopy 命令：
  - 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 管理員、 SharePoint 管理員、全域讀者或報表讀者。

若要將使用者、群組或應用程式新增為管理員：

選取權限索引標籤，然後選取新增使用者。
使用搜尋欄位，尋找需要新增權限的 Microsoft Entra ID 使用者、應用程式或群組。
選取角色指派，然後選取儲存。

管理執行個體

瀏覽至執行個體圖示，以尋找所有執行個體清單、建立執行個體，或移除執行個體。

檢視 API 使用情況

檢視有關即時 API 使用方式的詳細資料。

瀏覽至 API 管理索引標籤，然後選取使用方式。
選取時間範圍進行查看。

API 使用情況的頁面中包含三個區段：

API 呼叫：在選取的時間範圍中，會視覺化 API 彙總數量的圖表。
資料傳輸：圖表上顯示選取的時間範圍中，透過 API 傳送的資料總量。
作業：表格上的列是每個可用的 API 作業，以及有關作業使用方式的詳細資料。

常見問題

Microsoft 如何計算 API 所提供的雲端碳排放？

如需 Microsoft 計算方法的詳細資訊，請移至 Microsoft Cloud for Sustainability API 計算方法。

哪裡可以了解更多有關使用 OData 撰寫查詢的資訊？

若要了解有關 OData 的詳細資訊，請移至查詢選項概觀。

用於製作此報表的資料存放在哪裡？

資料存放在美國。

為什麼看不到上個月的排放資料？

指定月份的排放資料會在該月結束後的第 14 天 (包括非工作日) 前提供。

我無法建立執行個體。為什麼？

你可能正在嘗試使用與上線表單所提供不同之主機租用戶識別碼相關聯的帳戶來存取 Cloud for Sustainability API 入口網站。當您使用來賓帳戶時，可能會發生這種情況。不支援來賓帳戶。如果您希望我們將其他租用戶上線，請重新提交上線表單。

我的 Microsoft 365 和 Azure 有不同的租用戶識別碼。仍然可以使用 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 的 ApplicationId (c3163bf1-092f-436b-b260-7ade5973e5b9)，您已將其用於在自己的租用戶中建立 Microsoft Cloud for Sustainability API 應用程式註冊的執行個體 (企業應用程式)。

完成此動作後，即可前往應用註冊頁面，並選取 API 權限刀鋒視窗。若要新增權限，讓應用程式註冊可以呼叫 Microsoft Cloud for Sustainability API，請選取 + 新增權限，然後選取我的組織使用的 API 選項。接著搜尋 Microsoft Cloud for Sustainability API 的 ApplicationId (c3163bf1-092f-436b-b260-7ade5973e5b9)、選取 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 對於使用 Microsoft Cloud for Sustainability API (預覽版)，概不承擔任何責任。在任何情況下，Microsoft 均不對其他直接或間接損害負責，包括任何利潤損失、儲蓄損失，或因任何缺陷、使用或無法使用 Microsoft Cloud for Sustainability API (預覽版) 而引起的任何附帶或間接損害，即使 Microsoft 已被告知此類損害的可能性。

Microsoft Cloud for Sustainability API OData 查詢範例
 Microsoft Cloud for Sustainability API 計算方法
 Microsoft Cloud for Sustainability API

📄 產品頁面
 🎓 訓練

✅ 免費試用
 🎥 YouTube 頻道

💻 社群
 LinkedIn 群組

共用方式為

Cloud for Sustainability API (預覽版) 概觀