Table of contents

Informes y eventos (versión preliminar) | Conceptos de API Graph

Bryan Lamos|Última actualización: 05/10/2016
|
1 Colaborador

Se aplica a: API Graph | Azure Active Directory (AD)

Información general y requisitos previos

La vista previa de la API de REST de informes y eventos de Azure AD proporciona acceso de solo lectura a los datos de informes de acceso y uso que se mantienen dentro de un inquilino de Azure AD. Consulte el artículo Visualización de los informes de acceso y uso para obtener información general de los tipos de informe disponibles e información sobre el acceso a la característica de informes en la interfaz de usuario del Portal de administración de Azure relacionada.

Importante

La funcionalidad de la API de Azure AD Graph también se encuentra disponible a través de Microsoft Graph, una API unificada que también incluye las API de otros servicios Microsoft como Outlook, OneDrive, OneNote, Planner y Office Graph, todos ellos accesibles a través de un solo punto de conexión con un solo token de acceso. Tenga en cuenta que los informes y eventos no se admiten actualmente en Microsoft Graph; debe utilizar la API de Azure AD Graph para estas características.

También se necesita estar familiarizado con la configuración de autenticación y de aplicación de Azure AD para usar la vista previa de la API de REST de informes y eventos. Si no está familiarizado con los conceptos asociados a la autenticación de Azure AD o la posibilidad de conceder permisos a una aplicación para permitir el acceso al inquilino, revise el artículo Escenarios de autenticación para Azure AD, en concreto, la sección titulada Conceptos básicos sobre el registro de una aplicación en Azure AD. La última sección también incluye vínculos a un artículo más detallado, Integración de aplicaciones con Azure Active Directory, como los permisos específicos para el acceso a la API Graph API, una vez que está preparado para configurar el acceso en su aplicación.

Por último, necesitará acceso a un inquilino de Azure AD cuando esté listo para configurar el acceso para la aplicación. Encontrará una aplicación complementaria de ejemplo de ASP.NET denominada WebApp-GraphAPI-Reporting en Github con instrucciones paso a paso en readme.md, así como información general de todos los ejemplos que ilustran el uso de la biblioteca de autenticación de Active Directory (ADAL) y la API Graph desde varias plataformas en la página principal de Ejemplos de código de Azure AD.

Direccionamiento

Cuando tenga el inquilino configurado y esté listo para acceder a la API de informes y eventos, consulte el artículo Guía de inicio rápido de la API Graph de Azure AD para más información sobre los conceptos básicos de creación de la dirección URL de un servicio, el encabezado de solicitud HTTP y el token de acceso OData relacionado, así como información sobre el uso de herramientas de pruebas (es decir, Explorador de gráficos, Fiddler) para ejecutar solicitudes de prueba en el inquilino.

Recuerde que todas las operaciones de informes y eventos se direccionan con el siguiente formato de dirección URL compatible con OData, donde tenant-name es el nombre del inquilino de Azure AD y reports/<service-operation> es la ruta de acceso al recurso de informe específico que desea llamar: https://graph.windows.net/<tenant-name>/reports/<service-operation>?api-version=beta.

Además, la API de informes y eventos admite un subconjunto de las opciones de consulta de OData admitidas por la API Graph principal (consulte la sección siguiente).

Opciones de consulta admitidas

$filter

A las expresiones de filtro se les aplican las restricciones siguientes:

  • Todos los informes se refieren de forma predeterminada a los 30 días anteriores del historial.

  • No todas las propiedades de las entidades admitidas se pueden usar en una expresión de filtro. Para obtener más información, consulte a continuación los detalles de la propiedad para cada una de las entidades de informes y eventos de este tema.

  • Operadores lógicos: se admiten y. Por ejemplo: https://graph.windows.net/<tenant-name>/reports/accountProvisioningEvents?api-version=beta&$filter=(eventTime gt 2014-03-01 and eventTime lt 2015-04-23) or eventTime lt 2015-02-01

  • Operadores de comparación: se admiten eq (igual que), gt (mayor que), ge (mayor o igual que), lt (menos que) y le (menor o igual que).

  • startswith: no se admite.

  • any: no se admite.

  • Operadores aritméticos: no se admiten.

  • Funciones: no son compatibles.

  • No se admiten valores null como operando en expresiones de filtro.

Nota: Los espacios de la cadena de consulta deben codificarse para URL antes de enviar una solicitud. Por ejemplo, la siguiente cadena de consulta, https://graph.windows.net/<tenant-name>/reports/accountProvisioningEvents?api-version=beta&$filter=eventTime gt 2014-03-01 and eventTime lt 2015-04-23, debe codificarse para URL como: https://graph.windows.net/<tenant-name>/reports/accountProvisioningEvents?api-version=beta&$filter=eventTime%20gt%202014-03-01%20and%20eventTime%20lt%202015-04-23.

