Ejemplos de consulta de OData para la API Cloud for Sustainability (versión preliminar)
Importante
Algunas o todas estas funciones están disponibles como parte de una versión preliminar. El contenido y la funcionalidad están sujetos a cambios.
El Protocolo de datos abiertos (OData) es un protocolo de acceso a datos basado en protocolos centrales como HTTP. Utiliza metodologías comúnmente aceptadas como REST para la web. Puede usar varios tipos de bibliotecas y herramientas que se pueden usar para consumir servicios OData.
Para ayudarle a construir sus propias implementaciones basadas en la API Microsoft Cloud for Sustainability, puede revisar algunas de estas consultas de ejemplo solicitadas con frecuencia.
Modifique los ejemplos de consulta para que funcionen en sus entornos de destino:
{serviceRoot} :
https://api.mcfs.microsoft.com/api/v1.0/instances/{instanceId}{instanceId} : el GUID del entorno de Cloud for Sustainability que desea consultar, por ejemplo 20aec369-f1c8-4814-a89d-4d449dd7e8a1.
{serviceRootM365} :
{serviceRoot}/m365{serviceRootAzure} :
{serviceRoot}/enrollments/{enrollmentId}{enrollmentId} : el ID de inscripción, también conocido como ID de cuenta de facturación. Ejemplo: 12345678.
{tenantId} : Id. de inquilino de Microsoft 365.
Nota
Algunas consultas de la API contendrán muchos resultados y se dividirán en varias páginas. La API devuelve un máximo de 1000 resultados por página. Si hay más resultados disponibles, la API devuelve una propiedad @odata.nextLink que contiene una URL a la siguiente página de resultados.
Entidad EnrollmentEmission (para emisiones de Azure)
Representa los datos de emisiones de una cuenta de facturación, también denominada inscripción.
| Property | Tipo | Notas |
|---|---|---|
| dateKey | int32 | Fecha en formato aaaammdd; dd es siempre 01. |
| enrollmentId | string | También conocido como ID de cuenta de facturación. |
| orgName | string | Igual que Nombre de TP o Nombre principal superior. |
| subscriptionId | string | Id. de la suscripción. |
| subscriptionName | string | Nombre de la suscripción. |
| azureServiceName | string | Nombre de un servicio de Azure, por ejemplo, App Service |
| subService | string | Por ejemplo, Azure Storage o Azure Compute. |
| azureRegionName | string | Región de Azure donde está implementado el servicio. |
| scope | string | Ámbito de gases de efecto invernadero, por ejemplo, ámbito 1, ámbito 2 o ámbito 3. |
| scopeId | int32 | Id. del ámbito. |
| totalEmissions | doble | Emisiones totales del registro (mtCO2e). |
Ejemplos de consultas para la entidad EnrollmentEmission (para emisiones de Azure)
| Tipo de consulta | Ejemplo |
|---|---|
| Emisiones por inscripción | {serviceRootAzure}/emissions |
| Seleccione ciertos campos | {serviceRootAzure}/emissions?$select=enrollmentId,totalEmissions,scopeId |
| Incluir recuento | {serviceRootAzure}/emissions?$count=true |
| Limitar recuento de resultados | {serviceRootAzure}/emissions?$top=100 |
| Paginación | {serviceRootAzure}/emissions?$skip=100&$top=50 |
| Filtrar por ámbito | {serviceRootAzure}/emissions?$filter=ScopeId eq 1 |
| Filtrar y agregar | {serviceRootAzure}/emissions?$apply=filter(ScopeId eq 1)/aggregate($count como Count, totalEmissions con el promedio como Average, totalEmissions con la suma como Sum) |
| Filtrar y agrupar | {serviceRootAzure}/emissions?$apply=filter(totalEmissions gt 0.05)/groupby((ScopeId), aggregate($count as Count))` |
Entidad Microsoft365Emission (para emisiones Microsoft 365)
Representa las emisiones del centro de datos de Microsoft 365 asociadas con las siguientes aplicaciones:
- Exchange Online
- SharePoint
- OneDrive
- Microsoft Teams
- Word
- Excel
- PowerPoint
- Outlook
| Property | Tipo | Notas |
|---|---|---|
| dateKey | int32 | Fecha en formato aaaammdd; dd es siempre 01. |
| tenantId | string | Id. de inquilino. |
| tenantName | string | Nombre del inquilino. |
| officeRegionName | string | Región del centro de datos de Microsoft 365. |
| scope | string | Ámbito de gases de efecto invernadero, por ejemplo, ámbito 1, ámbito 2 o ámbito 3. |
| totalEmissions | doble | Emisiones totales del registro (mtCO2e). |
Ejemplos de consultas para la entidad Microsoft365Emission (para emisiones de Microsoft 365)
| Tipo de consulta | Ejemplo |
|---|---|
| Emisiones para el inquilino | {serviceRootM365}/tenantemissions |
| Seleccione ciertos campos | {serviceRootM365}/emissions?$select=tenantId,totalEmissions,scope |
| Incluir recuento | {serviceRootM365}/tenantemissions?$count=true |
| Limitar recuento de resultados | {serviceRootM365}/tenantemissions?$top=100 |
| Paginación | {serviceRootM365}/tenantemissions?$skip=100&$top=50 |
| Filtrar por ámbito | {serviceRootM365}/tenantemissions?$filter=Scope eq 'FILLMEIN' |
| Filtrar y agregar | {serviceRootserviceRootM365Azure}/tenantemissions?$apply=filter(scope eq 'FILLMEIN')/aggregate($count como Count, totalEmissions con el promedio como Average, totalEmissions con la suma como Sum) |
| Filtrar y agrupar | {serviceRootM365}/tenantemissions?$apply=filter(totalEmissions gt 0.05)/groupby((Scope), aggregate($count as Count))` |
Entidad EnrollmentUsage (para emisiones de Azure)
Representa un factor de uso calculado de los recursos de Microsoft Cloud.
| Property | Tipo | Notas |
|---|---|---|
| dateKey | int32 | Fecha en formato aaaammdd; dd es siempre 01. |
| enrollmentId | string | También conocido como ID de cuenta de facturación. |
| orgName | string | Igual que Nombre de TP o Nombre principal superior. |
| subscriptionId | string | Id. de la suscripción. |
| subscriptionName | string | Nombre de la suscripción. |
| subService | string | Por ejemplo, Azure Storage o Azure Compute. |
| azureRegionName | string | Región de Azure donde está implementado el servicio. |
| usage | doble | Uso total del registro. No tiene la unidad porque representa el uso normalizado del servicio en la región especificada. |
Para obtener más información sobre la metodología de cálculo de Microsoft, vaya a Método de cálculo de la API de Microsoft Cloud for Sustainability.|
Ejemplos de consultas para la entidad EnrollmentUsage
| Tipo de consulta | Ejemplo | Nota |
|---|---|---|
| Todos los datos de uso | {serviceRootAzure}/usage | |
| Uso total por mes por suscripción | {serviceRootAzure}/usage?$apply=groupby((SubscriptionName,DateKey),aggregar(uso con suma como TotalUsage))&$orderby=SubscriptionName,DateKey |
Entidad EnrollmentProjection (para emisiones de Azure)
Representa las emisiones proyectadas para el resto del año natural, con base en una media acumulada de los cinco meses anteriores. Diseñado para visualizaciones anualizadas.
| Property | Tipo | Notas |
|---|---|---|
| dateKey | int32 | Fecha en formato aaaammdd; dd es siempre 01. |
| enrollmentId | string | También conocido como ID de cuenta de facturación. |
| actualEmissions | doble | Solo se incluye para fechas pasadas (mtCO2e). |
| projectedEmissions | doble | Basado en un media acumulada de los cinco meses anteriores o menos según los datos reales disponibles para el año actual (mtCO2e). |
| actualUsage | doble | Solo incluido para fechas pasadas. |
| projectedUsage | doble | Basado en un media acumulada de los cinco meses anteriores o menos según los datos reales disponibles para el año actual. |
Ejemplos de consultas para la entidad EnrollmentProjection (para emisiones de Azure)
| Tipo de consulta | Ejemplo | Nota |
|---|---|---|
| Proyecciones después de 7-2022 | {serviceRootAzure}/projections?$filter=dateKey gt 20220701 | |
| Todas las proyecciones para el año | {serviceRootAzure}/projections |
Importante
La API de Microsoft Cloud for Sustainability se encuentra actualmente en versión preliminar y está sujeta a cambios. Sus cifras históricas de emisiones también pueden actualizarse a medida que Microsoft realiza mejoras en la precisión y la integridad de los datos.
Preguntas frecuentes
¿Cómo calcula Microsoft las emisiones y el uso?
Para obtener información sobre la metodología de cálculo de Microsoft, vaya a Método de cálculo de la API de Microsoft Cloud for Sustainability.
¿Qué es Rownum?
La API usa rownum para una paginación uniforme. El valor está sujeto a cambios, por lo que su aplicación no debería depender de él.
¿Qué es un id. de inscripción?
Un id. de inscripción se refiere a un id. de cuenta de facturación. Busque su id. de inscripción y el id. de cuenta de facturación en Azure Portal.
¿Cómo obtengo un token de autorización para mi entorno de destino?
La API requiere un token de autorización de OAuth. Le recomendamos utilizar Microsoft Authentication Library (MSAL).
¿Puede proporcionar más información sobre cómo utilizar nextLink para la paginación?
La API devuelve una propiedad @odata.nextLink si hay más resultados que los devueltos en la respuesta actual. Su aplicación debe realizar otro GET en este nextLink para obtener la siguiente página de resultados. La última página no contiene un nextLink.
Explore este ejemplo de código para obtener más detalles sobre la paginación con una biblioteca de cliente OData.
Información relacionada
- Resumen general de API de Cloud for Sustainability
- Método de cálculo de la API de Microsoft Cloud for Sustainability
- API de Microsoft Cloud for Sustainability
