Exemplos de consulta OData da API do Cloud for Sustainability (versão preliminar)
Microsoft Cloud for Sustainability
Importante
Algumas ou todas estas funcionalidades estão disponíveis como parte de uma versão preliminar. O conteúdo e a funcionalidade estão sujeitos a alterações.
Protocolo Open Data (OData) é um protocolo de acesso a dados baseado em protocolos importantes como HTTP. Ele usa metodologias comumente aceitas como REST para a Web. Você pode usar várias bibliotecas e ferramentas para consumir serviços OData.
Para ajudar na criação de suas próprias implementações com base na API do Microsoft Cloud for Sustainability, você pode revisar algumas destas consultas de exemplo solicitadas frequentemente.
Modifique os exemplos de consulta para fazê-los funcionar nos seus ambientes de destino:
{serviceRoot}:
https://api.mcfs.microsoft.com/api/v1.0/instances/{instanceId}{instanceId}: o GUID do ambiente do Cloud for Sustainability que você deseja consultar, como 20aec369-f1c8-4814-a89d-4d449dd7e8a1.
{serviceRootM365}:
{serviceRoot}/m365{serviceRootAzure}:
{serviceRoot}/enrollments/{enrollmentId}{enrollmentId}: a ID de inscrição, também conhecida como ID da conta de cobrança. Exemplo: 12345678.
{tenantId}: ID do locatário do Microsoft 365.
Observação
Algumas consultas de API conterão muitos resultados e serão divididas em várias páginas. A API retorna um máximo de 1.000 resultados por página. Se houver mais resultados disponíveis, a API retornará uma propriedade @odata.nextLink contendo uma URL para a próxima página de resultados.
Entidade EnrollmentEmission (para emissões do Azure)
Representa os dados de emissão de uma conta de cobrança, também chamada de inscrição.
| Propriedade | Tipo | Notes |
|---|---|---|
| dateKey | int32 | Data no formato aaaammdd; dd é sempre 01. |
| enrollmentId | cadeia | Também conhecida como ID da conta de cobrança. |
| orgName | cadeia | Igual ao nome TP ou ao nome pai superior. |
| subscriptionId | cadeia | ID da assinatura. |
| subscriptionName | cadeia | Nome da assinatura. |
| azureServiceName | cadeia | Nome de um serviço do Azure; por exemplo, "Serviço de Aplicativo". |
| subService | cadeia | Por exemplo, Armazenamento do Azure ou Computação do Azure. |
| azureRegionName | cadeia | A região do Azure onde o serviço está implantado. |
| escopo | cadeia | Escopo dos gases de efeito estufa; por exemplo, escopo 1, escopo 2 ou escopo 3. |
| scopeId | int32 | ID do escopo. |
| totalEmissions | dupla | Emissões totais para registro (mtCO2e). |
Consultas de exemplo para a entidade EnrollmentEmission (para emissões do Azure)
| Tipo de consulta | Exemplo |
|---|---|
| Emissões por inscrição | {serviceRootAzure}/emissões |
| Selecionar determinador campos | {serviceRootAzure}/emissions?$select=enrollmentId,totalEmissions,scopeId |
| Incluir conta | {serviceRootAzure}/emissions?$count=true |
| Limitar contagem de resultados | {serviceRootAzure}/emissions?$top=100 |
| Paginação | {serviceRootAzure}/emissions?$skip=100&$top=50 |
| Filtrar por escopo | {serviceRootAzure}/emissions?$filter=ScopeId eq 1 |
| Filtrar e agregar | {serviceRootAzure}/emissions?$apply=filter(ScopeId eq 1)/aggregate($count com Contagem, totalEmissions com média como Média, totalEmissions com a soma como Soma) |
| Filtrar e agrupar | {serviceRootAzure}/emissions?$apply=filter(totalEmissions gt 0.05)/groupby((ScopeId), aggregate($count como Contagem))` |
Entidade Microsoft365Emission (para emissões do M365)
Representa emissões de datacenter do Microsoft 365 associadas aos seguintes aplicativos:
- Exchange Online
- SharePoint
- OneDrive
- Microsoft Teams
- Word
- Excel
- PowerPoint
- Outlook
| Propriedade | Tipo | Notes |
|---|---|---|
| dateKey | int32 | Data no formato aaaammdd; dd é sempre 01. |
| tenantId | cadeia | ID do locatário. |
| tenantName | cadeia | Nome do locatário. |
| officeRegionName | cadeia | Região de datacenter do Microsoft 365. |
| escopo | cadeia | Escopo dos gases de efeito estufa; por exemplo, escopo 1, escopo 2 ou escopo 3. |
| totalEmissions | dupla | Emissões totais para registro (mtCO2e). |
Consultas de exemplo para a entidade Microsoft365Emission (para emissões do M365)
| Tipo de consulta | Exemplo |
|---|---|
| Emissões do locatário | {serviceRootM365}/tenantemissions |
| Selecionar determinador campos | {serviceRootM365}/emissions?$select=tenantId,totalEmissions,scope |
| Incluir conta | {serviceRootM365}/tenantemissions?$count=true |
| Limitar contagem de resultados | {serviceRootM365}/tenantemissions?$top=100 |
| Paginação | {serviceRootM365}/tenantemissions?$skip=100&$top=50 |
| Filtrar por escopo | {serviceRootM365}/tenantemissions?$filter=Scope eq 'FILLMEIN' |
| Filtrar e agregar | {serviceRootserviceRootM365Azure}/tenantemissions?$apply=filter(scope eq 'FILLMEIN')/aggregate($count como Contagem, totalEmissions com média como Média, totalEmissions com soma como Soma) |
| Filtrar e agrupar | {serviceRootM365}/tenantemissions?$apply=filter(totalEmissions gt 0.05)/groupby((Scope), aggregate($count como Contagem))` |
Entidade EnrollmentUsage (para emissões do Azure)
Representa um fator de uso calculado dos recursos de nuvem da Microsoft.
| Propriedade | Tipo | Notes |
|---|---|---|
| dateKey | int32 | Data no formato aaaammdd; dd é sempre 01. |
| enrollmentId | cadeia | Também conhecida como ID da conta de cobrança. |
| orgName | cadeia | Igual ao nome TP ou ao nome pai superior. |
| subscriptionId | cadeia | ID da assinatura. |
| subscriptionName | cadeia | Nome da assinatura. |
| subService | cadeia | Por exemplo, Armazenamento do Azure ou Computação do Azure. |
| azureRegionName | cadeia | A região do Azure onde o serviço está implantado. |
| uso ativo | dupla | Uso total do registro. Não tem a unidade porque ela representa o uso normalizado do serviço na região especificada. |
Para obter mais informações sobre a metodologia de cálculo da Microsoft, acesse Metodologia de cálculo da API do Microsoft Cloud for Sustainability.|
Consultas de exemplo para a entidade EnrollmentUsage
| Tipo de consulta | Exemplo | Observação |
|---|---|---|
| Todos os dados de uso | {serviceRootAzure}/uso | |
| Uso total por mês por assinatura | {serviceRootAzure}/usage?$apply=groupby((SubscriptionName,DateKey),aggregate(uso com soma como TotalUsage))&$orderby=SubscriptionName,DateKey |
Entidade EnrollmentProjection (para emissões do Azure)
Representa as emissões projetadas para o restante do ano fiscal, com base na média móvel dos cinco meses anteriores. Destinado a visualizações anualizadas.
| Propriedade | Tipo | Notes |
|---|---|---|
| dateKey | int32 | Data no formato aaaammdd; dd é sempre 01. |
| enrollmentId | cadeia | Também conhecida como ID da conta de cobrança. |
| actualEmissions | dupla | Incluído apenas para datas passadas (mtCO2e). |
| projectedEmissions | dupla | Com base em uma média móvel dos cinco meses anteriores ou menos com base nos dados reais disponíveis para o ano atual (mtCO2e). |
| actualUsage | dupla | Incluído somente para datas passadas. |
| projectedUsage | dupla | Com base em uma média móvel dos cinco meses anteriores ou menos com base nos dados reais disponíveis para o ano atual. |
Consultas de exemplo para a entidade EnrollmentProjection (para emissões do Azure)
| Tipo de consulta | Exemplo | Observação |
|---|---|---|
| Projeções após 7-2022 | {serviceRootAzure}/projections?$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 versão preliminar e está sujeita a alterações. Seus valores históricos de emissões também podem ser atualizados à medida que a Microsoft faz melhorias na precisão e integridade dos dados.
Perguntas frequentes
Como a Microsoft calcula as emissões e o uso?
Para obter mais informações sobre a metodologia de cálculo da Microsoft, acesse Metodologia de cálculo da API do Microsoft Cloud for Sustainability.
O que é Rownum?
A API usa rownum para a paginação consistente. O valor está sujeito a alterações, portanto, seu aplicativo não deve depender dele.
O que é uma ID de inscrição?
Uma ID de inscrição refere-se a uma ID da conta de cobrança. Encontre sua ID de inscrição e a ID da conta de cobrança no portal do Azure.
Como faço para obter um token de autorização para meu ambiente de destino?
A API requer um token de autorização OAuth. Recomendamos usar a Biblioteca de Autenticação da Microsoft (MSAL).
Você pode fornecer mais informações sobre como usar o nextLink para paginação?
A API retornará uma propriedade @odata.nextLink se houver mais resultados do que os retornados na resposta atual. Seu aplicativo deve executar outro GET neste nextLink para obter a próxima página de resultados. A última página não conterá um nextLink.
Explore este exemplo de código para obter mais detalhes sobre paginação com uma biblioteca de clientes OData.
