Control de versiones | Conceptos de Graph API
Se aplica a: Graph API | Azure Active Directory (AD)
En este tema se resumen las diferencias de versión de las operaciones y las entidades de la API de Azure Active Directory (AD) Graph. Debe especificar la versión de una operación que desea usar incluyendo el parámetro de cadena de consulta api-version en su solicitud. Se rechazarán las solicitudes sin un parámetro api-version y devolverán una respuesta (400) Solicitud incorrecta. Si las llamadas al servicio una versión anterior de una operación, puede elegir seguir llamando a la versión anterior, o modifique el código para llamar a una versión más reciente. Las diferencias de funcionalidad entre versiones se describen en la documentación de la entidad en la que está realizando la llamada.
Importante
Se recomienda encarecidamente que use Microsoft Graph en lugar de la API de Azure AD Graph para acceder a recursos de Azure Active Directory. Nuestros esfuerzos de desarrollo se concentran ahora en Microsoft Graph y no están previstas mejoras adicionales para la API de Azure AD Graph. Hay un número muy limitado de escenarios para los que la API de Azure AD Graph todavía podría ser adecuada; para más información, vea la entrada del blog Microsoft Graph o Azure AD Graph en el centro de desarrollo de Office.
A partir de la API de Azure AD Graph versión 1.5, el valor del parámetro api-version se especifica como un valor numérico para las versiones de disponibilidad general (GA). La siguiente URL muestra cómo consultar los recursos de nivel superior del dominio de inquilino contoso.com con Graph API versión 1.5: https://graph.windows.net/contoso.com?api-version=1.5. Para las versiones anteriores de Graph API, el valor del parámetro api-version se especifica como una cadena de fecha con el formato siguiente: AAAA-MM-DD. La siguiente dirección URL muestra cómo consultar los recursos del inquilino de nivel superior del mismo inquilino usando la versión 2013-11-08 de Graph API: https://graph.windows.net/contoso.com?api-version=2013-11-08. Para las características de versión preliminar, el valor del parámetro api-version se especifica mediante la cadena "beta", de la siguiente forma: https://graph.windows.net/contoso.com?api-version=beta.
Contrato de API, control de versiones y cambios importantes
Aumentaremos el número de versión de API para todos los cambios importantes en la API, con el fin de proteger las aplicaciones cliente. También podemos optar por incrementar la versión de API en caso de cambios no importantes (por ejemplo, si se agregan algunas capacidades nuevas significativamente grandes).
Por lo tanto, ¿qué es un "cambio importante"?
- Quitar algunas API o algunos de sus parámetros o bien cambiarles el nombre
- Cambios en el comportamiento de una API existente
- Cambios en los códigos de error y contratos de errores
- Todo lo que infrinja el "principio de la mínima sorpresa"
Nota: La adición de nuevos campos JSON a las respuestas no constituye un cambio importante. Para los programadores que generan sus propios servidores proxy de cliente (por ejemplo, los clientes de WCF), nuestro consejo es que las aplicaciones cliente deben estar preparadas para recibir las propiedades y los tipos derivados no previamente definidos por el servicio de Graph API. Aunque Graph API no es compatible todavía con OData V4 en el momento de redactar este artículo, sigue las instrucciones que se describen en la sección sobre el control de versiones en las especificaciones de OData V4 .
Cuando aumentamos la versión principal de la API (por ejemplo, de la 1.5 a la 2.0), dejamos claro que todo el soporte para los clientes existentes que usan la versión 1.x o las anteriores quedará obsoleto y dejarán de recibir soporte 12 meses después. Consulte la directiva de ciclo de vida de soporte de Microsoft Online Services para más detalles.
Versiones compatibles
Se han publicado las versiones siguientes de Graph API.
Versión beta
Las características de Graph API actualmente en versión preliminar pueden encontrarse en la sección de características de versión preliminar de los conceptos de Graph API o en el blog del equipo de Graph. Las características beta requieren el parámetro de cadena de consulta "api-version=beta". Cuando el equipo de Graph API considere que una característica de vista previa está lista para la disponibilidad general (GA), agregará dicha característica a la última versión de GA (o si constituye un cambio importante, lanzará un nuevo número de versión incrementado). No garantizamos que todas las características de vista previa vayan a pasar a la versión de GA.
En la versión beta, intentamos evitar los cambios importantes en la medida de lo posible, pero no lo garantizamos. En las aplicaciones de cliente que usan la versión beta sí se pueden producir cambios importantes de vez en cuando. Consulte Términos de uso complementarios de las Vistas Previas de Microsoft Azure.
Versión 1.6
En esta sección se enumeran los cambios de Graph API versión 1.6.
Graph API versión 1.6 introduce los siguientes cambios de características:
Compatibilidad agregada con usuarios de la cuenta local de Azure Active Directory B2C. Esto implica nuevas propiedades en la entidad User y un nuevo tipo complejo SignInName para admitir el inicio de sesión en una cuenta local en los inquilinos de Azure Active Directory B2C. Para más información sobre Azure Active Directory B2C, consulte la documentación de Azure Active Directory B2C.
Compatibilidad agregada con la detección de servicios con la entidad ServiceEndpoint y la propiedad de navegación serviceEndpoints en las entidades Application y ServicePrincipal.
Compatibilidad agregada con el comportamiento personalizado de aplicaciones que se puede invocar al consumir servicios con los tipos AddIn y KeyValue y la propiedad addIns en las entidades Application y ServicePrincipal.
Compatibilidad agregada con la autenticación sin contraseña con la entidad TrustedCAsForPasswordlessAuth, el tipo CertificateAuthorityInformation y la propiedad trustedCAsForPasswordlessAuth en la entidad TenantDetail.
Se ha agregado la acción changePassword, que se puede llamar para permitir al usuario con sesión iniciada cambiar su contraseña.
El cliente de Graph versiones 2.1.x requiere Graph API versión 1.6; el cliente de Graph versiones 2.0.x requiere Graph API 1.5.
Cambios de entidades
| Entidad | Descripción del cambio |
|---|---|
| Application | Se ha agregado la propiedad addIns, que define el comportamiento personalizado que puede usar un servicio de personalización para llamar a una aplicación en contextos específicos. Se ha agregado la propiedad de navegación serviceEndpoints, que contiene la colección de puntos de conexión de servicio que están disponibles para detección. |
| LicenseDetail | Nueva entidad que contiene los detalles de licencia de un usuario. |
| ServiceEndpoint | Nueva entidad que contiene la información de detección del servicio. |
| ServicePrincipal | Se ha agregado la propiedad addIns, que define el comportamiento personalizado que puede usar un servicio de personalización para llamar a una aplicación en contextos específicos. Se ha agregado la propiedad de navegación serviceEndpoints, que contiene la colección de puntos de conexión de servicio que están disponibles para detección. |
| SubscribedSku | Se ha agregado la propiedad appliesTo. |
| TenantDetail | Se ha agregado la propiedad trustedCAsForPasswordlessAuth, que contiene el conjunto de entidades de certificación usadas para validar la cadena de confianza mientras se realiza la autenticación sin contraseña. |
| TrustedCAsForPasswordlessAuth | Nueva entidad que representa un conjunto de entidades de certificación para validar la cadena de confianza mientras se realiza la autenticación sin contraseña. |
| User | Se ha agregado la propiedad creationType, que se utiliza para indicar que el usuario es una cuenta local. Se ha agregado la propiedad signInNames, que contiene la colección de nombres de inicio de sesión utilizados por un usuario de la cuenta local para iniciar sesión en un inquilino de Azure Active Directory B2C. El nombre de esta propiedad, alternativeSignInNamesInfo, cambia en la versión beta. Se ha agregado la propiedad de navegación licenseDetails. |
Cambios de tipo complejo
| Tipo | Descripción del cambio |
|---|---|
| AddIn | Nuevo tipo usado para definir el comportamiento personalizado que puede utilizar un servicio de consumo para llamar a una aplicación en contextos concretos. |
| CertificateAuthorityInformation | Nuevo tipo que representa una entidad de certificación que se utiliza al validar la cadena de confianza cuando se realiza la autenticación sin contraseña. |
| KeyValue | Nuevo tipo que contiene un par clave-valor que define un parámetro que puede usar un servicio de consumo, o al que puede llamar, en una aplicación especificada en AddIn. |
| ServicePlanInfo | Se ha agregado la propiedad appliesTo. Se ha agregado la propiedad provisioningStatus. |
| SignInName | Nuevo tipo para almacenar información sobre un nombre de inicio de sesión que puede utilizar un usuario de una cuenta local para iniciar sesión en un inquilino de Azure Active Directory B2C. Este tipo ya no se llama LogonIdentifier en la versión beta. |
Cambios de función y acción
| Función | Descripción del cambio |
|---|---|
| changePassword | Nueva acción que se puede llamar para permitir al usuario con sesión iniciada cambiar su contraseña. |
Versión 1.5
En esta sección se enumeran los cambios de Graph API versión 1.5.
Graph API versión 1.5 introduce los siguientes cambios de características:
El espacio de nombres del esquema de Graph API ha cambiado de Microsoft.WindowsAzure.ActiveDirectory a Microsoft.DirectoryServices. Esto afecta a todas las entidades y tipos complejos expuestos por Graph API.
Se ha agregado compatibilidad con las extensiones de esquema de directorio. Esto permite agregar propiedades requeridas por la aplicación a los objetos de directorio. Las siguientes entidades admiten extensiones de esquema: User, Group, TenantDetail, Device, Application y ServicePrincipal. Para permitir las extensiones de esquema, se ha agregado la entidad ExtensionProperty, se ha agregado la propiedad de navegación extensionProperties a la entidad Application y se ha agregado una nueva función, getAvailableExtensionProperties, para devolver las propiedades de extensiones registradas de objetos de directorio admitidos. Para más información sobre cómo extender el esquema de directorio, consulte las extensiones de esquema de directorio.
La manera en que se representan los permisos ha cambiado y está más estrechamente alineada con los conceptos de OAuth 2.0, así como con la manera en que se representa los permisos en otros componentes de Azure. Se ha eliminado la entidad Permission y se ha sustituido por la entidad OAuth2PermissionGrant. Esta entidad representa ámbitos de permisos de OAuth 2.0 delegados que llegan a una notificación de ámbito de token de acceso de OAuth 2.0. Además, la nueva entidad AppRoleAssignment representa los roles de aplicación que se pueden asignar a los usuarios, los grupos y las entidades de servicio. También se han agregado dos tipos complejos relacionados: AppRole y OAuth2Permission. Este cambio ha provocado el cambio del nombre de algunas propiedades y la adición de otras en las siguientes entidades: Application, Group, ServicePrincipal y User.
El nombre de la entidad Role ha cambiado a DirectoryRole.
El nombre de la entidad RoleTemplate ha cambiado a DirectoryRoleTemplate.
En las tablas siguientes se muestran las entidades, los tipos complejos y las funciones que se han agregado, cambiado o quitado para esta versión.
Cambios de entidades
| Entidad | Descripción del cambio |
|---|---|
| Application | Se ha actualizado la propiedad appId de Edm.Guid a Edm.String. Se ha agregado la propiedad appRoles, que contiene la colección de roles de aplicación que una aplicación puede declarar. Estos roles se pueden asignar a usuarios, grupos o entidades de servicio. Se ha agregado la propiedad groupMembershipClaims, que es una máscara de bits que configura la notificación "grupos" emitida en un usuario o un token de acceso de OAuth 2.0 que la aplicación espera. Los valores de máscara de bits son: 0: ninguno, 1: grupos de seguridad y roles de Azure AD, 2: reservado y 4: reservado. Al establecer la máscara de bits en 7 se obtendrán todos los grupos de seguridad, los grupos de distribución y los roles de Azure AD de los que es miembro el usuario que inició sesión. Se ha agregado la propiedad knownClientApplications, que contiene una lista de las aplicaciones cliente que están vinculadas a esta aplicación de recursos. El consentimiento de cualquiera de las aplicaciones cliente conocidas provocará el consentimiento implícito de la aplicación de recursos a través de un diálogo de consentimiento combinado (en el que se muestran los ámbitos de permisos OAuth requeridos por el cliente y el recurso). Se ha agregado la propiedad oauth2AllowImplicitFlow, que especifica si esta aplicación web puede solicitar tokens de flujo implícitos de OAuth2.0. El valor predeterminado es false. Se ha agregado la propiedad oauth2AllowUrlPathMatching, que especifica si, como parte de las solicitudes de token de OAuth 2.0, Azure AD permitirá la coincidencia de ruta del URI de redirección con las URL de respuesta de la aplicación. El valor predeterminado es false. Se ha agregado la propiedad oauth2Permissions, que contiene la colección de ámbitos de permiso de OAuth 2.0 que la aplicación de API web (recurso) expone a las aplicaciones cliente. Estos ámbitos de permisos pueden concederse a las aplicaciones cliente durante el consentimiento. Se ha agregado la propiedad oauth2RequiredPostResponse, que especifica si, como parte de las solicitudes de token de OAuth 2.0, Azure AD permitirá solicitudes POST en lugar de solicitudes GET. El valor predeterminado es false, que especifica que solo se permitirán solicitudes GET. Se ha agregado la propiedad requiredResourceAccess, que especifica los recursos a los que esta aplicación necesita acceso y el conjunto de ámbitos de permisos de OAuth y roles de aplicación que necesita en cada uno de esos recursos. Esta configuración previa de acceso a los recursos necesarios impulsa la experiencia de consentimiento del usuario final. Se ha agregado la propiedad de navegación extensionProperties, que contiene las propiedades de extensión asociadas a la aplicación. |
| AppRoleAssignment | Nueva entidad que se usa para registrar cuándo un usuario o grupo está asignado a una aplicación. En este caso, tendrá como resultado una ventana de aplicación visible arriba en el panel de acceso de la aplicación del usuario. Esta entidad también puede utilizarse para conceder acceso a otra aplicación (modelada como entidad de servicio) a una aplicación de recursos de un rol determinado. |
| Contacto | Se ha agregado la propiedad sipProxyAddress, que especifica la dirección del protocolo de inicio de sesión (SIP) de la voz sobre IP (VOIP) para el contacto. |
| DirectoryObject | Se ha agregado la propiedad deletionTimestamp, que indica la hora a la que se eliminó un objeto de directorio. Solo se aplica a los objetos de directorio que se pueden restaurar. Actualmente solo se admite para Application. |
| DirectoryRole | Se ha cambiado el nombre de Role. Se ha agregado la propiedad roleTemplateId. |
| DirectoryRoleTemplate | Ha cambiado el nombre de RoleTemplate. |
| ExtensionProperty | Nueva entidad que permite que una aplicación defina y use un conjunto de propiedades adicionales que se pueden agregar a objetos de directorio (usuarios, grupos, detalles de inquilino, dispositivos, aplicaciones y entidades de servicio) sin que la aplicación requiera un almacén de datos externo. |
| Group | Se ha agregado la propiedad onPremisesSecurityIdentifier, que contiene el identificador de seguridad local (SID) para el grupo que se sincronizó desde el entorno local con la nube. Se ha agregado la propiedad de navegación appRoleAssignments, que señala al conjunto de aplicaciones (entidades de servicio) al que está asignado este grupo. |
| OAuth2PermissionGrant | Nueva entidad que especifica un ámbito de permisos delegados de OAuth2.0. El ámbito de permisos delegados de OAuth especificado pueden solicitarlo las aplicaciones cliente (a través de la colección requiredResourceAccess) que llaman a esta aplicación de recursos. Reemplaza la entidad Permission que se eliminó de esta versión. |
| Permiso | Ha cambiado el nombre a OAuth2PermissionGrant. |
| Rol | Ha cambiado el nombre a DirectoryRole. |
| RoleTemplate | Ha cambiado el nombre a DirectoryRoleTemplate. |
| ServicePrincipal | Se ha agregado la propiedad appDisplayName, que especifica el nombre para mostrar expuesto por la aplicación asociada. Se ha agregado la propiedad appRoleAssignmentRequired, que especifica si se requiere un objeto AppRoleAssignment para un usuario o grupo antes de que Azure AD pueda emitir un token de usuario o de acceso a la aplicación. Se ha agregado la propiedad appRoles, que contiene los roles de aplicación expuestos por la aplicación asociada. Para obtener más información, consulte la definición de la propiedad appRoles en la entidad Application. Se ha agregado la propiedad oauth2Permissions, que contiene los permisos de OAuth 2.0 expuestos por la aplicación asociada. Para obtener más información, consulte la definición de la propiedad oauth2Permisions en la entidad Application. Se ha agregado la propiedad preferredTokenSigningKeyThumbprint. Reservado solo para uso interno. No escriba ni dependa de otra manera de esta propiedad. Puede quitarse en versiones futuras. Se ha agregado la propiedad de navegación appRoleAssignedTo, que señala al conjunto de aplicaciones al que está asignada la entidad de servicio. Se ha agregado la propiedad de navegación appRoleAssignments, que señala al conjunto de entidades de servicio (usuarios, grupos y entidades de servicio) asignadas a esta entidad de servicio. Se ha agregado la propiedad de navegación oauth2PermissionGrants, que señala al conjunto de concesiones de suplantación de usuario asociadas a esta entidad de servicio. Se ha quitado la propiedad de navegación permissions |
| TenantDetail | Se ha quitado la propiedad tenantType. |
| User | Se ha agregado la propiedad onPremisesSecurityIdentifier, que contiene el identificador de seguridad local (SID) para el usuario que se sincronizó desde el entono local en la nube. Se ha agregado la propiedad sipProxyAddress, que especifica la dirección del protocolo de inicio de sesión (SIP) de la voz sobre IP (VOIP) para el usuario. Se ha agregado la propiedad de navegación appRoleAssignments, que señala al conjunto de aplicaciones (entidades de servicio) al que está asignado este usuario. Se ha agregado la propiedad de navegación oauth2PermissionGrants, que señala al conjunto de concesiones de suplantación de usuario de OAuth 2.0 asociadas a este usuario. Se ha quitado la propiedad de navegación permissions. |
Cambios de tipo complejo
| Tipo | Descripción del cambio |
|---|---|
| AppRole | Nuevo tipo que especifica los roles de aplicación que se pueden solicitar por aplicaciones de cliente que llaman a esta aplicación o que se pueden usar para asignar la aplicación a usuarios o grupos en uno de los roles de aplicación especificados. |
| OAuth2Permission | Nuevo tipo que representa un ámbito de permisos de OAuth 2.0. El ámbito de permisos delegados de OAuth 2.0 especificado pueden solicitarlo las aplicaciones cliente (a través de la colección requiredResourceAccess) que llaman a esta aplicación de recursos. |
| RequiredResourceAccess | Nuevo tipo que especifica el conjunto de ámbitos de permiso de OAuth 2.0 y roles de aplicación en el recurso especificado al que una aplicación requiere acceso. |
| ResourceAccess | Nuevo tipo que representa un permiso que esta aplicación requiere. |
Cambios de función y acción
| Función | Descripción del cambio |
|---|---|
| getAvailableExtensionProperties | Nueva función que devuelve la lista completa de propiedades de extensión que se han registrado en un directorio. Se pueden registrar propiedades de extensión para las siguientes entidades: User, Group, Device, TenantDetail, Application y ServicePrincipal. |
| getMemberObjects | Nueva función que devuelve todos los objetos Group y DirectoryRole de los que un usuario, contacto, grupo o entidad de servicio sea miembro de manera transitiva. |
| getObjectsByObjectIds | Nueva función que devuelve los objetos de directorio especificados en una lista de identificadores de objeto. También puede especificar las colecciones de recursos (usuarios, grupos, etc.) en las que se debe buscar si especifica el parámetro opcional types. |
| restaurar | Nueva acción de servicio que permite la restauración de una aplicación eliminada. |
Versión 2013-11-08
En esta sección se enumeran los cambios de Graph API versión 2013-11-08.
En las tablas siguientes se muestran las entidades, los tipos complejos y las funciones que se han agregado, cambiado o quitado para esta versión.
Cambios de entidades
| Entidad | Descripción del cambio |
|---|---|
| Application | Se ha agregado la propiedad de navegación owners, que señala al conjunto de objetos de directorio que son propietarios de la aplicación. Los propietarios son un conjunto de usuarios no administrativos que tienen permiso para modificar este objeto. Se hereda de DirectoryObject. |
| DeviceConfiguration | Nueva entidad que representa la configuración de un dispositivo. |
| DirectoryObject | Se ha agregado la propiedad de navegación createdOnBehalfOf, que señala al objeto de directorio en nombre del cual se creó este objeto. Se ha agregado la propiedad de navegación createdObjects, que señala al conjunto de objetos de directorio creados por el objeto actual. Se ha agregado la propiedad de navegación owners, que señala al conjunto de objetos de directorio que son propietarios del objeto actual. Los propietarios son un conjunto de usuarios no administrativos que tienen permiso para modificar este objeto. Se ha agregado la propiedad de navegación ownedObjects, que señala al conjunto de objetos de directorio que son propiedad del objeto actual. Importante: Las entidades que se derivan de DirectoryObject heredan sus propiedades y pueden heredar sus propiedades de navegación. |
| Group | Se ha agregado la propiedad de navegación owners, que señala al conjunto de objetos de directorio que son propietarios del grupo. Los propietarios son un conjunto de usuarios no administrativos que tienen permiso para modificar este objeto. Se hereda de DirectoryObject. |
| Rol | Se ha agregado la propiedad de navegación ownedObjects, que señala al conjunto de objetos de directorio que son propiedad del rol. Se hereda de DirectoryObject. El nombre de la entidad Role ha cambiado a DirectoryRole a partir de la versión 1.5. Para obtener más información sobre Role, consulte DirectoryRole. |
| ServicePrincipal | Se ha agregado la propiedad appOwnerTenantID. Se ha agregado la propiedad autheniticationPolicy. Reservado solo para uso interno. No lo use. Quitado en la versión 1.5. Se ha agregado la propiedad de navegación createdObjects, que señala al conjunto de objetos de directorio creados por la entidad de servicio. Se hereda de DirectoryObject. Se ha agregado la propiedad de navegación owners, que señala al conjunto de objetos de directorio que son propietarios de la entidad de servicio. Los propietarios son un conjunto de usuarios no administrativos que tienen permiso para modificar este objeto. Se hereda de DirectoryObject. Se ha agregado la propiedad de navegación ownedObjects, que señala al conjunto de objetos de directorio que son propiedad de la entidad de servicio. Se hereda de DirectoryObject. |
| User | Se ha agregado la propiedad immutableId, que asocia una cuenta de usuario de Active Directory local a su objeto de usuario de Azure AD. Esta propiedad se debe especificar al crear una nueva cuenta de usuario en Graph si se usa un dominio federado para la propiedad userPrincipalName (UPN) del usuario. Se ha agregado la propiedad userType, que es un valor de cadena que se puede usar para clasificar tipos de usuario en el directorio, como "Member" y "Guest". Se ha agregado la propiedad de navegación createdObjects, que señala al conjunto de objetos de directorio creados por el usuario. Se hereda de DirectoryObject. Se ha agregado la propiedad de navegación ownedObjects, que señala al conjunto de objetos de directorio que son propiedad del usuario. Se hereda de DirectoryObject. |
Cambios de tipo complejo
| Tipo | Descripción del cambio |
|---|---|
| ServicePrincipalAuthenticationPolicy | Reservado solo para uso interno. No lo use. Quitado en la versión 1.5. |
Cambios de función y acción
| Función | Descripción del cambio |
|---|---|
| assignLicense | Nueva acción de servicio que actualiza un usuario con una lista de licencias para agregar o quitar. |
Versión 2013-04-05
Se trata de la versión base de Graph API.