Control de versiones, compatibilidad y directivas de cambios importantes en Microsoft Graph

Este artículo describe el soporte y las directivas de cambios importantes para Microsoft Graph y las versiones de la API de Microsoft Graph que están disponibles actualmente.

Información de degradación y directiva de soporte

Microsoft Graph sigue la Microsoft Lifecycle Policy.

A medida que vayan apareciendo nuevas versiones de los SDK de Microsoft Graph y de las API de REST de Microsoft Graph, se irán retirando las versiones anteriores. Microsoft declara una versión en desuso con al menos 24 meses de antelación para retirarla. De manera similar, para las API individuales que cuentan con disponibilidad general (GA), Microsoft declara una API como obsoleta al menos 24 meses antes de eliminarla de la versión GA.

Cuando incrementamos la versión principal de la API (por ejemplo, de v1.0 a v2.0), anunciamos que la versión actual (en este ejemplo, v1.0) está en desuso inmediatamente y ya no la admitiremos 24 meses después del anuncio. Es posible que hagamos alguna excepción a esta directiva por problemas de seguridad del servicio o de confiabilidad de su estado.

Una vez que se indica que la API está en desuso, se recomienda encarecidamente migrar a la versión más reciente lo antes posible. En algunos casos, anunciaremos que las nuevas aplicaciones tendrán que empezar a usar las nuevas API poco tiempo después de que las API originales estén en desuso. En estos casos, únicamente las aplicaciones activas que estén utilizando las API en desuso podrán continuar utilizándolas.

Contrato de API y cambios compatibles sin retroceso

Microsoft Graph tiene un registro de los cambios entre versiones. Estos cambios se enumeran en el Registro de cambios de Microsoft Graph. A medida que se agregan nuevas funciones y datos a Microsoft Graph, incrementamos el número de versión de la API para cualquier cambio compatible no hacia atrás en la API.

A continuación se muestran ejemplos de cambios compatibles con versiones no posteriores:

  • Cambios en la dirección URL, o en solicitudes o respuestas fundamentales asociadas a un recurso
  • Eliminación, cambio de nombre o cambio del tipo de propiedad declarada
  • Eliminación o cambio de nombre de las API o de sus parámetros
  • Adición de un encabezado de solicitud requerido

Los siguientes son ejemplos de cambios que son compatibles con versiones anteriores:

  • Adición de propiedades que admiten valores NULL o tienen un valor predeterminado
  • Adición de un miembro de una enumeración
  • Eliminación, cambio de nombre o cambio del tipo de extensión abierta
  • Eliminación, cambio de nombre o cambio del tipo de anotación
  • Introducción de paginación en las colecciones existentes
  • Cambios en los códigos de error
  • Cambios en el orden de propiedades
  • Cambios en la longitud o el formato de cadenas opacas, como identificadores de recursos

Nota: Con el tiempo, actualizaremos la lista de cambios compatibles con versiones anteriores. Si genera su propio proxy de cliente (como clientes WCF), nuestro consejo es que las aplicaciones cliente estén preparadas para recibir propiedades y tipos derivados que no estaban definidos previamente por el servicio de API de Microsoft Graph. La API de Microsoft Graph sigue las instrucciones descritas en la sección de Versiones del modelo en las directrices de la API de REST de Microsoft.

Versiones

Actualmente, existen las siguientes versiones de la API de Microsoft Graph.

Versión beta

En general, las API debutan en la versión beta y son accesibles en el punto de conexión de https://graph.microsoft.com/beta. Para consultar documentación sobre la API beta, vea Referencia del punto de conexión de Microsoft Graph beta. No se extrañe si ve cambios importantes y API que caen en desuso en la versión beta de vez en cuando. No tome una dependencia de producción en las API beta.

No ofrecemos ninguna garantía de que una característica de la versión beta se incluya en la versión actual. Cuando el equipo de Microsoft Graph API cree que una característica beta está lista para la disponibilidad general, agregamos esa característica a la versión actual más reciente. Si la promoción de la característica daría lugar a un cambio importante en la versión actual, el número de versión se incrementa y la nueva versión se convierte en la versión actual. Nuestra comunidad de desarrolladores puede publicar solicitudes de características en el foro de ideas de la Plataforma para desarrolladores de Microsoft 365, incluidas las solicitudes de nuevas características y solicitudes para promover las API beta existentes a la versión actual.

Versión actual

La versión actual de Microsoft Graph es v1.0. La versión v1.0 de la API de Microsoft Graph contiene características que están disponibles y listas para su uso en un entorno de producción, según se expone en https://graph.microsoft.com/v1.0. Examine la documentación de las API de versión 1.0.

Estado de la versión preliminar

Una API o característica de Microsoft Graph se etiqueta como "(preview)" para indicar que su comportamiento es único en el punto de conexión beta.

El comportamiento de la mayoría de las API y características de la versión v1.0 está en paridad con la versión beta. La "versión preliminar" califica a una minoría de APIs y características en uno de los dos casos siguientes:

  • Disponible solo en la versión beta
  • Disponible en versiones beta de forma diferente que en v1.0

Al igual que cualquier otra API del extremo beta, las API marcadas en la documentación como "(versión preliminar)" podrían experimentar cambios importantes sin previo aviso. No acceda a las API desde el punto de conexión beta en las aplicaciones de producción.

Por ejemplo, aprendizaje de simulación de ataques es una característica que ha estado disponible con carácter general para los administradores en el portal de Microsoft 365 Defender. Cuando la API REST para el entrenamiento de simulación de ataques está disponible en Microsoft Graph solo en el punto de conexión beta, la documentación de la API REST se etiqueta como "(preview)". La etiqueta "(versión preliminar)" se aplica a la API de REST y su documentación en Microsoft Graph, aunque el propio servicio esté disponible en general.

Versiones en desuso y no admitidas

Actualmente, no hay versiones de Microsoft Graph en desuso.

Términos de uso

El uso de las API de Microsoft Graph implica la aceptación de las Condiciones de uso de las API de Microsoft.

Su opinión es importante para nosotros. Conecte con nosotros en Microsoft Q&A. Etiquete sus preguntas con [microsoft-graph-*].