Экспорт данных о выбросах с помощью REST API
Чтобы экспортировать данные о выбросах с помощью REST API, необходимо создать и авторизовать субъект-службу для доступа к данным о выбросах. Затем можно использовать субъект-службу для получения маркера авторизации и экспорта данных о выбросах с помощью REST API.
Создание и авторизация субъекта-службы для экспорта данных о выбросах
Субъект-служба — это приложение, маркеры которого можно использовать для проверки подлинности и предоставления доступа к определенным ресурсам Azure с помощью идентификатора Microsoft Entra (ранее Azure Active Directory). Ресурсы включают пользовательские приложения, службы или средства автоматизации.
создание приложения Microsoft Entra и субъекта-службы, которые могут получить доступ к ресурсам.
Сохраните идентификатор клиента, новый идентификатор клиента и значение секрета клиента для приложения для использования в запросах маркеров.
Приложению необходимо назначить роль Carbon Optimization Reader для ресурсов, для которого требуется экспортировать данные о выбросах. Если вы планируете использовать приложение для экспорта данных о выбросах для многих ресурсов, можно назначить роль на уровне группы ресурсов или подписки. Дополнительные сведения см. в статье Назначение ролей Azure с помощью портала Azure.
Получение маркера авторизации
Отправьте следующий запрос в командной строке или с помощью клиента, например 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'
Появится текст ответа:
{
"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"
}
Используйте маркер доступа из ответа для использования в следующих HTTP-запросах.
Экспорт данных о выбросах с помощью REST API
POST /providers/Microsoft.Carbon/carbonEmissionReports?api-version=2023-04-01-preview Host: management.azure.com Content-Type: application/json Authorization: Bearer <значение токена>
Пример запроса
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:
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"
}
}
'
Пример выходных данных
{
"value": [
{
"dataType": "OverallSummaryData",
"totalCarbonEmission": 7000.622265493289,
"totalCarbonEmission12MonthsAgo": 0,
"totalCarbonEmissionLastMonth": 7480.374908590786,
"changeRatioFor12Months": 0,
"changeRatioForLastMonth": -0.06413483935765417,
"changeValueMonthOverMonth": 0
}
]
}
Типы отчетов
| Тип отчета |
Описание |
Когда следует использовать |
| Общие сведения об общем репрезестрируемомreport |
Общий объем выбросов для всех областей подписок и диапазона дат, указанных в входных данных. |
Необходимые данные отчета высокого уровня |
| MonthlySummaryReport |
Выбросы для всех подписок и областей выбросов за каждый месяц, указанный в диапазоне дат. |
Ежемесячная разбивка |
| TopItemsSummaryReport |
Выбросы основных элементов X, агрегированные по подпискам, выбросам, области, категории и указанному диапазону дат, разделенным по категориям. |
Данные для основных элементов по категориям |
| TopItemsMonthlySummaryReport |
Выбросы основных элементов X, агрегированных по подпискам, выбросам, областям и категориям за каждый месяц, указанный в диапазоне дат. Выбросы разбиваются по категориям. Основные элементы X основаны на выбросах в прошлом месяце. |
Данные для основных элементов по категориям и месяцам |
| ItemDetailsReport |
Выбросы, агрегированные по выбранным областям и идентификаторам подписок для заданного диапазона дат и разделенные по указанной категории. |
Данные о выбросах по категориям |
Экспорт параметров API выбросов
В следующей таблице описаны параметры, которые можно использовать для экспорта данных о выбросах с помощью REST API.
| Параметр |
Тип |
Описание |
reportType |
Струна |
Имя типа отчета. Поддерживаемые значения: OverallSummaryReport
MonthlySummaryReport
TopItemsSummaryReport TopItemsMonthlySummaryReport ItemDetailsReport |
subscriptionList |
[Строка] |
Список subscriptionId, для которого требуется запросить. Клиент должен иметь доступ к этим подпискам. |
resourceGroupUrlList |
[Строка] |
Список URL-адресов resourceGroup, для которого требуется получить данные. Например: ResourceGroupUrlList: [ "/subscriptions/sub-id-1111/resourcegroups/rg_name" ] Строковое значение в массиве должно соответствовать следующему формату: "/subscriptions/{sub_id}/resourcegroups/{rg_name}" |
carbonScopeList |
[Строка] |
Список областей углерода. Поддерживаемые значения: Scope1, Scope2 и Scope3. Этот список может быть любым сочетанием этих трех областей. |
dateRange |
Структура |
Поддерживает один месяц за последние 12 месяцев. Начальный и конечный месяц должен быть равным, и он должен быть первым днем месяца. Исключение возникает, если этот критерий не соответствует. Например dateRange": { "start": "2023-03-01", "end": "2023-03-01}
start и формат end: гггг-mm-dd. В настоящее время данные о выбросах углерода обновляются ежемесячно. Таким образом, значение свойств dateRangestart и end должно быть первым днем каждого месяца. |
Заметка
dateRange поддерживает один месяц за раз (с последних 12 месяцев). Исключение возникает, когда даты начала и окончания отличаются.
Параметры, относящиеся к отчету
В следующей таблице показаны дополнительные параметры, необходимые для каждого типа отчета.
| ДополнительныйParameter |
Тип |
Описание |
Отчеты |
categoryType |
Струна |
Поддерживаются пять типов категорий: Subscription
Location
ServiceType
ResourceGroup
Resource
|
TopItemsSummaryReportTopItemsMonthlySummaryReport
ItemDetailsReport
|
topItemsCount |
Целое число |
Основные элементы x для отображения (>5) |
TopItemsSummaryReportTopItemsMonthlySummaryReport
|
ItemDetailsReport |
category |
Струна |
Имя категории. Например, "category": "ResourceGroup" |
pageSize |
Целое число |
Размер страницы для результата запроса. Значение по умолчанию — 1000. Максимальное значение — 2000. |
ItemDetailsReport |
orderBy |
Струна |
См. таблицу ниже, чтобы просмотреть поддерживаемые значения, а также поддерживаемые типы категорий. |
ItemDetailsReport |
sortDirection |
Струна |
Значения поддержки: Desc, Asc |
ItemDetailsReport |
groupCategory |
Струна |
Это можно задать как пустую строку. Допустимые значения: ResourceGroup и SubscriptionId |
ItemDetailsReport |
Порядок по столбцам
Следующие столбцы результатов поддерживают параметр orderBy.
| Порядок по имени столбца |
Тип категории |
Name |
все, кроме Subscription |
TotalCarbonEmission |
все |
TotalCarbonEmissionLastMonth |
все |
ResourceGroup |
только для категории Resource |
SubscriptionId |
категория Subscription, Resource и ResourceGroup |
ChangeRatioForLastMonth |
все |
ChangeValueMonthOverMonth |
все |
Дополнительные сведения о отчетах REST API см. в разделе Углеродная служба — список отчетов о выбросах углерода.
