Referencia de la API de Actividad de administración de Office 365

Use la API de actividad de Office 365 Management para recuperar información sobre las acciones y eventos de usuario, administrador, sistema y directiva de los registros de actividad de Office 365 y Microsoft Entra.

Puede usar las acciones y eventos de los registros de auditoría y actividad de Office 365 y Microsoft Entra para crear soluciones que proporcionen supervisión, análisis y visualización de datos. Estas soluciones ofrecen a las organizaciones mayor visibilidad de las acciones realizadas en el contenido. Estas acciones y eventos también están disponibles en los informes de actividad de Office 365. Para más información, vea Buscar en el registro de auditoría en Microsoft 365.

La API de Actividad de administración de Office 365 es un servicio web REST que se puede usar para desarrollar soluciones mediante cualquier lenguaje y entorno de hospedaje que admita HTTPS y certificados X.509. La API se basa en Microsoft Entra ID y el protocolo OAuth2 para la autenticación y autorización. Para acceder a la API desde la aplicación, primero debe registrarla en Microsoft Entra ID y configurarla con los permisos adecuados. Esto permitirá que la aplicación solicite los tokens de acceso OAuth2 que necesita para llamar a la API. Para obtener más información, vea Get started with Office 365 Management APIs (Introducción a las API de administración de Office 365).

Para obtener información sobre los datos que devuelve la API de Actividad de administración de Office 365, vea Esquema de la API de Actividad de administración de Office 365.

Trabajar con la API de Actividad de administración de Office 365

La API de Actividad de administración de Office 365 agrega acciones y eventos en blobs de contenido específicos del espacio empresarial, que se clasifican según el tipo y el origen del contenido que contienen. En la actualidad, se admiten estos tipos de contenido:

• Audit.AzureActiveDirectory

• Audit.Exchange

• Audit.SharePoint

• Audit.General (incluye todas las demás cargas de trabajo que no se incluyen en los tipos de contenido anteriores)

• DLP.All (eventos exclusivos de DLP para todas las cargas de trabajo)

Para obtener más información sobre los eventos y las propiedades asociados a estos tipos de contenido, vea Office 365 Management Activity API schema (Esquema de la API de Actividad de administración de Office 365).

Para empezar a recuperar blobs de contenido para un inquilino, primero debe crear una suscripción a los tipos de contenido deseados. Si se van a recuperar blobs de contenido para varios espacios empresariales, cree varias suscripciones a todos los tipos de contenido deseados, una para cada espacio empresarial.

Después de crear una suscripción, puede sondear periódicamente para detectar nuevos blobs de contenido disponibles para descargar, o bien puede registrar un punto de conexión de webhook con la suscripción y se enviarán notificaciones a este punto de conexión cuando haya nuevos blobs de contenido disponibles.

Operaciones de la API de Actividad

Todas las operaciones de API están orientadas a un único espacio empresarial y la dirección URL raíz de la API incluye un identificador de espacio empresarial que especifica el contexto del espacio empresarial. El identificador de espacio empresarial es un GUID. Para obtener información sobre cómo conseguir el GUID, vea Get started with Office 365 Management APIs (Introducción a las API de administración de Office 365).

Como las notificaciones que se envían al webhook incluyen el identificador de espacio empresarial, puede usar el mismo webhook para recibir notificaciones para todos los espacios empresariales.

La URL del punto de conexión de la API que use está basada en el tipo de plan de suscripción de Microsoft 365 u Office 365 de su organización.

Plan para empresas

https://manage.office.com/api/v1.0/{tenant_id}/activity/feed/{operation}

Plan de Administración pública GCC

https://manage-gcc.office.com/api/v1.0/{tenant_id}/activity/feed/{operation}

Plan de Administración pública GCC High

https://manage.office365.us/api/v1.0/{tenant_id}/activity/feed/{operation}

Plan de Administración pública DoD

https://manage.protection.apps.mil/api/v1.0/{tenant_id}/activity/feed/{operation}

