Exportar dados de emissões usando a API REST
Para exportar dados de emissões usando a API REST, você deve criar e autorizar uma entidade de serviço a acessar seus dados de emissões. Em seguida, você pode usar a entidade de serviço para obter um token de autorização e exportar dados de emissões usando a API REST.
Criar e autorizar uma entidade de serviço para exportar dados de emissões
Uma entidade de serviço é um aplicativo cujos tokens podem ser usados para autenticar e conceder acesso a recursos específicos do Azure usando a ID do Microsoft Entra (anteriormente do Azure Active Directory). Os recursos incluem aplicativos de usuário, serviços ou ferramentas de automação.
Criar um aplicativo do Microsoft Entra e uma entidade de serviço que possa acessar recursos.
Salve a ID do locatário, a nova ID do cliente e o valor do segredo do cliente para seu aplicativo para uso em solicitações de token.
O aplicativo deve receber a função Carbon Optimization Reader para os recursos para os quais você deseja exportar dados de emissões. Se você planeja usar o aplicativo para exportar dados de emissões para muitos recursos, poderá atribuir a função no nível do grupo de recursos ou da assinatura. Para obter mais informações, consulte Atribuir funções do Azure usando o portal do Azure.
Obter um token de autorização
Envie a solicitação a seguir no prompt de comando ou usando um cliente como o 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'
O corpo da resposta é exibido:
{
"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"
}
Use o token de acesso da resposta para uso nas solicitações HTTP a seguir.
Exportar dados de emissões usando a API REST
POST /providers/Microsoft.Carbon/carbonEmissionReports?api-version=2023-04-01-preview Host: management.azure.com Content-Type: application/json Authorization: Bearer <token value>
Solicitação de exemplo
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"
}
}
exemplo de 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"
}
}
'
Saída de exemplo
{
"value": [
{
"dataType": "OverallSummaryData",
"totalCarbonEmission": 7000.622265493289,
"totalCarbonEmission12MonthsAgo": 0,
"totalCarbonEmissionLastMonth": 7480.374908590786,
"changeRatioFor12Months": 0,
"changeRatioForLastMonth": -0.06413483935765417,
"changeValueMonthOverMonth": 0
}
]
}
Tipos de relatório
| Tipo de relatório |
Descrição |
Quando usar |
| OverallSummaryReport |
Total de emissões para todos os escopos de assinaturas e intervalo de datas especificados na entrada. |
Dados de relatório de alto nível necessários |
| MonthlySummaryReport |
Emissões para todas as assinaturas e escopos de emissões para cada mês especificado no intervalo de datas. |
Detalhamento mensal |
| TopItemsSummaryReport |
Emissões dos principais itens X agregados entre assinaturas, emissões, escopo, categoria e intervalo de datas especificado, divididos por categoria. |
Dados para os principais itens por categoria |
| TopItemsMonthlySummaryReport |
Emissões dos principais itens X agregados entre assinaturas, emissões, escopos e categoria para cada mês especificado no intervalo de datas. As emissões são divididas por categoria. Os principais itens X são baseados nas emissões do mês passado. |
Dados para os principais itens por categoria e mês |
| ItemDetailsReport |
Emissões agregadas entre escopos selecionados e subscriptionsIDs para um determinado intervalo de datas e divididas por categoria especificada. |
Dados de emissões por categoria |
Exportar parâmetros de API de emissões
A tabela a seguir descreve os parâmetros que você pode usar para exportar dados de emissões usando a API REST.
| Parâmetro |
Tipo |
Descrição |
reportType |
Corda |
Nome do tipo de relatório. Valores com suporte: OverallSummaryReport
MonthlySummaryReport
TopItemsSummaryReport TopItemsMonthlySummaryReport ItemDetailsReport |
subscriptionList |
[Cadeia de caracteres] |
A lista subscriptionId para a qual você deseja consultar. O cliente deve ter acesso a essas assinaturas. |
resourceGroupUrlList |
[Cadeia de caracteres] |
A lista de URLs do resourceGroup para a qual você deseja obter dados. Por exemplo: "resourceGroupUrlList": [ "/subscriptions/sub-id-1111/resourcegroups/rg_name" ] O valor da cadeia de caracteres na matriz deve seguir este formato: "/subscriptions/{sub_id}/resourcegroups/{rg_name}" |
carbonScopeList |
[Cadeia de caracteres] |
A lista de escopo de carbono. Valores com suporte: Scope1, Scope2 e Scope3. Essa lista pode ser qualquer combinação desses três escopos. |
dateRange |
Struct |
Dá suporte a um mês dos últimos 12 meses. O início e o fim do mês devem ser iguais e deve ser o primeiro dia de um mês. Uma exceção é gerada quando esse critério não é atendido. Por exemplo dateRange": { "start": "2023-03-01", "end": "2023-03-01} formato start e end: yyyy-mm-dd. Atualmente, os dados de emissões de carbono são atualizados mensalmente. Portanto, o valor das propriedades dateRangestart e end deve ser o primeiro dia de cada mês. |
Nota
dateRange dá suporte a um mês de cada vez (dos últimos 12 meses). Uma exceção é gerada quando as datas de início e término são diferentes.
Parâmetros específicos do relatório
A tabela a seguir mostra parâmetros adicionais que são necessários para cada tipo de relatório.
| AdditionalParameter |
Tipo |
Descrição |
Relatórios |
categoryType |
Corda |
Há suporte para cinco tipos de categoria: Subscription
Location
ServiceType
ResourceGroup
Resource
|
TopItemsSummaryReportTopItemsMonthlySummaryReport
ItemDetailsReport
|
topItemsCount |
Inteiro |
Os principais itens x a serem mostrados (>5) |
TopItemsSummaryReportTopItemsMonthlySummaryReport
|
ItemDetailsReport |
category |
Corda |
O nome da categoria. Por exemplo, "category": "ResourceGroup" |
pageSize |
Inteiro |
O tamanho da página do resultado da consulta. O valor padrão é 1000. O valor máximo é 2000. |
ItemDetailsReport |
orderBy |
Corda |
Consulte a tabela abaixo para ver os valores com suporte, juntamente com os Tipos de Categoria com suporte. |
ItemDetailsReport |
sortDirection |
Corda |
Valores de suporte: Desc, Asc |
ItemDetailsReport |
groupCategory |
Corda |
Isso pode ser definido como uma cadeia de caracteres vazia. Valores válidos: ResourceGroup e SubscriptionId |
ItemDetailsReport |
Ordenar por colunas
As colunas de resultado a seguir dão suporte ao parâmetro orderBy.
| Nome da ordem por coluna |
Tipo de categoria |
Name |
todos, exceto Subscription |
TotalCarbonEmission |
todo |
TotalCarbonEmissionLastMonth |
todo |
ResourceGroup |
apenas para Resource categoria |
SubscriptionId |
categoria Subscription, Resource e ResourceGroup |
ChangeRatioForLastMonth |
todo |
ChangeValueMonthOverMonth |
todo |
Para obter mais informações sobre os relatórios da API REST, consulte Carbon Service – List Carbon Emission Reports.
