Exemplos de consulta OData da API do Cloud for Sustainability (pré-visualização)
Importante
Algumas ou todas estas funcionalidades estão disponíveis como parte de uma versão de pré-visualização. O conteúdo e a funcionalidade estão sujeitos a alterações.
O Protocolo de Dados Aberto (OData) é um protocolo de acesso a dados criado com base em protocolos nucleares, como o HTTP. Utiliza metodologias normalmente aceites como o REST para a Web. Pode utilizar várias bibliotecas e ferramentas para consumir serviços OData.
Para o ajudar a criar as suas próprias implementações com base na API do Microsoft Cloud for Sustainability, pode rever algumas destas consultas de exemplo pedidas com frequência.
Modifique as amostras de consulta para as fazer trabalhar nos seus ambientes de destino:
{serviceRoot}:
https://api.mcfs.microsoft.com/api/v1.0/instances/{instanceId}{instanceId}: O GUID do ambiente Cloud for Sustainability que você deseja consultar, como 20aec369-f1c8-4814-a89d-4d449dd7e8a1.
{serviceRootM365}:
{serviceRoot}/m365{serviceRootAzure}:
{serviceRoot}/enrollments/{enrollmentId}{enrollmentId}: O ID de inscrição, também conhecido como ID da conta de cobrança. Exemplo: 12345678.
{tenantId}: Microsoft 365 ID do inquilino.
Nota
Algumas consultas da API irão conter muitos resultados e serão divididas em várias páginas. A API devolve um máximo de 1000 resultados por página. Se estiverem disponíveis mais resultados, a API devolve uma propriedade @odata.nextLink que contém um URL à página seguinte de resultados.
Entidade EnrollmentEmission (para emissões do Azure)
Representa os dados de emissões de uma conta de faturação, também denominada de inscrição.
| Propriedade | Tipo | Notas |
|---|---|---|
| dateKey | int32 | Data no formato aaaammdd; dd é sempre 01. |
| enrollmentId | cadeia | Também conhecido como ID de conta de faturação. |
| orgName | cadeia | O mesmo que Nome de TP ou Nome Principal Superior. |
| subscriptionId | cadeia | ID da subscrição. |
| subscriptionName | cadeia | Nome da subscrição. |
| azureServiceName | cadeia | Nome de um serviço do Azure, por exemplo, o Serviço de Aplicações |
| subService | cadeia | Por exemplo, Armazenamento do Azure ou Computação do Azure. |
| azureRegionName | cadeia | A região do Azure onde o serviço está implementado. |
| âmbito | cadeia | Âmbito do gás com efeito de estufa, por exemplo, âmbito 1, âmbito 2 ou âmbito 3. |
| scopeId | int32 | ID do âmbito. |
| totalEmissions | duplo | Total de emissões para o registo (mtCO2e). |
Consultas de amostra para a entidade EnrollmentEmission (para emissões do Azure)
| Tipo de consulta | Exemplo |
|---|---|
| Emissões por inscrição | {serviceRootAzure}/emissões |
| Selecionar determinados campos | {serviceRootAzure}/emissions?$select=enrollmentId,totalEmissions,scopeId |
| Incluir contagem | {serviceRootAzure}/emissões?$count=true |
| Limitar contagem de resultados | {serviceRootAzure}/emissões?$top=100 |
| Paginação | {serviceRootAzure}/emissões?$skip=100&$top=50 |
| Filtrar por âmbito | {serviceRootAzure}/emissões?$filter=ScopeId eq 1 |
| Filtrar e agregar | {serviceRootAzure}/emissões?$apply=filter(ScopeId eq 1)/aggregate($count como Contagem, totalEmissões com média como Média, totalEmissões com soma como Soma) |
| Filtrar e agrupar | {serviceRootAzure}/emissions?$apply=filter(totalEmissions gt 0.05)/groupby((ScopeId), aggregate($count as Count))» |
Entidade Microsoft365Emission (para emissões do Microsoft 365)
Representa as emissões do datacenter do Microsoft 365 associadas às seguintes aplicações:
- Exchange Online
- SharePoint
- OneDrive
- Microsoft Teams
- Word
- Excel
- PowerPoint
- Outlook
| Propriedade | Tipo | Notas |
|---|---|---|
| dateKey | int32 | Data no formato aaaammdd; dd é sempre 01. |
| tenantId | cadeia | ID do inquilino. |
| tenantName | cadeia | Nome do inquilino. |
| officeRegionName | cadeia | Região do datacenter do Microsoft 365. |
| âmbito | cadeia | Âmbito do gás com efeito de estufa, por exemplo, âmbito 1, âmbito 2 ou âmbito 3. |
| totalEmissions | duplo | Total de emissões para o registo (mtCO2e). |
Consultas de amostra para a entidade Microsoft365Emission (para emissões do Microsoft 365)
| Tipo de consulta | Exemplo |
|---|---|
| Emissões para inquilino | {serviceRootM365}/inquilinoemissões |
| Selecionar determinados campos | {serviceRootM365}/emissions?$select=tenantId,totalEmissions,scope |
| Incluir contagem | {serviceRootM365}/tenantemissions?$count=true |
| Limitar contagem de resultados | {serviceRootM365}/tenantemissions?$top=100 |
| Paginação | {serviceRootM365}/inquilinoemissões?$skip=100&$top=50 |
| Filtrar por âmbito | {serviceRootM365}/tenantemissions?$filter=Scope eq 'FILLMEIN' |
| Filtrar e agregar | {serviceRootserviceRootM365Azure}/tenantemissions?$apply=filter(scope eq 'FILLMEIN')/aggregate($count como Contagem, totalEmissões com média como Média, totalEmissões com soma como Soma) |
| Filtrar e agrupar | {serviceRootM365}/tenantemissions?$apply=filter(totalEmissions gt 0.05)/groupby((Scope), aggregate($count as Count))» |
Entidade EnrollmentUsage (para emissões do Azure)
Representa um factor de utilização calculado dos recursos da cloud da Microsoft.
| Propriedade | Tipo | Notas |
|---|---|---|
| dateKey | int32 | Data no formato aaaammdd; dd é sempre 01. |
| enrollmentId | cadeia | Também conhecido como ID de conta de faturação. |
| orgName | cadeia | O mesmo que Nome de TP ou Nome Principal Superior. |
| subscriptionId | cadeia | ID da subscrição. |
| subscriptionName | cadeia | Nome da subscrição. |
| subService | cadeia | Por exemplo, Armazenamento do Azure ou Computação do Azure. |
| azureRegionName | cadeia | A região do Azure onde o serviço está implementado. |
| ativa | duplo | Utilização total do registo. Não tem a unidade porque representa a utilização normalizada do serviço na região especificada. |
Para mais informações sobre a metodologia de cálculo da Microsoft, aceda a Metodologia de cálculo da API do Microsoft Cloud for Sustainability.|
Consultas de amostra para a entidade EnrollmentUsage
| Tipo de consulta | Exemplo | Nota |
|---|---|---|
| Todos os dados de utilização | {serviceRootAzure}/uso | |
| Utilização total por mês por subscrição | {serviceRootAzure}/usage?$apply=groupby((SubscriptionName,DateKey),aggregate(usage with sum as TotalUsage))&$orderby=SubscriptionName,DateKey |
Entidade EnrollmentProjection (para emissões do Azure)
Representa as emissões projetadas para o restante ano civil, com base numa média móvel dos cinco meses anteriores. Destina-se a visualizações anualizadas.
| Propriedade | Tipo | Notas |
|---|---|---|
| dateKey | int32 | Data no formato aaaammdd; dd é sempre 01. |
| enrollmentId | cadeia | Também conhecido como ID de conta de faturação. |
| actualEmissions | duplo | Apenas incluído para datas passadas (mtCO2e). |
| projectedEmissions | duplo | Com base numa média móvel dos últimos cinco meses ou menos, com base nos dados reais disponíveis para o ano atual (mtCO2e). |
| actualUsage | duplo | Apenas incluídas em datas passadas. |
| projectedUsage | duplo | Com base numa média móvel dos últimos cinco meses ou menos, com base nos dados reais disponíveis para o ano atual. |
Consultas de amostra para a entidade EnrollmentProjection (para emissões do Azure)
| Tipo de consulta | Exemplo | Nota |
|---|---|---|
| Projeções passadas 7-2022 | {serviceRootAzure}/projeções?$filter=dateKey gt 20220701 | |
| Todas as projeções para o ano | {serviceRootAzure}/projeções |
Importante
A API do Microsoft Cloud for Sustainability está atualmente em pré-visualização e está sujeita a alterações. Os números das emissões históricas também podem ser atualizadas à medida que a Microsoft faz melhorias na precisão e integridade dos dados.
FAQ
Como são calculadas as emissões e a utilização pela Microsoft?
Para obter informações sobre a metodologia de cálculo da Microsoft, aceda a Microsoft Cloud for Sustainability metodologia de cálculo da API.
O que é Rownum?
A API utiliza o rownum para paginação consistente. O valor está sujeito a alteração, pelo que a sua aplicação não deve depender do mesmo.
O que é uma ID de inscrição?
Uma ID de inscrição refere-se à ID de conta de faturação. Encontre o ID de inscrição e o ID da conta de cobrança no portal Azure.
Como obter um token de autorização para o meu ambiente de destino?
A API requer um token de autorização OAuth. Recomendamos a utilização da Biblioteca de Autenticações da Microsoft (MSAL).
Pode fornecer mais informações sobre como utilizar a nextLink para paginação?
A API devolve uma propriedade @odata.nextLink se houver mais resultados do que os devolvidos na resposta atual. A aplicação deve executar outra GET nesta nextLink para obter a página de resultados seguinte. A última página não contém um nextLink.
Explore esta amostra de código para mais detalhes sobre paginação com uma biblioteca de clientes OData.
Informações relacionadas
- Visão geral da API Cloud for Sustainability
- Microsoft Cloud for Sustainability Metodologia de cálculo API
- Microsoft Cloud for Sustainability API