Solicitudes de ejemplo con la opción de consulta $filter:

SolicitudDescripción
https://graph.windows.net/<tenant-name>/reports/accountProvisioningEvents?api-version=beta&$filter=eventTime%20eq%202015-03-12T22:01:18.4385955ZDevuelve una lista de los eventos del informe de aprovisionamiento de cuentas que se han producido en una fecha y hora específicas.
https://graph.windows.net/<tenant-name>/reports/accountProvisioningEvents?api-version=beta&$filter=eventTime%20gt%202014-03-01%20and%20eventTime%20lt%202015-04-23Devuelve una lista de los eventos del informe de aprovisionamiento de cuentas que se han producido dentro del rango especificado.

$top

$top devuelve un subconjunto de las entradas del informe especificado, que consta de las primeras N entradas, donde N es un entero positivo. Solicitudes de ejemplo con la opción de consulta $top:

SolicitudDescripción
https://graph.windows.net/<tenant-name>/reports/accountProvisioningEvents?api-version=beta&$top=5Devuelve los 5 eventos del informe de aprovisionamiento de cuentas más recientes.

$skip

$skip devuelve un subconjunto de las entradas del informe especificado, donde el subconjunto se define buscando N entradas en la colección de informes y seleccionando solo las entradas restantes (comenzando por la entrada N+1). Solicitudes de ejemplo con la opción de consulta $skip:

SolicitudDescripción
https://graph.windows.net/<tenant-name>/reports/accountProvisioningEvents?api-version=beta&$skip=17Devuelve las entradas restantes de la colección de eventos del informe de auditoría de cuentas, comenzando por la entrada 18.

Operaciones, propiedades, entidades y metadatos del servicio

Todas las entidades y propiedades admitidas por los recursos OData de informes y eventos se especifican en su documento de metadatos de servicio, que define el Entity Data Model (EDM) del servicio mediante el lenguaje de definición de esquema común (CSDL) de OData. Puede recuperar los metadatos CSDL agregando el segmento $metadata a la ruta de acceso a recursos /reports en la dirección URL: https://graph.windows.net/<tenant-name>/reports/$metadata?api-version=beta. La exclusión del segmento $metadata devolverá una lista de los recursos de informe disponibles como datos JSON en el cuerpo de la respuesta. Las operaciones de servicio de OData que se pueden usar en la ruta de acceso a recursos para acceder a las colecciones de datos de evento se definen mediante el atributo "Name" de los elementos &ltEntitySet&gt al final del CSDL. Por ejemplo, para acceder a la colección de datos de eventos asociada al informe “aprovisionamiento de cuentas”, usaría una URL como la siguiente: https://graph.windows.net/<tenant-name>/reports/accountProvisioningEvents?api-version=beta.

Nota: El espacio de nombres que define las entidades de OData que admite la API de informes y eventos es Microsoft.ActiveDirectory.DataService.PublicApi.Model.Reporting, que es diferente del que define las entidades de la API Graph principal, que es Microsoft.DirectoryServices. Además, la API de informes y eventos difiere de la API Graph principal en los siguientes aspectos importantes:

  • Las entidades no se derivan de un tipo base ni admiten propiedades de navegación
  • El servicio no admite funciones adicionales ni tipos complejos
  • El servicio solo admite operaciones HTTP READ

En este tema se ofrecen detalles adicionales sobre las colecciones ofrecidas por cada entidad y sus propiedades asociadas, que solo se admiten en operaciones de lectura (HTTP GET). Consulte el artículo Visualización de los informes de acceso y uso para más información sobre cada uno.

AllUsersWithAnomalousSignInActivityEvent

NombreTipoRead(GET)Descripción
eventTimeEdm.DateTimeOffsetFiltrableFecha y hora en que se detectó la actividad irregular.
detailEdm.StringDetalles de la actividad.
reasonEdm.StringActividad anómala que provocó que el usuario esté en el informe.
idEdm.GuidIdentificador único del evento.
displayNameEdm.StringNombre para mostrar del usuario.
userNameEdm.StringNombre del usuario.

AccountProvisioningEvent

