Bedarfsgesteuertes Abrufen kleiner Kostendatasets

  • Artikel

Mithilfe der Kostendetails-API können Sie rohe, nicht aggregierte Kostendaten abrufen, die zu Ihrer Azure-Rechnung gehören. Die API ist nützlich, wenn Ihre Organisation eine Lösung für den programmgesteuerten Datenabruf benötigt. Erwägen Sie die Nutzung der API, wenn Sie kleinere Kostendatasets bis maximal 2 GB (2 Mio. Zeilen) analysieren möchten. Für laufende Workloads zur Datenerfassung und das Herunterladen größerer Datasets sollten Sie jedoch auf die Export-API zurückgreifen.

Wenn Sie in regelmäßigen Abständen große Mengen von exportierten Daten abrufen möchten, finden Sie weitere Informationen unter Regelmäßiges Abrufen großer Datasets mit Kostendaten mithilfe von Exporten.

Weitere Informationen zu den Daten in den Kostendetails (zuvor als Nutzungsdetails bezeichnet) finden Sie unter Erfassen von Daten mit Kostendetails.

Der Bericht Kostendetails ist nur für Kunden mit Enterprise Agreement oder Microsoft-Kundenvereinbarung verfügbar. Wenn Sie ein Kunde mit MSDN, nutzungsbasierter Zahlung oder Visual Studio sind, finden Sie Informationen unter Abrufen von Kostendetails für Abonnements mit nutzungsbasierter Zahlung.

Berechtigungen

Um die Kostendetails-API zu verwenden, benötigen Sie Berechtigungen vom Typ „Schreibgeschützt“ für unterstützte Features und Bereiche.

Hinweis

Die Kostendetails-API unterstützt keine Verwaltungsgruppen für EA- oder MCA-Kunden.

Weitere Informationen finden Sie unter

Bewährte Methoden für die Kostendetails-API

Microsoft empfiehlt für die Kostendetails-API das Befolgen der folgenden bewährten Methoden.

Anforderungszeitplan

Wenn Sie die neuesten Kostendaten abrufen möchten, wird empfohlen, die Abfrage höchstens einmal pro Tag auszuführen. Berichte werden alle vier Stunden aktualisiert. Bei häufigeren Aufrufen erhalten Sie identische Daten. Nachdem Sie Ihre Kostendaten für historische Rechnungen heruntergeladen haben, ändern sich die Gebühren nur, wenn Sie explizit darüber benachrichtigt werden. Es wird empfohlen, die Kostendaten in einem abfragbaren Speicher auf Ihrer Seite zwischenzuspeichern, um wiederholte Aufrufe identischer Daten zu verhindern.

Unterteilen Ihrer Anforderungen

Unterteilen Sie Ihre Aufrufe in kleine Datumsbereiche, um besser verwaltbare Dateien zum Herunterladen über das Netzwerk zu erhalten. Es wird beispielsweise eine Unterteilung nach Tag oder Woche empfohlen, wenn Sie über große monatsbezogene Azure-Kostendateien verfügen. Wenn Sie Bereiche mit einer großen Menge von Kostendaten haben (z. B. ein Abrechnungskonto), sollten Sie mehrere Aufrufe für untergeordnete Bereiche ausführen, um besser verwaltbare Dateien zum Herunterladen zu erhalten. Weitere Informationen zu Cost Management-Bereichen finden Sie unter Verstehen von und Arbeiten mit Bereichen. Nachdem Sie die Daten heruntergeladen haben, können Sie die Daten in Excel mit Filtern und PivotTables weiter analysieren.

Wenn Ihr Dataset monatlich mehr als 2 GB (oder ca. 2 Mio. Zeilen umfasst), sollten Sie die Export-API als skalierbarere Lösung erwägen.

Datenlatenz und Ratenbegrenzungen

Für bedarfsgesteuerte Aufrufe der API gelten Ratenbegrenzungen. Die zum Generieren Ihrer Kostendetails benötigte Zeit steht in direktem Zusammenhang mit der Menge der Daten in der Datei. Um zu erfahren, wie lange es voraussichtlich dauert, ehe Ihre Datei zum Herunterladen zur Verfügung steht, können Sie in der API-Antwort den Header retry-after verwenden.