Todas las operaciones de API requieren un encabezado HTTP de autorización con un token de acceso obtenido de Microsoft Entra ID. El identificador de inquilino del token de acceso debe coincidir con el identificador de inquilino de la dirección URL raíz de la API y el token de acceso debe contener la notificación ActivityFeed.Read (esto corresponde al permiso [Leer datos de actividad de una organización] que configuró para la aplicación en Microsoft Entra ID).

Authorization: Bearer eyJ0e...Qa6wg

La API de Actividad admite las operaciones siguientes:

• Iniciar una suscripción para empezar a recibir notificaciones y recuperar datos de actividad de un espacio empresarial.

• Detener una suscripción para dejar de recuperar datos de un espacio empresarial.

• Enumerar las suscripciones actuales

• Enumerar el contenido disponible y las direcciones URL de contenido correspondientes.

• Recibir notificaciones enviadas por un webhook cuando hay contenido nuevo disponible.

• Recuperar contenido mediante la dirección URL de contenido.

• Enumerar las notificaciones enviadas por un webhook.

• Recuperar los nombres descriptivos de recurso de los objetos de la fuente de datos identificados mediante GUID.

Iniciar una suscripción

Esta operación inicia una suscripción para el tipo de contenido especificado. Si ya existe una suscripción para el tipo de contenido específico, esta operación se usa para:

• Actualizar las propiedades de un webhook activo.

• Habilitar un webhook que estaba deshabilitado debido a un exceso de notificaciones con error.

• Volver a habilitar un webhook expirado mediante la especificación de una fecha de expiración nula o posterior.

• Quitar un webhook.

Solicitud de muestra

POST {root}/subscriptions/start?contentType=Audit.SharePoint&PublisherIdentifier=46b472a7-c68e-4adf-8ade-3db49497518e
Content-Type: application/json; utf-8
Authorization: Bearer eyJ0e...Qa6wg

{
    "webhook" : {
        "address": "https://webhook.myapp.com/o365/",
        "authId": "o365activityapinotification",
        "expiration": ""
    }
}

Respuesta de muestra

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "contentType": "Audit.SharePoint",
    "status": "enabled",
    "webhook": {
        "status": "enabled",
        "address":  "https://webhook.myapp.com/o365/",
        "authId": "o365activityapinotification",
        "expiration": null
    }
}

Validación del webhook

Cuando se llama a la operación /start y se especifica un webhook, le enviaremos una notificación de validación a la dirección de webhook especificada para validar que una escucha activa puede aceptar y procesar las notificaciones. Si no recibimos una respuesta HTTP 200 Correcto, no se creará la suscripción. O bien, si se empieza a llamar a /start para agregar un webhook a una suscripción existente y no se recibe una respuesta de HTTP 200 Correcto, el webhook no se agregará y no se cambiará la suscripción.

Solicitud de muestra

POST {webhook address}
Content-Type: application/json; charset=utf-8
Webhook-AuthID: (webhook authId, if provided)
Webhook-ValidationCode: (random opaque string)

{
    "validationCode": (random opaque string, same as header)
}

Respuesta de muestra

HTTP/1.1 200 OK

Detener una suscripción

Esta operación detiene una suscripción para el tipo de contenido especificado.

Cuando se detiene una suscripción, ya no recibirá notificaciones y no podrá recuperar el contenido disponible. Si la suscripción se reinicia más adelante, tendrá acceso al nuevo contenido desde ese momento. No podrá recuperar el contenido que estaba disponible entre el momento de detener la suscripción y reiniciarla.

Solicitud de muestra

POST {root}/subscriptions/stop?contentType=Audit.SharePoint&PublisherIdentifier=46b472a7-c68e-4adf-8ade-3db49497518e
Authorization: Bearer eyJ0e...Qa6wg

Respuesta de muestra

HTTP/1.1 200 OK

Enumerar las suscripciones actuales

Esta operación devuelve una colección de las suscripciones actuales junto con los webhooks asociados.

Solicitud de muestra

