Exportieren von Emissionsdaten mithilfe der REST-API
Um Emissionsdaten mithilfe der REST-API zu exportieren, müssen Sie einen Dienstprinzipal für den Zugriff auf Ihre Emissionsdaten erstellen und autorisieren. Anschließend können Sie den Dienstprinzipal verwenden, um ein Autorisierungstoken abzurufen und dann Emissionsdaten mithilfe der REST-API zu exportieren.
Erstellen und Autorisieren eines Dienstprinzipals zum Exportieren von Emissionsdaten
Ein Dienstprinzipal ist eine Anwendung, deren Token zum Authentifizieren und Gewähren des Zugriffs auf bestimmte Azure-Ressourcen mithilfe der Microsoft Entra-ID (früher Azure Active Directory-) verwendet werden können. Ressourcen umfassen Benutzer-Apps, Dienste oder Automatisierungstools.
Erstellen einer Microsoft Entra-Anwendung und eines Dienstprinzipals, die auf Ressourcen zugreifen können.
Speichern Sie die Mandanten-ID, die neue Client-ID und den geheimen Clientschlüsselwert für Ihre App für die Verwendung in Tokenanforderungen.
Der App muss die rolle Carbon Optimization Reader für die Ressourcen zugewiesen werden, für die Sie Emissionsdaten exportieren möchten. Wenn Sie beabsichtigen, die App zum Exportieren von Emissionsdaten für viele Ressourcen zu verwenden, können Sie die Rolle auf Ressourcengruppen- oder Abonnementebene zuweisen. Weitere Informationen finden Sie unter Zuweisen von Azure-Rollen mithilfe des Azure-Portals.
Abrufen eines Autorisierungstokens
Senden Sie die folgende Anforderung an die Eingabeaufforderung oder mithilfe eines Clients wie Postman.
curl -X POST 'https://login.microsoftonline.com/<tennant ID>/oauth2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<your apps client ID>' \
--data-urlencode 'client_secret=<your apps client secret' \
--data-urlencode 'resource=https://management.azure.com'
Der Antworttext wird angezeigt:
{
"token_type": "Bearer",
"expires_in": "86399",
"ext_expires_in": "86399",
"expires_on": "1672826207",
"not_before": "1672739507",
"resource": "https://management.azure.com",
"access_token": "eyJ0eXAiOiJKV1Qi....gpHWoRzeDdVQd2OE3dNsLIvUIxQ"
}
Verwenden Sie das Zugriffstoken aus der Antwort für die Verwendung in den folgenden HTTP-Anforderungen.
Exportieren von Emissionsdaten mithilfe der REST-API
POST /providers/Microsoft.Carbon/carbonEmissionReports?api-version=2023-04-01-preview Host: management.azure.com Content-Type: application/json Authorization: Bearer <Tokenwert>
Beispielanforderung
POST /providers/Microsoft.Carbon/carbonEmissionReports?api-version=2023-04-01-preview
Host: management.azure.com
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKJ...gVBNrsvg
{
"reportType": "OverallSummaryReport",
"subscriptionList": [
"abcd1234-a1b2-d3c4-e3f5-976543210abc"
],
"carbonScopeList": [
"Scope1",
"Scope2",
"Scope3"
],
"dateRange": {
"start": "2023-12-01",
"end": "2023-12-01"
}
}
Curl-Beispiel:
curl --location 'https://management.azure.com/providers/Microsoft.Carbon/carbonEmissionReports?api-version=2023-04-01-preview' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJ0eXA...2-KgVBNrsvg' \
--data '{
"reportType": "OverallSummaryReport",
"subscriptionList": [
"abcd1234-a1b2-d3c4-e3f5-976543210abc"
],
"carbonScopeList": [
"Scope1",
"Scope2",
"Scope3"
],
"dateRange": {
"start": "2023-12-01",
"end": "2023-12-01"
}
}
'
Beispielausgabe
{
"value": [
{
"dataType": "OverallSummaryData",
"totalCarbonEmission": 7000.622265493289,
"totalCarbonEmission12MonthsAgo": 0,
"totalCarbonEmissionLastMonth": 7480.374908590786,
"changeRatioFor12Months": 0,
"changeRatioForLastMonth": -0.06413483935765417,
"changeValueMonthOverMonth": 0
}
]
}
Berichtstypen
| Berichtstyp |
Beschreibung |
Wann verwendet werden soll |
| OverallSummaryReport |
Gesamtemissionen für alle Abonnementbereiche und Datumsbereiche, die in der Eingabe angegeben sind. |
Berichtsdaten auf hoher Ebene erforderlich |
| MonthlySummaryReport |
Emissionen für alle Abonnements und Emissionsbereiche für jeden Monat, der im Datumsbereich angegeben ist. |
Monatliche Aufschlüsselung |
| TopItemsSummaryReport |
Emissionen der obersten X-Elemente, die über Abonnements, Emissionen, Umfang, Kategorie und angegebenen Datumsbereich aggregiert wurden, aufgeschlüsselt nach Kategorie. |
Daten für die wichtigsten Elemente nach Kategorie |
| TopItemsMonthlySummaryReport |
Emissionen der obersten X-Elemente, die über Abonnements, Emissionen, Bereiche und Kategorie für jeden Monat aggregiert wurden, der im Datumsbereich angegeben ist. Die Emissionen werden nach Kategorie aufgeschlüsselt. Die wichtigsten X-Elemente basieren auf den Emissionen des letzten Monats. |
Daten für die wichtigsten Elemente nach Kategorie und Monat |
| ItemDetailsReport |
Für einen bestimmten Zeitraum aggregierte Emissionen und AbonnementsIDs für einen bestimmten Zeitraum und aufgeschlüsselt nach der angegebenen Kategorie. |
Emissionsdaten nach Kategorie |
Exportieren von Emissions-API-Parametern
In der folgenden Tabelle werden die Parameter beschrieben, mit denen Sie Emissionsdaten mithilfe der REST-API exportieren können.
| Parameter |
Art |
Beschreibung |
reportType |
Schnur |
Berichtstypname. Unterstützte Werte: OverallSummaryReport
MonthlySummaryReport
TopItemsSummaryReport TopItemsMonthlySummaryReport ItemDetailsReport |
subscriptionList |
[Zeichenfolge] |
Die SubscriptionId-Liste, nach der Sie abfragen möchten. Der Client sollte Zugriff auf diese Abonnements haben. |
resourceGroupUrlList |
[Zeichenfolge] |
Die resourceGroup-URL-Liste, für die Sie Daten abrufen möchten. Zum Beispiel: "resourceGroupUrlList": [ "/subscriptions/sub-id-1111/resourcegroups/rg_name" ] Der Zeichenfolgenwert im Array muss diesem Format entsprechen: "/subscriptions/{sub_id}/resourcegroups/{rg_name}" |
carbonScopeList |
[Zeichenfolge] |
Die Kohlenstoffbereichsliste. Unterstützte Werte: Scope1, Scope2 und Scope3. Diese Liste kann eine beliebige Kombination dieser drei Bereiche sein. |
dateRange |
Struktur |
Unterstützt einen Monat ab den letzten 12 Monaten. Der Anfangs- und Endmonat sollte gleich sein und sollte der erste Tag eines Monats sein. Eine Ausnahme wird ausgelöst, wenn diese Kriterien nicht erfüllt sind. Zum Beispiel dateRange": { "start": "2023-03-01", "end": "2023-03-01}
start und end Format: yyyy-mm-dd. Derzeit werden die Co2-Emissionsdaten monatlich aktualisiert. Der Wert der eigenschaften dateRangestart und end muss also der erste Tag jedes Monats sein. |
Anmerkung
dateRange unterstützt jeweils einen Monat (ab dem letzten 12. Monat). Eine Ausnahme wird ausgelöst, wenn Anfangs- und Enddaten unterschiedlich sind.
Berichtsspezifische Parameter
In der folgenden Tabelle sind zusätzliche Parameter aufgeführt, die für jeden Berichtstyp erforderlich sind.
| AdditionalParameter |
Art |
Beschreibung |
Berichte |
categoryType |
Schnur |
Fünf Kategorietypen werden unterstützt: Subscription
Location
ServiceType
ResourceGroup
Resource
|
TopItemsSummaryReportTopItemsMonthlySummaryReport
ItemDetailsReport
|
topItemsCount |
Ganze Zahl |
Die oberen x-Elemente, die angezeigt werden sollen (>5) |
TopItemsSummaryReportTopItemsMonthlySummaryReport
|
ItemDetailsReport |
category |
Schnur |
Der Kategoriename. Beispiel: "category": "ResourceGroup" |
pageSize |
Ganze Zahl |
Die Seitengröße für das Abfrageergebnis. Der Standardwert ist 1000. Der Maximalwert ist 2000. |
ItemDetailsReport |
orderBy |
Schnur |
Sehen Sie sich die nachstehende Tabelle an, um die unterstützten Werte zusammen mit den unterstützten Kategorietypen anzuzeigen. |
ItemDetailsReport |
sortDirection |
Schnur |
Supportwerte: Desc, Asc |
ItemDetailsReport |
groupCategory |
Schnur |
Dies kann als leere Zeichenfolge festgelegt werden. Gültige Werte: ResourceGroup und SubscriptionId |
ItemDetailsReport |
Reihenfolge nach Spalten
Die folgenden Ergebnisspalten unterstützen den orderBy-Parameter.
| Reihenfolge nach Spaltenname |
Kategorietyp |
Name |
alle außer Subscription |
TotalCarbonEmission |
alle |
TotalCarbonEmissionLastMonth |
alle |
ResourceGroup |
nur für Resource Kategorie |
SubscriptionId |
Subscription, Resource und ResourceGroup Kategorie |
ChangeRatioForLastMonth |
alle |
ChangeValueMonthOverMonth |
alle |
Weitere Informationen zu den REST-API-Berichten finden Sie unter Carbon Service - List Carbon Emission Reports.
