Descripción general de la API Cloud for Sustainability (versión preliminar)

  • Artículo

Cumbre Técnica de mayo 2024 de Microsoft Cloud for Sustainability

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.

Microsoft Cloud for Sustainability proporciona API para obtener acceso a los datos de emisiones relacionados con su uso de Azure y Microsoft 365.

La contabilidad precisa del carbono requiere buena información de los socios, distribuidores y proveedores. Las API de Cloud for Sustainability le brindan transparencia sobre las emisiones de carbono generadas por su uso de Azure y Microsoft 365. La contabilidad de carbono de Microsoft se extiende a los tres ámbitos de las emisiones con una metodología validada de terceros. Utiliza una contabilidad de carbono coherente y precisa para cuantificar el efecto de Azure y Microsoft 365 en la huella ambiental de los clientes.

Los detalles de la API se enumeran en la Referencia de las API de Microsoft Cloud for Sustainability. Incluyen información adicional sobre operaciones, parámetros y respuestas.

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. Este versión preliminar no está destinada a fines de cumplimiento legal, marketing o informes.

Introducción a las API de Cloud for Sustainability

Nota

Si su organización desea obtener acceso a la API de Microsoft Cloud for Sustainability (versión preliminar), envíe este formulario de registro.

Empiece a utilizar las API con los siguientes procedimientos:

Cuentas compatibles

  • Azure: las API de Microsoft Cloud for Sustainability para Azure admiten cuentas EA Direct, MCA y MPA con una relación de facturación directa con Microsoft. Los clientes que compran Azure de un proveedor de soluciones en la nube (CSP) no son compatibles y deben trabajar directamente con su CSP para conocer sus emisiones en la nube. No se admiten cuentas heredadas, cuentas basadas en créditos, inscripciones en China ni cuentas de Azure Government. Para comprobar su tipo de cuenta, vaya a Consulte el tipo de su cuenta.

    Nota

    La utilización de la Ventaja híbrida de Azure actualmente no se captura ni se refleja en las emisiones.

  • Microsoft 365: las API de Microsoft Cloud for Sustainability para Microsoft 365 admiten suscripciones comerciales, empresariales o educativas para Microsoft 365 u Office 365. No son compatibles las implementaciones de nube nacional/regional, incluidas, entre otras, las nubes del gobierno de EE. UU. de Microsoft y Office 365 operado por 21Vianet.

Registrarse y crear una instancia

Después de recibir acceso a las API de Microsoft Cloud for Sustainability de Microsoft, inicie sesión con sus credenciales de Azure Microsoft Entra ID.

Debe crear una instancia para acceder a las API de Microsoft Cloud for Sustainability. Al crear la instancia, se convierte en el administrador de esa instancia. El administrador de la instancia puede agregar usuarios, grupos y aplicaciones a la instancia.

Mire este video para obtener una descripción general del uso de las API y el portal de Cloud for Sustainability:

Configurar orígenes de datos y habilitar las API

Importante

Para habilitar con éxito el acceso a los datos de su organización, este paso debe ser realizado por el administrador correspondiente. Para las cuentas de Azure MCA, se requiere una cuenta de facturación Administrador con un rol como cuenta de facturación Lector, colaborador, o propietario. Para las cuentas Azure EA, se requiere un Administrador de empresa o Administrador de empresa - solo lectura. Compruebe su rol en el Azure Portal. Para Microsoft 365, se requiere uno de los siguientes roles: administrador global, administrador de Exchange, administrador de Skype Empresarial, administrador de SharePoint, lector global, lector de informes. Los administradores de Azure y Microsoft 365 pueden crear instancias o ser agregados a instancias para habilitar orígenes de datos y la API. Si no tiene un rol de administración necesario para habilitar los datos, puede explorar la API solo con datos de demostración.

  1. En la pestaña Orígenes de datos, ponga la conexión en on para conectar los datos de emisiones de Azure o Microsoft 365. Asegúrese de que el estado aparezca como Disponible antes de usar las API. Esta acción habilita los datos de emisiones relacionados con todas las asignaciones o cuentas de facturación a las que tiene acceso. Si no tiene acceso a ningún dato de emisiones, proceda solo con los datos de demostración.

    Nota

    Los datos de emisiones de Microsoft 365 pueden tardar hasta 48 horas en estar disponibles después de habilitar el origen de datos. Al deshabilitar el origen de datos de Microsoft 365, se eliminarán de forma permanente los datos históricos de emisiones de Microsoft 365.

    Orígenes de datos.

  2. Seleccione la pestaña API Management y, a continuación, seleccione Habilitar.

    Al habilitar la API, se generan claves de API principales y secundarias para que su instancia las use en las solicitudes de API. Para volver a generar las claves, seleccione Icono Actualizar. . Para copiar las claves, seleccione Copiar icono. .