GET {root}/subscriptions/list?PublisherIdentifier=46b472a7-c68e-4adf-8ade-3db49497518e
Authorization: Bearer eyJ0e...Qa6wg

Respuesta de muestra

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
    {
        "contentType" : "Audit.SharePoint",
        "status": "enabled",
        "webhook": {
            "status": "enabled",
            "address": "https://webhook.myapp.com/o365/",
            "authId": "o365activityapinotification",
            "expiration": null
        }
    },

    ...

    {
        "contentType": "Audit.Exchange",
        "webhook": null
    }
]

Enumerar el contenido disponible

Esta operación enumera el contenido disponible actualmente que se puede recuperar para el tipo de contenido especificado. El contenido es una agregación de acciones y eventos recopilados de varios servidores en varios centros de datos. El contenido se mostrará en el orden en que estén disponibles las agregaciones, pero no se garantiza que los eventos y las acciones de las agregaciones sean secuenciales. Se devuelve un error si el estado de la suscripción es deshabilitado.

Solicitud de muestra

GET {root}/subscriptions/content?contentType=Audit.SharePoint&PublisherIdentifier=46b472a7-c68e-4adf-8ade-3db49497518e
Authorization: Bearer eyJ0e...Qa6wg

Respuesta de muestra

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
    {
        "contentType": "Audit.SharePoint",
        "contentId": "492638008028$492638008028$f28ab78ad40140608012736e373933ebspo2015043022$4a81a7c326fc4aed89c62e6039ab833b$04",
        "contentUri": "https://manage.office.com/api/v1.0/f28ab78a-d401-4060-8012-736e373933eb/activity/feed/audit/492638008028$492638008028$f28ab78ad40140608012736e373933ebspo2015043022$4a81a7c326fc4aed89c62e6039ab833b$04",
        "contentCreated": "2015-05-23T17:35:00.000Z",
        "contentExpiration": "2015-05-30T17:35:00.000Z"
    },
    ...
]

Paginación

Al enumerar el contenido disponible para un intervalo de tiempo, el número de resultados devueltos está limitado para impedir tiempos de espera de respuesta. Si en el intervalo de tiempo especificado hay más resultados de los que se pueden devolver en una única respuesta, los resultados se truncarán y se agregará un encabezado a la respuesta en el que se indica la dirección URL que se va a usar para recuperar la siguiente página de resultados. La dirección URL contendrá los mismos parámetros startTime y endTime que se especificaron en la solicitud original, junto con un parámetro que indica el identificador interno de la página siguiente. Si no se especificaron los parámetros startTime y endTime en la solicitud original, se establecerán para reflejar el intervalo de 24 horas anterior a la solicitud original.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
NextPageUri: https://manage.office.com/api/v1/{tenant_id}/activity/feed/subscriptions/content?contentType=Audit.SharePoint&startTime=2015-10-01&endTime=2015-10-02&nextPage=2015101900R022885001761

Para mostrar todo el contenido disponible para un intervalo de tiempo especificado, es posible que tenga que recuperar varias páginas hasta que reciba una respuesta sin el encabezado NextPageUri.

Recibir notificaciones

Las notificaciones se envían al webhook configurado para una suscripción cuando hay contenido nuevo disponible. Como la notificación incluye el identificador de espacio empresarial, puede usar el mismo webhook para recibir notificaciones para todos los espacios empresariales para los que tiene suscripciones.

La notificación se realiza como HTTP POST sobre TLS (TLS 1.0 y versiones posteriores) a la dirección del webhook especificado. Si la configuración de webhook incluye un identificador de autenticación, se enviará como un encabezado HTTP: Webhook-AuthID. Cualquier respuesta distinta de HTTP 200 Correcto se considera un error y la notificación se volverá a intentar. También puede configurar el webhook para requerir autenticación basada en certificados de cliente y se autenticará con el certificado manage.office.com.

