視需要取得小型成本資料集

  • 發行項

使用成本詳細資料 API 來取得對應至 Azure 帳單的原始未彙總成本資料。 當您的組織需要程式設計資料擷取解決方案時，API 會很有用。 如果您想要分析 2 GB (2 百萬個資料列) 或更少的較小成本資料集，請考慮使用該 API。 不過，您應該對持續進行的資料擷取工作負載，以及對較大型資料集的下載使用匯出。

如果您想要定期取得大量的匯出資料，請參閱使用匯出定期擷取大型成本資料集。

若要深入了解成本詳細資料 (先前稱為使用量詳細資料)，請參閱擷取成本詳細資料。

[成本詳細資料] 報表僅適用於有 Enterprise 合約或 Microsoft 客戶合約的客戶。 如果您是 MSDN、隨用隨付或 Visual Studio 客戶，請參閱取得隨用隨付訂用帳戶的成本詳細資料。

權限

若要使用成本詳細資料 API，您需要支援功能和範圍的唯讀權限。

注意

成本詳留資料 API 不支援 EA 或 MCA 客戶的管理群組。

如需詳細資訊，請參閱

成本詳細資料 API 最佳做法

使用成本詳細資料 API 時，Microsoft 建議下列最佳做法。

要求排程

如果您想要取得最新的成本資料，建議您每天最多查詢一次。 報表會每隔四小時重新整理一次。 如果更頻繁地呼叫，您會收到相同的資料。 下載歷程記錄發票的成本資料之後，除非您明確收到通知，否則費用不會變更。 建議您在可查詢存放區中快取成本資料，以在您這端避免重複呼叫相同的資料。

將要求區塊化

將您的呼叫區塊化為小型日期範圍，以取得您可以透過網路下載的可管理檔案。 例如，如果您有每月計算的大型 Azure 成本檔案，建議您依日或依週進行區塊化。 如果您有包含大量成本資料的範圍 (例如計費帳戶)，請考慮對子範圍進行多個呼叫，以便取得您可下載的可管理檔案。 如需成本管理範圍的詳細資訊，請參閱了解並使用範圍。 下載資料之後，請使用 Excel 搭配篩選與樞紐分析表進一步分析資料。

如果您的資料集每月超過 2 GB (或大約 200 萬個資料列)，請考慮使用匯出做為更可調整的解決方案。

延遲與速率限制

對 API 的隨選呼叫會受到速率限制。 產生成本詳細資料檔案所需的時間會與檔案中的資料量直接相互關聯。 若要了解檔案可供下載之前的預期時間量，您可以在 API 回應中使用 retry-after 標頭。

支援的資料集時間範圍

成本詳細資料 API 支援每個報表一個月的資料集時間範圍上限。 在目前日期之前，最多可以擷取 13 個月的歷程資料。 如果您想要植入 13 個月的歷程記錄資料集，我們建議在過去 13 個月內的一個月資料集中進行 13 次呼叫。。 若要擷取超過 13 個月的歷程記錄資料，請使用匯出 REST API。

成本詳細資料 API 要求範例

Microsoft 客戶會使用下列範例要求來解決常見情況。 要求傳回的資料會對應至計費系統收到成本的日期。 其中可能包含來自多張發票的成本。 其是非同步 API。 因此，您會發出初始呼叫來要求您的報表，並在回應標頭中接收輪詢連結。 您可以從該處輪詢提供的連結，直到報表可供使用為止。

使用 API 回應中的 retry-after 標頭，以指定下一個輪詢 API 的時機。 標頭會提供報表產生所需的估計最短時間。

若要深入了解 API 合約，請參閱成本詳細資料 API。

實際成本與分攤成本

若要控制您想要查看實際成本或分攤成本報告，請變更初始要求本文中計量欄位所使用的值。 可用的計量值為 ActualCost 或 AmortizedCost。

分攤成本會將您購買的保留容量細分成每日區塊，並將其分散到保留容量期間的整個時段。 例如，您不會看到 1 月 1 日購買了 365 美元，而是會看到 1 月 1 日到 12 月 31 日每天購買 1.00 美元。 除了基本分攤，這些成本也會透過使用已使用該保留容量的特定資源來重新配置並建立關聯。 例如，如果 1.00 美元的每日費用由兩部虛擬機器攤銷，則您會看到當天有兩筆 0.50 美元的費用。 如果當天並未使用部分保留容量，您會看到一筆與適用虛擬機器相關聯的 0.50 美元費用，以及一筆收費類型為 UnusedReservation 的 0.50 美元費用。 只有在檢視分攤成本時，才會看到未使用的保留容量成本。