¿Está interesado en configurar una aplicación para llamar a la API Cloud for Sustainability? Vea esta demostración:

Probar las API

En la pestaña Administración de API, seleccione Probar API para explorar OData y Exportar API. Consulte de forma interactiva sus datos de emisiones conectando las API de OData de baja latencia a sus paneles. O bien, realice su propio procesamiento masivo transfiriendo sus datos de emisiones directamente a su Azure Data Lake Storage utilizando las API de exportación. Se abre un portal para desarrolladores en una nueva pestaña donde puede explorar los esquemas de solicitud y respuesta y realizar solicitudes en vivo contra las Microsoft Cloud for Sustainability API.

Pruebe las API de OData

  1. En la barra de navegación de la izquierda, asegúrese de que Agrupar por etiqueta esté habilitado y seleccione la agrupación OData para revisar Azure y Microsoft 365 API OData.

  2. Para realizar una solicitud en vivo, seleccione Probar. Introduzca todos los campos obligatorios:

    • Autorización: token de autorización rellenado automáticamente
    • Clave de suscripción: se completa automáticamente con la clave API desde la pestaña API Management
    • enrollmentId: su ID de inscripción, también conocido como ID de cuenta de facturación. Azure solo. Si no tiene acceso a una inscripción, puede explorar la API usando datos de demostración ingresando demodata en este campo.
    • instanceId: se encuentra en la URL del portal de la API de Microsoft Cloud for Sustainability
    • tenantId: Microsoft 365 Id. de inquilino

    Página Probar.

  3. Agregue todos los parámetros de consulta necesarios. Desplácese hacia la parte inferior del panel lateral y seleccione Enviar. La respuesta HTTP se mostrará en la parte inferior del panel.

Mire este video para obtener más información sobre las API de Cloud for Sustainability con OData:

Pruebe a exportar API

  1. En la barra de navegación de la izquierda, asegúrese de que Agrupar por etiqueta esté habilitado y seleccione la agrupación Exportar para comenzar a exportar las emisiones y datos de uso a su lago de datos. Seleccione RunExportJob.

  2. Seleccione Probarlo. Introduzca todos los campos obligatorios y seleccione Enviar.

    • Autorización: token de autorización rellenado automáticamente
    • Clave de suscripción: se completa automáticamente con la clave API desde la pestaña API Management
    • instanceId: se encuentra en la URL del portal de la API de Microsoft Cloud for Sustainability
    • exportJobType: Seleccione Azure o Microsoft 365 para designar el origen de datos para exportar los datos de emisiones y uso.
    • demodata: Ingrese "verdadero" si desea explorar esta funcionalidad exportando datos de demostración.

  3. Después de seleccionar Enviar, desplácese hacia abajo para ver la respuesta HTTP. Si está exportando datos de Azure, la respuesta enumera los identificadores de inscripción para los datos exportados. Si no tiene acceso a Azure o a datos de Microsoft 365, esta operación no se realiza correctamente. Asegúrese de que ha configurado adecuadamente sus orígenes de datos.

    Inicialmente, la respuesta indica que el trabajo tiene NotStarted. El trabajo de exportación tarda de 2 a 3 minutos en completarse y puede usar el Id. de trabajo para comprobar el estado de la exportación mediante la API ExportJobStatus. Asegúrese de que el trabajo se haya realizado correctamente, lo que indica que los datos exportados ahora están disponibles en el almacenamiento de blobs provisional.

    Puede usar LatestExportJob para revisar la información sobre su último trabajo de exportación.

    Puede usar la API ExportJobs para revisar la información sobre su histórico de exportaciones.

  4. Utilice la API ExportLocation para obtener la URL de SAS. La URL de SAS caducará después de dos horas. Copie la URL de SAS para acceder a los datos exportados desde el almacenamiento de blobs provisional.

  5. Los datos caducan 28 días después de ejecutar el trabajo de exportación y deben copiarse antes de que caduquen. De lo contrario, los datos se eliminan de la ubicación provisional. Los usuarios pueden volver a ejecutar un trabajo de exportación en cualquier momento para obtener otro lote de datos con un vencimiento de 28 días e incluido el conjunto de datos más reciente. Hay varias formas de acceder a los datos exportados.

    1. Azure Storage Explorer

      Instale y abra el Explorador de Azure Storage. Seleccione el botón Abrir cuadro de diálogo de conexión y luego seleccione Contenedor o directorio ADLS Gen2. Seleccione URL de firma de acceso compartido (SAS) y pegue la URL de SAS del paso 4 en la entrada Contenedor de blobs o URL de SAS de directorio. Seleccione Siguiente y luego seleccione Conectar. Debe ubicar o crear un contenedor en una cuenta de almacenamiento nueva o existente para usarlo para almacenar estos datos exportados. Copie los datos de Azure o Microsoft 365 del almacenamiento de blobs provisional y péguelos en el contenedor de su elección.

    2. Utilice azcopy. Con la URL de SAS del paso 4 y la URL de la cuenta de almacenamiento donde está almacenando sus emisiones exportadas (URL de destino), ejecute el comando azcopy.exe:

      • azcopy login
      • azcopy list <SAS URL>
      • azcopy cp <SAS URL> <destination URL>

    3. Script de Spark

      Utilice mssparkutils en Microsoft Fabric o Synapse. Puede optar por utilizar bibliotecas y entornos alternativos.

      import subprocess