Unterstützte Zeitbereiche für das Dataset

Die Kostendetails-API unterstützt einen maximalen Zeitraum für das Dataset von einem Monat pro Bericht. Verlaufsdaten können für bis zu 13 Monate ab dem aktuellen Datum rückwirkend abgerufen werden. Wenn Sie ein 13-monatiges historisches Dataset erstellen möchten, empfehlen wir, 13 Aufrufe für je Datasets für einen Monat für die letzten 13 Monate zu platzieren. Verwenden Sie die Export-REST-API, um Daten abzurufen, die älter als 13 Monate sind.

Beispielanforderungen für die Kostendetails-API

Die folgenden Beispielanforderungen werden von Microsoft-Kunden verwendet, um gängige Szenarien abzudecken. Die über die Anforderung zurückgegebenen Daten entsprechen dem Datum, an dem die Kosten vom Abrechnungssystem erfasst wurden. Die Daten können Kosten mehrerer Rechnungen umfassen. Dies ist eine asynchrone API. Sie führen also einen einleitenden Aufruf durch, um Ihren Bericht anzufordern, und erhalten im Antwortheader einen Abfragelink. Anschließend können Sie den angegebenen Link so lange abfragen, bis der Bericht für Sie verfügbar ist.

Verwenden Sie in der API-Antwort den Header retry-after, um festzulegen, wann die API als Nächstes abgefragt werden soll. Der Header gibt eine geschätzte Mindestzeit an, die das Generieren Ihres Berichts in Anspruch nehmen wird.

Weitere Informationen zum API-Vertrag finden Sie unter Kostendetails-API.

Vergleich von Ist- und amortisierten Kosten

Um zu bestimmen, ob Sie einen Bericht zu Ist- oder amortisierten Kosten einsehen möchten, ändern Sie den für das Metrikfeld verwendeten Wert im ursprünglichen Anforderungstext. Die verfügbaren Metrikwerte sind ActualCost oder AmortizedCost.

Bei den amortisierten Kosten werden Ihre Reservierungskäufe in tägliche Blöcke unterteilt und auf die Dauer der Reservierungslaufzeit aufgeteilt. Beispiel: Anstelle eines Einkaufs in Höhe von 365 USD am 1. Januar sehen Sie für jeden Tag vom 1. Januar bis zum 31. Dezember einen Einkauf in Höhe von 1,00 USD. Zusätzlich zur einfachen Amortisierung werden die Kosten auch neu zugeteilt und den spezifischen Ressourcen zugeordnet, die die Reservierung genutzt haben. Falls die Kosten von 1,00 USD beispielsweise auf zwei virtuelle Computer aufgeteilt waren, werden für den Tag zwei Gebühren von jeweils 0,50 USD angezeigt. Wenn ein Teil der Reservierung für den Tag nicht genutzt wird, wird eine Gebühr von 0,50 USD für den entsprechenden virtuellen Computer und eine weitere Gebühr von 0,50 USD mit dem Gebührentyp UnusedReservation angezeigt. Nicht verwendete Reservierungskosten können nur bei Ansicht amortisierter Kosten eingesehen werden.

Aufgrund der veränderten Anzeige von Kosten ist es wichtig zu beachten, dass für die Ansicht mit den Ist-Kosten und den amortisierten Kosten unterschiedliche Gesamtwerte angezeigt werden. Im Allgemeinen sinken die Gesamtkosten von Monate für einen Reservierungskauf im Laufe der Zeit, wenn Sie die amortisierten Kosten betrachten. Die Kosten der Monate nach einer Reservierungskauferhöhung. Amortisierung ist nur für Reservierungskäufe verfügbar und erfolgt derzeit nicht für Käufe in Azure Marketplace.

Anfängliche Anforderung zum Erstellen eines Berichts

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

Anforderungstext:

Hier finden Sie eine Beispielanforderung für ein ActualCost-Dataset für einen bestimmten Datumsbereich.

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

Verfügbare {scope}-Optionen zum Erstellen des richtigen URI sind unter Identifizieren der Ressourcen-ID für einen Bereich beschrieben.

