REST API를 사용하여 배출 데이터 내보내기
REST API를 사용하여 배출 데이터를 내보내려면 서비스 주체가 배출 데이터에 액세스할 수 있도록 만들고 권한을 부여해야 합니다. 그런 다음 서비스 주체를 사용하여 권한 부여 토큰을 가져오고 REST API를 사용하여 배출 데이터를 내보낼 수 있습니다.
배출 데이터를 내보낼 서비스 주체 만들기 및 권한 부여
서비스 주체는 Microsoft Entra ID(이전의 Azure Active Directory)를 사용하여 특정 Azure 리소스에 대한 액세스를 인증하고 부여하는 데 토큰을 사용할 수 있는 애플리케이션입니다. 리소스에는 사용자 앱, 서비스 또는 자동화 도구가 포함됩니다.
리소스에 액세스할 수 있는 Microsoft Entra 애플리케이션 및 서비스 주체 만듭니다.
토큰 요청에 사용할 앱의 테넌트 ID, 새 클라이언트 ID 및 클라이언트 비밀 값을 저장합니다.
앱에는 배출 데이터를 내보내려는 리소스에 대한 Carbon Optimization Reader 역할이 할당되어야 합니다. 앱을 사용하여 많은 리소스에 대한 배출 데이터를 내보내려는 경우 리소스 그룹 또는 구독 수준에서 역할을 할당할 수 있습니다. 자세한 내용은 Azure Portal사용하여 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
}
]
}
보고서 형식
| 보고서 유형 |
묘사 |
사용 시기 |
| OverallSummaryReport |
입력에 지정된 모든 구독 범위 및 날짜 범위에 대한 총 배출량입니다. |
높은 수준의 보고서 데이터 필요 |
| MonthlySummaryReport |
날짜 범위에 지정된 매월의 모든 구독 및 배출 범위에 대한 배출입니다. |
월별 분석 |
| TopItemsSummaryReport |
구독, 배출, 범위, 범주 및 지정된 날짜 범위에서 집계된 상위 X 항목의 배출은 범주별로 세분화됩니다. |
범주별 상위 항목에 대한 데이터 |
| TopItemsMonthlySummaryReport |
날짜 범위에 지정된 매월 구독, 배출, 범위 및 범주에 걸쳐 집계된 상위 X 항목의 배출입니다. 배출량은 범주별로 세분화됩니다. 상위 X 항목은 지난 달의 배출량을 기준으로 합니다. |
범주 및 월별 상위 항목에 대한 데이터 |
| ItemDetailsReport |
지정된 날짜 범위에 대해 선택한 범위 및 subscriptionsID에서 집계되고 지정된 범주별로 세분화된 배출입니다. |
범주별 배출 데이터 |
내보내기 API 매개 변수
다음 표에서는 REST API를 사용하여 배출 데이터를 내보내는 데 사용할 수 있는 매개 변수에 대해 설명합니다.
| 매개 변수 |
형 |
묘사 |
reportType |
문자열 |
보고서 형식 이름입니다. 지원되는 값: OverallSummaryReport
MonthlySummaryReport
TopItemsSummaryReport TopItemsMonthlySummaryReport ItemDetailsReport |
subscriptionList |
[String] |
쿼리할 subscriptionId 목록입니다. 클라이언트는 이러한 구독에 액세스할 수 있어야 합니다. |
resourceGroupUrlList |
[String] |
데이터를 가져올 resourceGroup URL 목록입니다. 예를 들어: "resourceGroupUrlList": [ "/subscriptions/sub-id-1111/resourcegroups/rg_name" ] 배열의 문자열 값은 다음 형식을 따라야 합니다. "/subscriptions/{sub_id}/resourcegroups/{rg_name}" |
carbonScopeList |
[String] |
탄소 범위 목록입니다. 지원되는 값: Scope1, Scope2 및 Scope3. 이 목록은 이러한 세 가지 범위의 조합일 수 있습니다. |
dateRange |
구조체 |
지난 12개월에서 1개월을 지원합니다. 시작 월과 끝 월은 같아야 하며 월의 첫 번째 날이어야 합니다. 이 조건이 충족되지 않으면 예외가 throw됩니다. 예를 들어 dateRange": { "start": "2023-03-01", "end": "2023-03-01}
start 및 end 형식: yyyy-mm-dd. 현재 탄소 배출 데이터는 매월 새로 고쳐집니다. 따라서 dateRangestart 및 end 속성 값은 매월 첫째 날이어야 합니다. |
메모
dateRange 한 번에 한 달(지난 12개월)을 지원합니다. 시작 날짜와 종료 날짜가 다를 때 예외가 throw됩니다.
보고서별 매개 변수
다음 표에서는 각 보고서 유형에 필요한 추가 매개 변수를 보여줍니다.
| AdditionalParameter |
형 |
묘사 |
보고서 |
categoryType |
문자열 |
5가지 범주 유형이 지원됩니다. 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 보고서에 대한 자세한 내용은 탄소 서비스 -탄소 배출 보고서 나열을 참조하세요.