El cuerpo de la solicitud contendrá una matriz de uno o más objetos JSON que representan los blobs de contenido disponibles. El número de blobs de contenido en cada notificación es limitado para que el tamaño de la notificación sea relativamente pequeño. Como este límite puede cambiar, la implementación debe consultar la longitud de la matriz en lugar de esperar un tamaño fijo. Cada objeto incluirá las mismas propiedades que devuelve la operación /content, junto con el GUID del espacio empresarial al que corresponden los datos y el GUID de la aplicación que creó las suscripciones. Esto permite al webhook establecer el contexto cuando se usa con varios espacios empresariales y aplicaciones.

• tenantId: el GUID del espacio empresarial al que pertenece el contenido.

• clientId: el GUID de la aplicación que creó la suscripción.

• contentType: indica el tipo de contenido.

• contentId: una cadena opaca que identifica el contenido de forma única.

• contentUri: la dirección URL que se va a usar al recuperar el contenido.

• contentCreated: la fecha y hora de disponibilidad del contenido.

• contentExpiration: la fecha y hora después de la que el contenido ya no estará disponible para su recuperación.

A continuación se muestra un ejemplo de una notificación.

POST https://webhook.myapp.com/o365/ 
Content-Type: application/json; utf-8
Webhook-AuthID: o365activityapinotification

[
    {
        "tenantId": "{GUID}",
        "clientId": "{GUID}",
        "contentType": "Audit.SharePoint",
        "contentId": "492638008028$492638008028$f28ab78ad40140608012736e373933ebspo2015043022$4a81a7c326fc4aed89c62e6039ab833b$04",
        "contentUri": "https://manage.office.com/api/v1.0/f28ab78a-d401-4060-8012-736e373933eb/activity/feed/audit/492638008028$492638008028$f28ab78ad40140608012736e373933ebspo2015043022$4a81a7c326fc4aed89c62e6039ab833b$04",
        "contentCreated": "2015-05-23T17:35:00.000Z",
        "contentExpiration": "2015-05-30T17:35:00.000Z"
    },
    ...
]

Error de notificación y reintento

El sistema de notificaciones envía las notificaciones cuando hay nuevo contenido disponible. Si se producen errores excesivos al enviar las notificaciones, nuestro mecanismo de reintento aumentará de forma exponencial el tiempo entre los reintentos. Si se siguen produciendo errores, nos reservamos el derecho de deshabilitar el webhook y detener por completo el envío de notificaciones. Se puede usar la operación /start para volver a habilitar un webhook deshabilitado.

Recuperar contenido

Para recuperar un blob de contenido, realice una solicitud GET en el URI del contenido correspondiente que se incluye en la lista de contenido disponible y en las notificaciones enviadas a un webhook. El contenido devuelto será una colección de una más acciones o eventos en formato JSON.

Solicitud de muestra

GET https://manage.office.com/api/v1.0/41463f53-8812-40f4-890f-865bf6e35190/activity/feed/audit/301299007231$301299007231$41463f53881240f4890f865bf6e35190aad2015062920$e1c2ab19858a469fb1f1fd097effffc9$04 HTTP/1.1
Authorization: Bearer eyJ0e...Qa6wg