NombreTipoRead(GET)Descripción
idEdm.StringIdentificador único del evento.
eventTimeEdm.DateTimeOffsetFiltrableFecha y hora en que se produjo el evento.
aplicaciónEdm.StringNombre de la aplicación que provocó el evento de aprovisionamiento.
instanceNameEdm.StringNombre de la instancia de aplicación que provocó el evento de aprovisionamiento.
operaciónEdm.StringNombre de la operación.
sourceTypeEdm.StringTipo del origen de la actividad.
targetTypeEdm.StringTipo del destino de la actividad.
joiningPropertyEdm.StringPropiedad usada para combinar.
addedPropertiesEdm.StringNombres de las propiedades que se agregaron.
removedPropertiesEdm.StringNombres de las propiedades que se quitaron.
resultEdm.StringResultado de la operación.

ApplicationUsageSummaryEvent

Importante

La funcionalidad de informes de actividad de inicio de sesión está disponible a través de la API de informes de actividad de inicio de sesión de Azure Active Directory.

NombreTipoRead(GET)Descripción
idEdm.StringIdentificador único del evento.
eventTimeEdm.DateTimeOffsetFiltrableFecha y hora en que se produjo el evento.
applicationNameEdm.StringEl nombre para mostrar de la aplicación con la actividad de inicio de sesión.
uniqueUsersEdm.Int32El número de usuarios únicos que han iniciado sesión en la aplicación.
signInsEdm.Int32El número de inicios de sesión en la aplicación.

AuditEvent

Importante

Use la API de auditoría a la que se hace referencia en este artículo.

NombreTipoRead(GET)Descripción
idEdm.StringIdentificador único del evento.
eventTimeEdm.DateTimeOffsetFiltrableFecha y hora en que se produjo el evento.
actorEdm.StringNombre principal de usuario (UPN) del usuario actor.
actionEdm.StringAcción concreta realizada por el actor. Para más información sobre los valores de acción posibles, consulte el artículo Eventos del informe de auditoría de Azure Active Directory.
targetEdm.StringNombre principal de usuario (UPN) del usuario de destino.
actorDetailEdm.StringDetalles adicionales de la propiedad para el usuario actor, incluidos, entre otros, el UPN y el PUID.
targetDetailEdm.StringDetalles adicionales de la propiedad para el usuario de destino, incluidos el UPN y el PUID.
updatedPropertiesEdm.StringPropiedades que se actualizaron en un evento de actualización, tal como se indica en la propiedad action.

CompromisedCredentialsEvent

NombreTipoRead(GET)Descripción
eventTimeEdm.DateTimeOffsetFiltrableFecha y hora en que se produjo el evento.
credentialTypeEdm.StringEl tipo de credencial.
reasonEdm.StringEl motivo de por qué se marcó la cuenta como en peligro.
idEdm.GuidIdentificador único del usuario.
displayNameEdm.StringNombre para mostrar del usuario.
userNameEdm.StringNombre del usuario.

IrregularSignInActivityEvent

NombreTipoRead(GET)Descripción
eventTimeEdm.DateTimeOffsetFiltrableFecha y hora en que se detectó la actividad irregular.
ipAddressEdm.StringDirección IP del inicio de sesión.
eventClassificationEdm.StringSi el inicio de sesión se clasifica como irregular o sospechoso.
dispositivoEdm.StringInformación sobre el dispositivo en que el usuario inició sesión.
reasonEdm.StringMotivo por el que el inicio de sesión se marcó como sospechoso.
ubicaciónEdm.StringUbicación geográfica aproximada del inicio de sesión.
idEdm.GuidIdentificador único del evento.
displayNameEdm.StringNombre para mostrar del usuario.
userNameEdm.StringNombre del usuario.

MimSsgmGroupActivityEvent

NombreTipoRead(GET)Descripción
idEdm.StringIdentificador único del evento.
eventTimeEdm.DateTimeOffsetFiltrableFecha y hora en que se produjo el evento.
groupEdm.StringEl grupo en el que se realizó la acción de autoservicio.
actionEdm.StringLa acción del grupo de autoservicio realizada.

MimSsprActivityEvent

NombreTipoRead(GET)Descripción
eventTimeEdm.DateTimeOffsetFiltrableFecha y hora en que se produjo el evento.
rolEdm.StringLa función del usuario.
methodsUsedEdm.StringEl método utilizado para restablecer la contraseña del usuario.
resultEdm.StringEl resultado del intento del usuario de restablecer su contraseña.
detallesEdm.StringDetalles adicionales sobre el intento del usuario de restablecer su contraseña.
idEdm.StringIdentificador único del evento.
displayNameEdm.StringNombre para mostrar del usuario.
userNameEdm.StringNombre del usuario.

MimSsprRegistrationActivityEvent

NombreTipoRead(GET)Descripción
eventTimeEdm.DateTimeOffsetFiltrableFecha y hora en que se produjo el evento.
rolEdm.StringLa función del usuario.
registrationActivityEdm.StringLa actividad de registro realizada por el usuario.
idEdm.StringIdentificador único del evento.
displayNameEdm.StringNombre para mostrar del usuario.
userNameEdm.StringNombre del usuario.

