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 se publiquen nuevas versiones de las API REST de Microsoft Graph, se retirarán las versiones anteriores. Microsoft declara una versión en desuso con al menos 24 meses de antelación para retirarla. De forma similar, para las API individuales que alcanzaron la disponibilidad general (GA), Microsoft declara una API en desuso al menos 24 meses antes de quitarla de la versión de disponibilidad general.

En el caso de los SDK de Microsoft Graph, solo se admite y actualiza la versión principal más reciente de una biblioteca determinada con nuevas características, correcciones de errores y soluciones alternativas. La versión principal que precede a la versión más reciente se admite durante 12 meses a partir de la fecha de lanzamiento de la versión principal más reciente, solo para correcciones de seguridad. Se recomienda actualizar a la versión más reciente de los SDK siempre que sea posible.

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, actualizamos 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.

Versión actual

La versión actual de Microsoft Graph es v1.0. Estas API son accesibles en el punto de https://graph.microsoft.com/v1.0 conexión. La versión de Microsoft Graph API v1.0 contiene características que están disponibles con carácter general y están listas para su uso en producción. Para ver la documentación de la API v1.0, consulte Referencia del punto de conexión de Microsoft Graph v1.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. Algunas API se marcan como "versión preliminar" por una de las siguientes razones:

• Las API solo están disponibles en versión beta.
• El comportamiento de las API es diferente en la versión beta que en la versión 1.0

Al igual que cualquier otra API del punto de conexión beta, podemos introducir cambios importantes en las API marcadas como versión preliminar sin previo aviso. No acceda a las API desde el punto de conexión beta en las aplicaciones de producción.

Nota: Las API pueden estar en versión preliminar incluso cuando la característica o el propio producto estén disponibles con carácter general.

Versiones en desuso y no admitidas

Actualmente, ninguna versión de Microsoft Graph está en desuso o no se admite.

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-*].