Hier sind die verfügbaren Felder, die Sie im Anforderungstext für den Bericht angeben können.

  • metric: der Typ des angeforderten Berichts. Kann entweder ActualCost oder AmortizedCost sein. Nicht erforderlich. Wenn das Feld nicht angegeben wird, erstellt die API standardmäßig einen ActualCost-Bericht.
  • timePeriod: der angeforderte Datumsbereich für Ihre Daten. Nicht erforderlich. Dieser Parameter kann nicht zusammen mit den Parametern invoiceId oder billingPeriod angegeben werden. Wenn der Parameter timePeriod, invoiceId oder billingPeriod nicht im Anforderungstext angegeben wird, gibt die API die Kosten des laufenden Monats zurück.
  • invoiceId: die angeforderte Rechnung für Ihre Daten. Dieser Parameter wird nur von Kunden mit Microsoft-Kundenvereinbarung verwendet. Darüber hinaus kann er nur im Bereich „Abrechnungsprofil“ oder „Kunde“ verwendet werden. Dieser Parameter kann nicht zusammen mit den Parametern billingPeriod oder timePeriod angegeben werden. Wenn der Parameter timePeriod, invoiceId oder billingPeriod nicht im Anforderungstext angegeben wird, gibt die API die Kosten des laufenden Monats zurück.
  • billingPeriod: der angeforderte Abrechnungszeitraum für Ihre Daten. Dieser Parameter wird nur von Enterprise Agreement-Kunden verwendet. Verwenden Sie das JahrMonat-Format. Beispiel: 202008. Dieser Parameter kann nicht zusammen mit den Parametern invoiceId oder timePeriod angegeben werden. Wenn der Parameter timePeriod, invoiceId oder billingPeriod nicht im Anforderungstext angegeben wird, gibt die API die Kosten des laufenden Monats zurück.

API-Antwort:

Response Status: 202 – Accepted : Gibt an, dass die Anforderung akzeptiert wurde. Verwenden Sie den Header Location, um den Status zu überprüfen.

Antwortheader:

Name Typ Format BESCHREIBUNG
Standort String Die URL zum Überprüfen des asynchronen Vorgangs.
Retry-After Integer Int32 Die voraussichtliche Dauer zur Generierung Ihres Berichts. Warten Sie diese Zeitspanne ab, ehe Sie die Abfrage wiederholen.

Abfragen und Herunterladen von Berichten

Sobald Sie die Erstellung eines Berichts mit Kostendetails angefordert haben, rufen Sie den Bericht über den im Header location der API-Antwort angegebenen Endpunkt ab. Hier ist ein Beispiel für eine Abfrageanforderung.

Abfrageanforderung für Bericht:

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

Response Status 200 – Succeeded: gibt an, dass die Anforderung erfolgreich war.

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

Hier ist eine Zusammenfassung der wichtigsten Felder in der API-Antwort finden:

  • manifestVersion: die Version des Manifestvertrags in der Antwort. Derzeit bleibt die Manifestversion für eine bestimmte API-Version identisch.
  • dataFormat: CSV ist das einzige unterstützte Dateiformat, das derzeit von der API bereitgestellt wird.
  • blobCount: die Anzahl individueller Datenblobs im Berichtsdataset. Beachten Sie, dass diese API in der Antwort ein partitioniertes Dataset mit mehr als einer Datei bereitstellen kann. Entwerfen Sie Ihre Datenpipelines so, dass sie partitionierte Dateien entsprechend verarbeiten können. Dank Partitionierung können Sie größere Datasets in Zukunft schneller erfassen.
  • byteCount: Die gesamte Anzahl der Bytes des Berichtsdatasets in allen Partitionen.
  • compressData: Bei der ersten Veröffentlichung ist die Komprimierung stets auf FALSE festgelegt. In Zukunft wird die API jedoch die Komprimierung unterstützen.
  • requestContext: die für den Bericht angeforderte Anfangskonfiguration.
  • blobs: eine Liste von n Blobdateien, die zusammen den vollständigen Bericht bilden.
    • blobLink: die Download-URL einer einzelnen Blobpartition.
    • blobLink: die Anzahl der Bytes in einer einzelnen Blobpartition.
  • validTill: Das Datum, an dem der Bericht nicht mehr zugänglich ist.

Zugehöriger Inhalt