Respuesta de muestra

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
    {
        "CreationTime": "2015-06-29T20:03:19",
        "Id": "80c76bd2-9d81-4c57-a97a-accfc3443dca",
        "Operation": "PasswordLogonInitialAuthUsingPassword",
        "OrganizationId": "41463f53-8812-40f4-890f-865bf6e35190",
        "RecordType": 9,
        "ResultStatus": "failed",
        "UserKey": "1153977025279851686@contoso.onmicrosoft.com",
        "UserType": 0,
        "Workload": "AzureActiveDirectory",
        "ClientIP": "134.170.188.221",
        "ObjectId": "admin@contoso.onmicrosoft.com",
        "UserId": "admin@contoso.onmicrosoft.com",
        "AzureActiveDirectoryEventType": 0,
        "ExtendedProperties": [
            {
                "Name": "LoginError",
                "Value": "-2147217390;PP_E_BAD_PASSWORD;The entered and stored passwords do not match."
            }
        ],
        "Client": "Exchange",
        "LoginStatus": -2147217390,
        "UserDomain": "contoso.onmicrosoft.com"
    },
    {
        "CreationTime": "2015-06-29T20:03:34",
        "Id": "4e655d3f-35fa-42e0-b050-264b2d255c7a",
        "Operation": "PasswordLogonInitialAuthUsingPassword",
        "OrganizationId": "41463f53-8812-40f4-890f-865bf6e35190",
        "RecordType": 9,
        "ResultStatus": "success",
        "UserKey": "1153977025279851686@contoso.onmicrosoft.com",
        "UserType": 0,
        "Workload": "AzureActiveDirectory",
        "ClientIP": "134.170.188.221",
        "ObjectId": "admin@contoso.onmicrosoft.com",
        "UserId": "admin@contoso.onmicrosoft.com",
        "AzureActiveDirectoryEventType": 0,
        "Client": "Exchange",
        "LoginStatus": 0,
        "UserDomain": "contoso.onmicrosoft.com"
    },
    {
        "CreationTime": "2015-06-29T20:04:55",
        "Id": "b567caf0-088e-4c1c-a4ea-633a1e3d66c8",
        "Operation": "Add User.",
        "OrganizationId": "41463f53-8812-40f4-890f-865bf6e35190",
        "RecordType": 8,
        "ResultStatus": "success",
        "UserKey": "1003BFFD8EC47CA6@contoso.onmicrosoft.com",
        "UserType": 0,
        "Workload": "AzureActiveDirectory",
        "ObjectId": "user001@contoso.onmicrosoft.com",
        "UserId": "admin@contoso.onmicrosoft.com",
        "AzureActiveDirectoryEventType": 0,
        "Actor": [
            {
                "ID": "1cef1fdb-ff52-48c4-8e4e-dfb5ea83d357",
                "Type": 2
            },
            {
                "ID": "admin@contoso.onmicrosoft.com",
                "Type": 5
            },
            {
                "ID": "1003BFFD8EC47CA6",
                "Type": 3
            }
        ],
        "ActorContextId": "41463f53-8812-40f4-890f-865bf6e35190",
        "InterSystemsId": "c2ced078-ad57-4079-a743-5c37f5284790",
        "IntraSystemId": "d1497f7e-15b4-49aa-83ad-11a17ca4a2f4",
        "Target": [
            {
                "ID": "user001@contoso.onmicrosoft.com",
                "Type": 5
            },
            {
                "ID": "10037FFE91510806",
                "Type": 3
            }
        ],
        "TargetContextId": "41463f53-8812-40f4-890f-865bf6e35190"
    }
]

Enumerar notificaciones

Esta operación enumera todos los intentos de notificación para el tipo de contenido especificado. Si no ha incluido un webhook al iniciar la suscripción para el tipo de contenido, no existirá ninguna notificación para recuperar. Como en caso de error se reintentan las notificaciones, esta operación puede devolver varias notificaciones para el mismo contenido, y el orden en el que se envían no coincidirá necesariamente con el orden en que el contenido está disponible (en especial si hay errores y reintentos).

Puede usar esta operación para ayudar a investigar problemas relacionados con los webhooks y las notificaciones, pero no debería usarla para determinar qué contenido está disponible actualmente para la recuperación. En su lugar, use la operación /content. Se devolverá un error si el estado de la suscripción es deshabilitado.

Solicitud de muestra

GET {root}/subscriptions/notifications?contentType=Audit.SharePoint&PublisherIdentifier=46b472a7-c68e-4adf-8ade-3db49497518e
Authorization: Bearer eyJ0e...Qa6wg

