Eksportowanie danych emisji przy użyciu interfejsu API REST
Aby wyeksportować dane emisji przy użyciu interfejsu API REST, należy utworzyć i autoryzować jednostkę usługi w celu uzyskania dostępu do danych emisji. Następnie możesz użyć jednostki usługi, aby uzyskać token autoryzacji, a następnie wyeksportować dane emisji przy użyciu interfejsu API REST.
Tworzenie i autoryzowanie jednostki usługi w celu eksportowania danych emisji
Jednostka usługi to aplikacja, której tokeny mogą służyć do uwierzytelniania i udzielania dostępu do określonych zasobów platformy Azure przy użyciu identyfikatora Entra firmy Microsoft (wcześniej azure Active Directory). Zasoby obejmują aplikacje użytkownika, usługi lub narzędzia automatyzacji.
Tworzenie aplikacji i jednostki usługi firmy Microsoft, które mogą uzyskiwać dostęp do zasobów.
Zapisz identyfikator dzierżawy, nowy identyfikator klienta i wartość wpisu tajnego klienta dla aplikacji do użycia w żądaniach tokenów.
Aplikacja musi mieć przypisaną rolę Carbon Optimization Reader dla zasobów, dla których chcesz wyeksportować dane emisji. Jeśli planujesz używać aplikacji do eksportowania danych emisji dla wielu zasobów, możesz przypisać rolę na poziomie grupy zasobów lub subskrypcji. Aby uzyskać więcej informacji, zobacz Przypisywanie ról platformy Azure przy użyciu witryny Azure Portal.
Uzyskiwanie tokenu autoryzacji
Wyślij następujące żądanie w wierszu polecenia lub przy użyciu klienta, takiego jak 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'
Treść odpowiedzi zostanie wyświetlona:
{
"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"
}
Użyj tokenu dostępu z odpowiedzi do użycia w następujących żądaniach HTTP.
Eksportowanie danych emisji przy użyciu interfejsu API REST
POST /providers/Microsoft.Carbon/carbonEmissionReports?api-version=2023-04-01-preview Host: management.azure.com Content-Type: application/json Authorization: Bearer <wartość tokenu>
Przykładowe żądanie
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"
}
}
Przykład narzędzia curl:
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"
}
}
'
Przykładowe dane wyjściowe
{
"value": [
{
"dataType": "OverallSummaryData",
"totalCarbonEmission": 7000.622265493289,
"totalCarbonEmission12MonthsAgo": 0,
"totalCarbonEmissionLastMonth": 7480.374908590786,
"changeRatioFor12Months": 0,
"changeRatioForLastMonth": -0.06413483935765417,
"changeValueMonthOverMonth": 0
}
]
}
Typy raportów
| Typ raportu |
Opis |
Kiedy należy używać |
| OverallSummaryReport |
Łączna emisja dla wszystkich zakresów subskrypcji i zakresu dat określonych w danych wejściowych. |
Wymagane dane raportu wysokiego poziomu |
| MonthlySummaryReport |
Emisje dla wszystkich subskrypcji i zakresów emisji dla każdego miesiąca określonego w zakresie dat. |
Podział miesięczny |
| TopItemsSummaryReport |
Emisje najważniejszych elementów X zagregowanych między subskrypcjami, emisjami, zakresem, kategorią i określonym zakresem dat podzielonym na kategorie. |
Dane dla najważniejszych elementów według kategorii |
| TopItemsMonthlySummaryReport |
Emisje najważniejszych elementów X zagregowanych w ramach subskrypcji, emisji, zakresów i kategorii dla każdego miesiąca określonego w zakresie dat. Emisje są podzielone według kategorii. Pierwsze elementy X opierają się na emisjach z ubiegłego miesiąca. |
Dane dotyczące najważniejszych elementów według kategorii i miesiąca |
| ItemDetailsReport |
Emisje zagregowane w wybranych zakresach i identyfikatorach subskrypcji dla danego zakresu dat i podzielone według określonej kategorii. |
Dane emisji według kategorii |
Parametry interfejsu API eksportu emisji
W poniższej tabeli opisano parametry, których można użyć do eksportowania danych emisji przy użyciu interfejsu API REST.
| Parametr |
Typ |
Opis |
reportType |
Struna |
Nazwa typu raportu. Obsługiwane wartości: OverallSummaryReport
MonthlySummaryReport
TopItemsSummaryReport TopItemsMonthlySummaryReport ItemDetailsReport |
subscriptionList |
[Ciąg] |
Lista subscriptionId, dla której chcesz wykonać zapytanie. Klient powinien mieć dostęp do tych subskrypcji. |
resourceGroupUrlList |
[Ciąg] |
Lista adresów URL grupy zasobów, dla której chcesz pobrać dane. Na przykład: "resourceGroupUrlList": [ "/subscriptions/sub-id-1111/resourcegroups/rg_name" ] Wartość ciągu w tablicy musi mieć następujący format: "/subscriptions/{sub_id}/resourcegroups/{rg_name}" |
carbonScopeList |
[Ciąg] |
Lista zakresów emisji dwutlenku węgla. Obsługiwane wartości: Scope1, Scope2 i Scope3. Ta lista może być dowolną kombinacją tych trzech zakresów. |
dateRange |
Struct |
Obsługuje jeden miesiąc z ostatnich 12 miesięcy. Miesiąc początkowy i końcowy powinien być równy i powinien być pierwszym dniem miesiąca. Wyjątek jest zgłaszany, gdy te kryteria nie zostaną spełnione. Na przykład dateRange": { "start": "2023-03-01", "end": "2023-03-01} format start i end: yyyy-mm-dd. Obecnie dane dotyczące emisji dwutlenku węgla są odświeżane co miesiąc. Dlatego wartość właściwości dateRangestart i end musi być pierwszym dniem każdego miesiąca. |
Nuta
dateRange obsługuje jeden miesiąc w danym momencie (z ostatnich 12 miesięcy). Wyjątek jest zgłaszany, gdy daty rozpoczęcia i zakończenia są inne.
Parametry specyficzne dla raportu
W poniższej tabeli przedstawiono dodatkowe parametry wymagane dla każdego typu raportu.
| Dodatkowy parametr |
Typ |
Opis |
Raporty |
categoryType |
Struna |
Obsługiwane są pięć typów kategorii: Subscription
Location
ServiceType
ResourceGroup
Resource
|
TopItemsSummaryReportTopItemsMonthlySummaryReport
ItemDetailsReport
|
topItemsCount |
Liczba całkowita |
Najważniejsze elementy x do pokazania (>5) |
TopItemsSummaryReportTopItemsMonthlySummaryReport
|
ItemDetailsReport |
category |
Struna |
Nazwa kategorii. Na przykład "category": "ResourceGroup" |
pageSize |
Liczba całkowita |
Rozmiar strony dla wyniku zapytania. Wartość domyślna to 1000. Wartość maksymalna to 2000. |
ItemDetailsReport |
orderBy |
Struna |
Zapoznaj się z poniższą tabelą, aby wyświetlić obsługiwane wartości wraz z obsługiwanymi typami kategorii. |
ItemDetailsReport |
sortDirection |
Struna |
Wartości pomocy technicznej: Desc, Asc |
ItemDetailsReport |
groupCategory |
Struna |
Można to ustawić jako pusty ciąg. Prawidłowe wartości: ResourceGroup i SubscriptionId |
ItemDetailsReport |
Kolejność według kolumn
Poniższe kolumny wyników obsługują parametr orderBy.
| Kolejność według nazwy kolumny |
Typ kategorii |
Name |
wszystkie z wyjątkiem Subscription |
TotalCarbonEmission |
cały |
TotalCarbonEmissionLastMonth |
cały |
ResourceGroup |
tylko dla kategorii Resource |
SubscriptionId |
Subscription, Resource i kategoria ResourceGroup |
ChangeRatioForLastMonth |
cały |
ChangeValueMonthOverMonth |
cały |
Aby uzyskać więcej informacji na temat raportów interfejsu API REST, zobacz Carbon Service — Lista raportów emisji dwutlenku węgla.
