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 cambiamos de una versión de la API a otra posterior (por ejemplo, de v1.0 a v2.0), estamos indicando que la versión actual en ese momento (en este ejemplo, v1.0) comienza a estar en desuso y, 24 meses después de ese anuncio, ya no se admitirá. Puede que hagamos excepciones a esta directiva si se trata de problemas de seguridad del servicio o de fiabilidad del 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 después de que las API originales queden 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 no compatibles con versiones anteriores

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 vayan agregando funcionalidades y datos a Microsoft Graph, se incrementará el número de versión de la API para los cambios que no sean compatibles con versiones anteriores de la API.

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

  • 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 Control de versiones 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. Por tanto, no establezca dependencias 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 la API de Microsoft Graph crea que una característica de la versión beta está lista para tener disponibilidad general, agregaremos esa característica a la versión más actual. Si la promoción de la característica da como resultado un cambio importante en la versión actual, se incrementará el número de versión, y la nueva versión se convertirá 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 las solicitudes de 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 v1.0.

Estado de la versión preliminar

Una API o característica de Microsoft Graph se etiqueta como "(versión preliminar)" 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 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 de REST para el aprendizaje de simulación de ataques esté disponible en Microsoft Graph solo en el punto de conexión beta, la documentación de la API de REST se etiqueta como "(versión preliminar)". 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-*].