因為成本的呈現方式會改變，請務必注意實際成本和分攤成本檢視所顯示的總額會不同。 一般來說，購買保留容量一段時間的每月成本，將在檢視分攤成本時減少。 預訂購買後幾個月的成本會增加。 分攤功能僅適用於購買的保留容量，目前並不適用 Azure Marketplace 的購買項目。

建立報表的初始要求

POST https://management.azure.com/{scope}/providers/Microsoft.CostManagement/generateCostDetailsReport?api-version=2022-05-01

要求本文:

以下是指定日期範圍的 ActualCost 資料集範例要求。

{
  "metric": "ActualCost",
  "timePeriod": {
    "start": "2020-03-01",
    "end": "2020-03-15"
  }
}

可用 {scope} 選項來組建適當的 URI，記載於識別範圍的資源識別碼。

以下是您可以在報告要求本文中提供的可用欄位。

  • metric - 要求的報表類型。 其可以是 ActualCost 或 AmortizedCost。 非必要。 如果未指定欄位，API 會預設為 ActualCost 報表。
  • timePeriod - 資料要求的日期範圍。 非必要。 此參數不能與 invoiceId 或 billingPeriod 參數一起使用。 如果未在要求本文中提供 timePeriod、invoiceId 或 billingPeriod 參數，API 會傳回當月的成本。
  • invoiceId - 資料所要求的發票。 此參數僅供 Microsoft 客戶合約客戶使用。 此外，其只能用於帳單設定檔或客戶範圍。 此參數不能與 billingPeriod 或 timePeriod 參數一起使用。 如果未在要求本文中提供 timePeriod、invoiceId 或 billingPeriod 參數，API 會傳回當月的成本。
  • billingPeriod - 您的資料所要求的計費週期。 此參數僅供 Enterprise 合約客戶使用。 使用 YearMonth 格式。 例如，202008。 此參數不能與 invoiceId 或 timePeriod 參數一起使用。 如果未在要求本文中提供 timePeriod、invoiceId 或 billingPeriod 參數，API 會傳回當月的成本。

API 回應：

Response Status: 202 – Accepted：表示已接受要求。 使用 Location 標頭來檢查狀態。

回應標頭：

名稱 類型 格式 描述
Location String 用來檢查非同步作業結果的 URL。
Retry-after 整數 Int32 產生報表的預期時間。 等候此持續時間，之後再次輪詢。

報表輪詢和下載

在您提出建立成本詳細資料報告的要求之後，使用 API 回應 location 標頭中提供的端點來輪詢報表。 以下是輪詢要求的範例。

報表輪詢要求：

GET https://management.azure.com/{scope}/providers/Microsoft.CostManagement/costDetailsOperationStatus/{operationId}?api-version=2022-05-01

Response Status 200 – Succeeded：表示要求成功。

{
  "id": "subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.CostManagement/operationResults/00000000-0000-0000-0000-000000000000",
  "name": "00000000-0000-0000-0000-000000000000",
  "status": "Completed",
  "manifest": {
    "manifestVersion": "2022-05-01",
    "dataFormat": "Csv",
    "blobCount": 1,
    "byteCount": 160769,
    "compressData": false,
    "requestContext": {
      "requestScope": "subscriptions/00000000-0000-0000-0000-000000000000",
      "requestBody": {
        "metric": "ActualCost",
        "timePeriod": {
          "start": "2020-03-01",
          "end": "2020-03-15"
        }
      }
    },
    "blobs": [
      {
        "blobLink": "{downloadLink}",
        "byteCount": 32741
      }
    ]
  },
  "validTill": "2022-05-10T08:08:46.1973252Z"
}

以下是 API 回應中金鑰欄位的摘要：

  • manifestVersion - 回應中使用的資訊清單合約版本。 目前，指定 API 版本的資訊清單版本會維持不變。
  • dataFormat - CSV 是 API 目前唯一支援的檔案格式。
  • blobCount - 代表報表資料集中存在的個別資料 Blob 數目。 務必注意，此 API 可能會在回應中提供多個檔案的分割資料集。 設計您的資料管線，以便據以處理分割的檔案。 分割讓您往後更快速地擷取更大的資料集。
  • byteCount - 所有分割區中報表資料集的總位元組計數。
  • compressData - 第一個版本的壓縮一律會設為 false。 不過，API 未來將支援壓縮。
  • requestContext - 針對報表要求的初始組態。
  • blob - 共同組成完整報表的 n 個 Blob 檔案清單。
    • blobLink - 個別 Blob 分割區的下載 URL。
    • byteCount - 個別 Blob 分割區的位元組計數。
  • validTill - 無法再存取報表的日期。

相關內容