Respuesta de muestra

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
    {
        "contentType": "Audit.SharePoint",
        "contentId": "492638008028$492638008028$f28ab78ad40140608012736e373933ebspo2015043022$4a81a7c326fc4aed89c62e6039ab833b$04",
        "contentUri": "https://manage.office.com/api/v1.0/f28ab78a-d401-4060-8012-736e373933eb/activity/feed/audit/492638008028$492638008028$f28ab78ad40140608012736e373933ebspo2015043022$4a81a7c326fc4aed89c62e6039ab833b$04",
        "contentCreated": "2015-05-23T17:35:00.000Z",
        "contentExpiration": "2015-05-30T17:35:00.000Z",
        "notificationSent": "2015-05-23T17:36:00.000Z",
        "notificationStatus": "success"

    },
    ...
]

Paginación

Al enumerar el historial de notificaciones para un intervalo de tiempo, el número de resultados devueltos está limitado para impedir tiempos de espera de respuesta. Si en el intervalo de tiempo especificado hay más resultados de los que se pueden devolver en una única respuesta, los resultados se truncan y se agrega un encabezado a la respuesta en el que se indica la dirección URL que se va a usar para recuperar la siguiente página de resultados. La dirección URL contendrá los mismos parámetros startTime y endTime que se especificaron en la solicitud original, junto con un parámetro que indica el identificador interno de la página siguiente. Si no se especificaron los parámetros startTime y endTime en la solicitud original, se establecerán para reflejar el intervalo de 24 horas anterior a la solicitud original.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
NextPageUri: https://manage.office.com/api/v1/{tenant_id}/activity/feed/subscriptions/content?contentType=Audit.SharePoint&startTime=2015-10-01&endTime=2015-10-02&nextPage=2015101900R022885001761

Para mostrar todo el contenido disponible para un intervalo de tiempo especificado, es posible que tenga que recuperar varias páginas hasta que reciba una respuesta sin el encabezado NextPageUri.

Recuperar los nombres descriptivos de recurso

Esta operación recupera los nombres descriptivos de los objetos de la fuente de datos identificados mediante GUID. En la actualidad, el único objeto que se admite es "DlpSensitiveType".

Solicitud de muestra

GET {root}/resources/dlpSensitiveTypes?PublisherIdentifier=46b472a7-c68e-4adf-8ade-3db49497518e
Authorization: Bearer eyJ0e...Qa6wg
Accept-Language: {language code} 

Respuesta de muestra

HTTP/1.1 200 OK

[
    {
        "id": "50842eb7-edc8-4019-85dd-5a5c1f2bb085",
        "name": "CreditCardNumber"
    }, 
    {
        "id": "0e9b3178-9678-47dd-a509-37222ca96b42",
        "name": "EUDebitCardNumber"
    }, 
    ...
    {
    }
]

Limitación de API

Las organizaciones que tienen acceso a registros de auditoría a través de la API de Actividad de administración de Office 365 se restringieron con límites en el nivel de editor. Esto significa que, para un editor que extrae datos en nombre de varios clientes, todos los clientes han compartido el límite.

Estamos cambiando de un límite de nivel de editor a un límite de nivel de espacio empresarial. El resultado es que cada organización obtendrá su propia cuota de ancho de banda completamente asignada para tener acceso a los datos de auditoría. Se asigna inicialmente una línea base de 2 000 solicitudes por minuto a todas las organizaciones. Este no es un límite estático y predefinido, sino que se modela en base a una combinación de factores, incluido el número de puestos en la organización, y que las organizaciones de Office 365 y Microsoft 365 E5 tendrán aproximadamente el doble de ancho de banda que las organizaciones que no son E5. También habrá un límite en el ancho de banda máximo para proteger el estado del servicio.

Para obtener más información, vea la sección "acceso de banda ancha a la API de Actividad de administración de Office 365" en Auditoría avanzada en Microsoft 365.

Errores

Cuando el servicio encuentra un error, notificará el código de respuesta de error al autor de la llamada, mediante la sintaxis estándar de código de error de HTTP. . En el cuerpo de la llamada con error se incluye información adicional como un único objeto JSON. A continuación se muestra un ejemplo de un cuerpo completo de error JSON:

{ 
    "error":{ 
        "code":"AF50000",
        "message": "An internal server error occurred. Retry the request."
    } 
}