from notebookutils import mssparkutils

result = subprocess.run(['pip', 'install', 'azure-storage-blob'], capture_output=True)

# replace with SAS URI from API request
source_sas_url = 'https://<account_name>.blob.windows.net/<container_name>/<path>?<sas_token>'

start_index = source_sas_url.find('https://') + len('https://')
end_index = source_sas_url.find('.blob', start_index)
account_name = source_sas_url[start_index:end_index]
split = source_sas_url.split('?', 1)
domain_path = split[0]
sas_token = split[1]
container_name = domain_path.split('/')[3]

source_mount_point = '/src'
destination_mount_point = '/dest'

mssparkutils.fs.unmount(source_mount_point)
mssparkutils.fs.mount(
    f'abfss://{container_name}@{account_name}.blob.core.windows.net',
    source_mount_point,
    { 'sasToken': sas_token })

mssparkutils.fs.unmount(destination_mount_point)
mssparkutils.fs.mount( 
    'abfss://<destinationPath>', # replace with destination connection string
    destination_mount_point)

mssparkutils.fs.cp(src_path, dest_path, True)

Consultas de ejemplo

Para ver una breve lista de consultas de muestra de OData para trabajar con las API, vaya a Ejemplos de consultas de OData.

Asignar permisos

El acceso a las API de Microsoft Cloud for Sustainability está restringido a los usuarios de su organización que un administrador de una instancia agrega a la aplicación. Un usuario puede ser un solo usuario, grupo o aplicación. No se admiten las cuentas de invitado. Hay tres tipos diferentes de roles que se pueden asignar:

  • Espectador: puede ver todas las páginas dentro de la API de Microsoft Cloud for Sustainability.
  • Colaborador: puede interactuar con todas las páginas del portal de la API de Microsoft Cloud for Sustainability. No puede agregar ni quitar usuarios.
  • Administrador: todos los permisos disponibles, incluida la capacidad de agregar o eliminar usuarios.

Nota

Los colaboradores y administradores no pueden deshabilitar ni habilitar el origen de datos de Microsoft 365 a menos que sean administrador global, administrador de Exchange, administrador de Skype Empresarial, administrador de SharePoint, lector global o lector de informes.

Para agregar usuarios, grupos o aplicaciones como administrador:

  1. Seleccione la pestaña Permisos y, después, Agregar usuarios.
  2. Utilice el campo Buscar para encontrar el usuario, la aplicación o grupo de Microsoft Entra ID que desea agregar.
  3. Seleccione una asignación de roles y, a continuación, seleccione Guardar.

Administrar instancias

Vaya al icono de instancias Icono de instancia para obtener una lista de todas las instancias, crear instancias o eliminar instancias.

Ver el uso de la API

Ver detalles sobre su uso de API en tiempo real.

  1. Vaya a la pestaña API Management y seleccione Uso.
  2. Seleccione un plazo de tiempo que quiera ver.

La página Uso de API contiene tres secciones:

  • Llamadas API: un gráfico que visualiza el número agregado de llamadas API en el plazo de tiempo seleccionado.
  • Transferencia de datos: un gráfico que muestra la cantidad de datos que se transfirieron a través de la API en el período de tiempo seleccionado.
  • Operaciones: una tabla con filas para cada operación de API disponible y detalles sobre el uso de las operaciones.

Preguntas frecuentes

¿Cómo calcula Microsoft las emisiones de carbono en la nube que pone a disposición la API?

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.

¿Dónde puedo obtener más información sobre cómo escribir consultas con OData?

Para obtener más información sobre OData, vaya a Información general de las opciones de consulta.

¿Dónde se almacenan los datos utilizados para producir este informe?

Los datos se guardan en Estados Unidos.

¿Por qué no puedo ver los datos de emisiones del mes anterior?

Los datos de emisiones de un mes determinado estarán disponibles el día 14 después del final de ese mes (incluidos los días no laborables).

No puedo crear una instancia. ¿Por qué?

Es posible que esté intentando acceder al portal de API Cloud for Sustainability con una cuenta que está asociada con un id. de inquilino de host diferente al proporcionado en el formulario de incorporación. Esta situación puede ocurrir cuando utiliza una cuenta de invitado. No se admiten las cuentas de invitado. Si desea que incorporemos a otro inquilino, vuelva a enviar el formulario de incorporación.