SignInsAfterMultipleFailuresEvent

NombreTipoRead(GET)Descripción
firstSuccessfulSignInEdm.DateTimeOffsetFiltrableFecha y hora del primer inicio de sesión correcto después de varios intentos.
failedAttemptsToSignInEdm.Int32Número de inicios de sesión con error antes del inicio de sesión correcto.
idEdm.GuidIdentificador único del evento.
displayNameEdm.StringNombre para mostrar del usuario.
userNameEdm.StringNombre del usuario.

SignInsFromIPAddressesWithSuspiciousActivityEvent

NombreTipoRead(GET)Descripción
eventTimeEdm.DateTimeOffsetFiltrableÚltima fecha y hora en que se produjo este tipo de evento.
ipAddressEdm.StringDirección IP del inicio de sesión.
idEdm.GuidIdentificador único del evento.
displayNameEdm.StringNombre para mostrar del usuario.
userNameEdm.StringNombre del usuario.

SignInsFromMultipleGeographiesEvent

NombreTipoRead(GET)Descripción
firstSigninFromEdm.StringUbicación aproximada del primer inicio de sesión.
secondSigninFromEdm.StringUbicación aproximada del segundo inicio de sesión.
timeOfSecondSignInEdm.DateTimeOffsetFiltrableFecha y hora del segundo inicio de sesión.
timeBetweenSignInsEdm.StringDiferencia aproximada entre las dos ubicaciones de inicio de sesión.
estimatedTravelHoursEdm.Int32Tiempo de viaje necesario estimado entre las dos ubicaciones de inicio de sesión.
idEdm.GuidIdentificador único del evento.
displayNameEdm.StringNombre para mostrar del usuario.
userNameEdm.StringNombre del usuario.

SignInsFromPossiblyInfectedDevicesEvent

NombreTipoRead(GET)Descripción
deviceIPAddressEdm.StringDirección IP donde se produjo el inicio de sesión.
lastSignInTimeEdm.DateTimeOffsetFiltrableFecha y hora del último inicio de sesión.
deviceLocationEdm.StringUbicación geográfica aproximada del inicio de sesión.
ligeroEdm.StringInformación sobre el dispositivo potencialmente infectado.
suspectedInfectionEdm.StringToda la información sobre la posible infección.
latestPotentiallySuspiciousActivityEdm.DateTimeOffsetFiltrableFecha y hora de la infección.
idEdm.GuidIdentificador único del evento.
displayNameEdm.StringNombre para mostrar del usuario.
userNameEdm.StringNombre del usuario.

SignInsFromUnknownSourcesEvent

NombreTipoRead(GET)Descripción
numberOfSigninsEdm.Int32Número total de inicios de sesión.
ipAddressEdm.StringDirección IP del inicio de sesión.
timeOfLastSuccessfulSignInEdm.DateTimeOffsetFiltrableÚltima fecha y hora en que se produjo este tipo de evento.
idEdm.GuidIdentificador único del evento.
displayNameEdm.StringNombre para mostrar del usuario.
userNameEdm.StringNombre del usuario.

SsgmGroupActivityEvent

NombreTipoRead(GET)Descripción
idEdm.StringIdentificador único del evento.
eventTimeEdm.DateTimeOffsetFiltrableFecha y hora en que se produjo el evento.
groupEdm.StringEl grupo en el que se realizó la acción de autoservicio.
actionEdm.StringLa acción del grupo de autoservicio realizada.

SsprActivityEvent

NombreTipoRead(GET)Descripción
eventTimeEdm.DateTimeOffsetFiltrableFecha y hora en que se produjo el evento.
rolEdm.StringLa función del usuario.
methodsUsedEdm.StringEl método utilizado para restablecer la contraseña del usuario.
resultEdm.StringEl resultado del intento del usuario de restablecer su contraseña.
detallesEdm.StringDetalles adicionales sobre el intento del usuario de restablecer su contraseña.
idEdm.StringIdentificador único del evento.
displayNameEdm.StringNombre para mostrar del usuario.
userNameEdm.StringNombre del usuario.

SsprRegistrationActivityEvent

NombreTipoRead(GET)Descripción
eventTimeEdm.DateTimeOffsetFiltrableFecha y hora en que se produjo el evento.
rolEdm.StringLa función del usuario.
registrationActivityEdm.StringLa actividad de registro realizada por el usuario.
idEdm.StringIdentificador único del evento.
displayNameEdm.StringNombre para mostrar del usuario.
userNameEdm.StringNombre del usuario.

Recursos adicionales

© 2017 Microsoft