Tengo un Id. de inquilino diferente para Microsoft 365 y Azure. ¿Puedo usar la API de Microsoft Cloud for Sustainability?

Todavía puede acceder a las API, pero el portal no admite varios inquilinos por instancia. Debe incorporar estos inquilinos a las API por separado.

¿Cómo configuro una aplicación para llamar a la API de Microsoft Cloud for Sustainability?

¿Está interesado en configurar una aplicación para llamar a la API Cloud for Sustainability? Vea esta demostración:

En Azure Portal, vaya a su Microsoft Entra ID, seleccione Registros de aplicaciones y luego seleccione + Nuevo registro. En la nueva página de registro, asigne un nombre para el registro de su aplicación, personalice las opciones según sus necesidades y luego seleccione Registrar. Vaya a la página Microsoft Entra ID, seleccione la hoja Aplicaciones empresariales, establezca Tipo de aplicación en Microsoft Applications y busque por nombre de aplicación MCFS SDS. El parámetro ApplicationId que pasó en el comando New-AzADServicePrincipal requerido durante la incorporación es el ApplicationId del Microsoft Cloud for Sustainability API (c3163bf1-092f-436b-b260-7ade5973e5b9) con el que creó una instancia (aplicación empresarial) del registro de la aplicación API de Microsoft Cloud for Sustainability en su propio inquilino.

Con eso en su lugar, ahora puede ir a la página de registro de su aplicación y seleccionar la hoja permisos de la API. Para agregar permiso para que el registro de su aplicación pueda llamar a la API de Microsoft Cloud for Sustainability, seleccione + Agregar un permiso, seguido por la opción API que usa mi organización. Luego, busque el ApplicationId de la API Microsoft Cloud for Sustainability (c3163bf1-092f-436b-b260-7ade5973e5b9), seleccione MCFS SDS y, a continuación, seleccione el permiso App.Emissions.Read de la hoja Permisos de aplicación.

Este permiso de tipo de aplicación debe recibir el consentimiento del administrador seleccionando Otorgar el consentimiento del administrador para {your-tenant}.

Por último, visite la página de inicio de la API Microsoft Cloud for Sustainability, vaya a la hoja Permisos, luego seleccione + Agregar. En el panel lateral que aparece, elija Espectador como Rol en la entrada de Usuario, Grupo o Aplicación y proceda a buscar el registro de su aplicación. Seleccione Guardar.

Estoy obteniendo un token de acceso para mi aplicación, ¿cuál es la URL del recurso?

c3163bf1-092f-436b-b260-7ade5973e5b9/.default

¿Cuántos datos históricos hay disponibles?

  • Azure: los datos de uso y emisiones cubren los últimos cinco años de datos asociados con la inscripción.
  • Microsoft 365: los datos de emisiones cubren los últimos 12 meses de datos asociados con la suscripción a Microsoft 365.

Declinación de responsabilidades

La API Microsoft Cloud for Sustainability (versión preliminar) se basa en los estándares de la industria para el cálculo de carbono de los servidores y proporciona estimaciones generales para ayudar a las organizaciones a obtener información sobre las emisiones de carbono de la infraestructura de TI asociada con el uso de los servicios en la nube de Azure. Los hallazgos, interpretaciones y conclusiones presentadas con la API Microsoft Cloud for Sustainability (vista previa), incluidos los cálculos, no son consejos o recomendaciones específicas. La información y las opiniones expresadas pueden cambiar sin previo aviso. Microsoft Cloud for Sustainability API (vista previa) se proporciona tal cual, sin ninguna representación o garantía de ningún tipo, ya sea expresa o implícita, incluidas, entre otras, cualquier representación o aprobación con respecto al uso, los resultados o el rendimiento de la API Microsoft Cloud for Sustainability (versión preliminar), su idoneidad, precisión, fiabilidad o corrección. Usted asume todo el riesgo en cuanto al uso de la API de Microsoft Cloud for Sustainability (vista previa). Microsoft no asume ninguna responsabilidad por el uso de la API Microsoft Cloud for Sustainability (vista previa). En ningún caso, Microsoft será responsable de daños directos o indirectos adicionales, incluida la pérdida de ganancias, la pérdida de ahorros o cualquier daño incidental o consecuente que surja de cualquier defecto, o el uso o la incapacidad de usar la API Microsoft Cloud for Sustainability (vista previa), incluso si Microsoft ha sido advertido de la posibilidad de tales daños.

Consulte también

Ejemplos de consultas OData de la API de Microsoft Cloud for Sustainability
Método de cálculo de la API de Microsoft Cloud for Sustainability
API de Microsoft Cloud for Sustainability API