Référence de l’API Activité de gestion Office 365
Utilisez l’API d’activité de gestion Office 365 pour récupérer des informations sur les actions et événements des utilisateurs, des administrateurs, du système et des stratégies à partir des journaux d’activité Office 365 et Microsoft Entra.
Vous pouvez utiliser les actions et les événements de l’Office 365 et Microsoft Entra journaux d’audit et d’activité pour créer des solutions qui fournissent la surveillance, l’analyse et la visualisation des données. Ces solutions offrent aux organisations une meilleure visibilité sur les actions effectuées sur leur contenu. Ces actions et ces événements sont également disponibles dans les rapports d’activité Office 365. Pour plus d’informations, consultez Rechercher le journal d'audit dans Microsoft 365.
Conseil
Si vous souhaitez créer des rapports personnalisés à partir des journaux d’audit, les blogs suivants peuvent vous être utiles.
L’API Activité de gestion Office 365 est un service web REST qui vous permet de développer des solutions à l’aide de n’importe quel langage et environnement d’hébergement qui prend en charge les certificats X.509 et HTTPS. L’API s’appuie sur Microsoft Entra ID et le protocole OAuth2 pour l’authentification et l’autorisation. Pour accéder à l’API à partir de votre application, vous devez d’abord l’inscrire dans Microsoft Entra ID et la configurer avec les autorisations appropriées. Ainsi, votre application pourra demander les jetons d’accès OAuth2 dont elle a besoin pour appeler l’API. Pour en savoir plus, consultez l’article relatif à la prise en main des API de gestion Office 365.
Pour obtenir des informations sur les données renvoyées par l’API Activité de gestion Office 365 ainsi que sur les problèmes connus et les modifications à venir risquant d’affecter votre implémentation, consultez l’article relatif au schéma de l’API Activité de gestion Office 365.
Importante
Avant de pouvoir accéder aux données via l’API Activité de gestion Office 365, vous devez activer la journalisation d’audit unifié pour votre organisation Office 365. Pour ce faire, vous devez activer le journal d’audit d’Office 365. Pour obtenir des instructions, consultez la rubrique Activer ou désactiver la recherche dans un journal d’audit Office 365.
Utilisation de l’API Activité de gestion Office 365
L’API Activité de gestion Office 365 agrège des actions et des événements dans des blobs de contenu propres au locataire, classés selon le type et la source du contenu qu’ils contiennent. Actuellement, les types de contenu suivants sont pris en charge :
Audit.AzureActiveDirectory
Audit.Exchange
Audit.SharePoint
Audit.General (comprend toutes les autres charges de travail non incluses dans les types de contenu précédents)
DLP.All (événements DLP liés à toutes les charges de travail)
Pour en savoir plus sur les événements et les propriétés associés à ces types de contenu, consultez l’article relatif au schéma de l’API Activité de gestion Office 365.
Pour commencer à récupérer des objets blob de contenu pour un locataire, vous devez d’abord créer un abonnement aux types de contenu souhaités. Si vous récupérez des blobs de contenu associés à plusieurs locataires, créez un abonnement à chacun des types de contenu souhaités pour chaque client.
Une fois qu’un abonnement est créé, vous pouvez régulièrement l’interroger pour découvrir les nouveaux blobs de contenu disponibles au téléchargement. Sinon, vous pouvez inscrire un point de terminaison de webhook avec l’abonnement, auquel nous enverrons des notifications dès que de nouveaux blobs de contenu sont disponibles.
Remarque
Quand un abonnement est créé, il faut attendre jusqu’à 12 heures avant que les premiers blobs de contenu associés à cet abonnement deviennent disponibles. Les blobs de contenu sont créés en collectant et en agrégeant des actions et des événements sur plusieurs serveurs et centres de données. À la suite de ce processus distribué, les actions et les événements contenus dans les blobs de contenu n’apparaissent pas nécessairement dans l’ordre dans lequel ils ont eu lieu. Un blob de contenu peut contenir des actions et des événements qui ont eu lieu avant les actions et les événements contenus dans un blob de contenu antérieur. Nous mettons tout en œuvre pour réduire la latence entre l’occurrence des actions et des événements et leur disponibilité au sein d’un blob de contenu, mais nous ne pouvons pas garantir qu’elles apparaissent de manière séquentielle.
Remarque
Les données sensibles régies par les stratégies de protection contre la perte de données (DLP) sont disponibles dans l’API Flux d’activités uniquement pour les utilisateurs auxquels les autorisations « Lire les données sensibles DLP » ont été accordées. Pour en savoir plus, reportez-vous à l’article Vue d’ensemble des stratégies de protection contre la perte de données.
Opérations de l’API Activité
Toutes les opérations de l’API sont limitées à un seul locataire et l’URL racine de l’API inclut un ID de locataire qui spécifie le contexte du locataire. L’ID de locataire est un GUID. Pour savoir comment obtenir le GUID, consultez l’article relatif à la prise en main des API de gestion Office 365.
Étant donné que les notifications que nous envoyons à votre webhook incluent l’ID de locataire, vous pouvez utiliser le même webhook pour recevoir des notifications pour tous les locataires.
L’URL du point de terminaison de l’API que vous utilisez est basée sur le type d’abonnement Microsoft 365 ou Office 365 pour votre organisation.
Plan Entreprise
https://manage.office.com/api/v1.0/{tenant_id}/activity/feed/{operation}
Plan pour le secteur public GCC
https://manage-gcc.office.com/api/v1.0/{tenant_id}/activity/feed/{operation}
Plan pour le secteur public GCC
https://manage.office365.us/api/v1.0/{tenant_id}/activity/feed/{operation}
Plan pour le secteur public DoD
https://manage.protection.apps.mil/api/v1.0/{tenant_id}/activity/feed/{operation}
Toutes les opérations d’API nécessitent un en-tête HTTP d’autorisation avec un jeton d’accès obtenu à partir de Microsoft Entra ID. L’ID de locataire dans le jeton d’accès doit correspondre à l’ID de locataire dans l’URL racine de l’API et le jeton d’accès doit contenir la revendication ActivityFeed.Read (cela correspond à l’autorisation [Lire les données d’activité pour un organization] que vous avez configurée pour votre application dans Microsoft Entra ID).
Authorization: Bearer eyJ0e...Qa6wg
L’API Activité prend en charge les opérations suivantes :
Démarrer un abonnement pour commencer à recevoir des notifications et récupérer les données d’activité d’un locataire.
Arrêter un abonnement pour ne plus récupérer les données d’un locataire.
Répertorier les abonnements actifs
Répertorier le contenu disponible et les URL de contenu correspondantes.
Recevoir des notifications envoyées par un webhook dès que du nouveau contenu est disponible.
Récupérer du contenu à l’aide de l’URL de contenu.
Répertorier les notifications envoyées par un webhook.
Récupérer les noms conviviaux des ressources pour les objets du flux de données identifiés par un GUID.
Démarrer un abonnement
Cette opération démarre l’abonnement souscrit pour le type de contenu spécifié. Si un abonnement pour le type de contenu spécifié existe déjà, cette opération sert à :
mettre à jour les propriétés d’un webhook actif.
activer un webhook qui a été désactivé en raison du nombre excessif de notifications d’échec envoyées.
réactiver un webhook expiré en spécifiant une date d’expiration Null ou ultérieure.
supprimer un webhook.
| Abonnement | Description |
|---|---|
| Chemin | /subscriptions/start?contentType={ContentType} |
| Paramètres | contentType : doit être un type de contenu valide. |
| PublisherIdentifier | GUID de locataire de l’éditeur qui code l’API. Il ne s’agit pas du GUID de l’application ou du GUID du client qui utilise l’application, mais bien du GUID de l’entreprise qui écrit le code. Ce paramètre permet de limiter le taux de requêtes émises. Vérifiez que ce paramètre est spécifié dans toutes les requêtes émises pour obtenir un quota dédié. Toutes les requêtes reçues sans ce paramètre auront le même quota. |
| Corps | webhook : cet objet JSON facultatif comprend trois propriétés :
|
| Réponse | contentType : type de contenu spécifié dans l’appel. |
| statut | Statut de l’abonnement. Si un abonnement est désactivé, vous ne serez pas en mesure de répertorier ou de récupérer du contenu. |
| webhook | Propriétés du webhook spécifiées dans l’appel avec l’état du webhook. Si le webhook est désactivé, vous ne recevrez pas de notification, mais vous pourrez toujours répertorier et récupérer du contenu, à condition que l’abonnement soit activé. |
Exemple de demande
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": ""
}
}
Exemple de réponse
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
}
}
Validation du webhook
Quand l’opération /start est appelée et un webhook est spécifié, nous vous envoyons une notification de validation à l’adresse de webhook indiquée pour confirmer qu’un détecteur actif peut accepter et traiter les notifications. Si nous ne recevons pas une réponse HTTP 200 OK, l’abonnement n’est pas créé. Sinon, si l’opération /start est appelée pour ajouter un webhook à un abonnement existant et si nous ne recevons pas une réponse HTTP 200 OK, le webhook n’est pas ajouté et l’abonnement reste inchangé.
Exemple de demande
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)
}
Exemple de réponse
HTTP/1.1 200 OK
Arrêter un abonnement
Cette opération arrête un abonnement souscrit pour le type de contenu spécifié.
Lorsqu’un abonnement est arrêté, vous ne recevez plus de notifications et vous ne pourrez plus récupérer le contenu disponible. Si l’abonnement est redémarré ultérieurement, vous aurez accès au nouveau contenu à partir de ce moment. Vous ne pourrez pas récupérer le contenu mis à disposition pendant la période où l’abonnement était arrêté.
| Abonnement | Description |
|---|---|
| Chemin | /subscriptions/stop?contentType={ContentType} |
| Paramètres | contentType : doit être un type de contenu valide. |
| PublisherIdentifier | GUID de locataire de l’éditeur qui code l’API. Il ne s’agit pas du GUID de l’application ou du GUID du client qui utilise l’application, mais bien du GUID de l’entreprise qui écrit le code. Ce paramètre permet de limiter le taux de requêtes émises. Vérifiez que ce paramètre est spécifié dans toutes les requêtes émises pour obtenir un quota dédié. Toutes les requêtes reçues sans ce paramètre auront le même quota. |
| Corps | (vide) |
| Réponse | (vide) |
Exemple de demande
POST {root}/subscriptions/stop?contentType=Audit.SharePoint&PublisherIdentifier=46b472a7-c68e-4adf-8ade-3db49497518e
Authorization: Bearer eyJ0e...Qa6wg
Exemple de réponse
HTTP/1.1 200 OK
Répertorier les abonnements actifs
Cette opération renvoie une collection d’abonnements actifs avec les webhooks associés.
| Abonnement | Description | |
|---|---|---|
| Chemin | /subscriptions/list |
|
| Paramètres | PublisherIdentifier | GUID de locataire de l’éditeur qui code l’API. Il ne s’agit pas du GUID de l’application ou du GUID du client qui utilise l’application, mais bien du GUID de l’entreprise qui écrit le code. Ce paramètre permet de limiter le taux de requêtes émises. Vérifiez que ce paramètre est spécifié dans toutes les requêtes émises pour obtenir un quota dédié. Toutes les requêtes reçues sans ce paramètre auront le même quota. |
| Corps | (vide) | |
| Réponse | Tableau JSON | Chaque abonnement est représenté par un objet JSON comprenant trois propriétés :
|
Exemple de demande
GET {root}/subscriptions/list?PublisherIdentifier=46b472a7-c68e-4adf-8ade-3db49497518e
Authorization: Bearer eyJ0e...Qa6wg
Exemple de réponse
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
}
]
Répertorier le contenu disponible
Cette opération répertorie le contenu actuellement disponible que vous pouvez récupérer pour le type de contenu spécifié. Le contenu est une agrégation des actions et des événements collectés sur plusieurs serveurs de plusieurs centres de données. Le contenu est répertorié dans l’ordre de mise à disposition des agrégations. En revanche, nous ne pouvons pas garantir que les événements et les actions des agrégations sont répertoriés de manière séquentielle. Une erreur est renvoyée si l’état de l’abonnement est désactivé.
| Abonnement | Description |
|---|---|
| Chemin | /subscriptions/content?contentType={ContentType}&startTime={0}&endTime={1} |
| Paramètres | contentType : doit être un type de contenu valide. |
| PublisherIdentifier | GUID de locataire de l’éditeur qui code l’API. Il ne s’agit pas du GUID de l’application ou du GUID du client qui utilise l’application, mais bien du GUID de l’entreprise qui écrit le code. Ce paramètre permet de limiter le taux de requêtes émises. Vérifiez que ce paramètre est spécifié dans toutes les requêtes émises pour obtenir un quota dédié. Toutes les requêtes reçues sans ce paramètre auront le même quota. |
| startTime endTime | Date/Heure (UTC) facultative indiquant l’intervalle de temps à prendre en compte pour renvoyer le contenu, selon le moment à partir duquel le contenu est devenu disponible. L’intervalle de temps est inclusif en ce qui concerne startTime (startTime <= contentCreated) et exclusif en ce qui concerne endTime (contentCreated < endTime), de sorte que les intervalles de temps incrémentiels qui ne se chevauchent pas peuvent être utilisés pour paginer le contenu disponible.
REMARQUE : même si l’heure de début et l’heure de fin peuvent être espacées de plus de 24 heures, nous vous déconseillons de le faire. Par ailleurs, si vous obtenez des résultats en réponse à une requête portant sur un intervalle de plus de 24 heures, ces résultats peuvent être partiels et ne doivent pas être pris en compte. L’intervalle de la requête émise entre l’heure de début et l’heure de fin doit couvrir une plage horaire de moins de 24 heures. |
| Réponse | Tableau JSON : le contenu disponible est représenté par des objets JSON comprenant les propriétés suivantes :
|
Exemple de demande
GET {root}/subscriptions/content?contentType=Audit.SharePoint&PublisherIdentifier=46b472a7-c68e-4adf-8ade-3db49497518e
Authorization: Bearer eyJ0e...Qa6wg
Exemple de réponse
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"
},
...
]
Pagination
Quand vous répertoriez le contenu disponible au cours d’un intervalle de temps donné, le nombre de résultats renvoyés est limité pour éviter de dépasser le délai de réponse. Si d’autres résultats correspondent à l’intervalle de temps spécifié mais ne peuvent pas être renvoyés dans une seule réponse, les résultats sont tronqués et un en-tête est ajouté à la réponse indiquant l’URL à utiliser pour accéder à la page de résultats suivante. L’URL contient les mêmes paramètres startTime et endTime qui ont été spécifiés dans la requête d’origine, ainsi qu’un paramètre indiquant l’ID interne de la page suivante. Si les paramètres startTime et endTime ne sont pas spécifiés dans la requête d’origine, ils indiquent l’intervalle de 24 heures qui précède la requête d’origine.
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
Pour répertorier tout le contenu disponible dans un intervalle de temps spécifié, vous devrez peut-être récupérer plusieurs pages jusqu’à ce que vous receviez une réponse qui ne contient pas l’en-tête NextPageUri.
Réception des notifications
Les notifications sont envoyées au webhook configuré pour un abonnement au fur et à mesure que le nouveau contenu devient disponible. Étant donné que les notifications incluent l’ID de locataire, vous pouvez utiliser le même webhook pour recevoir des notifications pour tous les locataires auxquels vous êtes abonné.
La notification est envoyée sous la forme d’une requête HTTP POST sur TLS (TLS 1.0 et versions ultérieures) à l’adresse de webhook spécifiée. Si la configuration du webhook inclut un ID d’authentification, nous l’envoyons comme en-tête HTTP : Webhook-AuthID. Les réponses qui n’incluent pas HTTP 200 OK seront considérées comme ayant échoué et la notification sera renvoyée. Vous pouvez également configurer votre webhook pour exiger une authentification basée sur les certificats clients ; nous nous authentifierons alors à l’aide du certificat manage.office.com.
Le corps de la requête contiendra une matrice comprenant un ou plusieurs objets JSON qui représentent les blobs de contenu disponibles. Le nombre de blobs de contenu compris dans chaque notification est limité pour réduire au maximum la taille de la notification. Dans la mesure où cette limite peut être modifiée, votre implémentation doit interroger la longueur de la matrice au lieu de prévoir une taille fixe. Chaque objet inclura les mêmes propriétés renvoyées par l’opération /content ainsi que le GUID du locataire auquel appartiennent les données et le GUID de l’application ayant créé les abonnements. Ainsi, le webhook peut établir le contexte dans lequel il est utilisé avec plusieurs locataires et applications.
tenantId : GUID du locataire auquel appartient le contenu.
clientId : GUID de votre application qui a créé l’abonnement.
contentType : indique le type de contenu.
contentId : chaîne opaque qui identifie le contenu.
contentUri : URL à utiliser pour récupérer le contenu.
contentCreated : date/heure à laquelle le contenu est disponible.
contentExpiration : date/heure après laquelle vous ne pouvez plus récupérer le contenu.
Vous trouverez ci-dessous un exemple de notification.
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"
},
...
]
Échec de notification et nouvelle tentative
Le système de notification envoie des notifications dès que du nouveau contenu est disponible. Si l’envoi des notifications échoue à de multiples reprises, le délai d’attente entre chaque nouvelle tentative augmente. Si l’envoi des notifications continue d’échouer, nous nous réservons le droit de désactiver le webhook et d’arrêter de lui envoyer des notifications. L’opération /start peut être utilisée pour réactiver un webhook désactivé.
Récupérer du contenu
Pour récupérer un blob de contenu, envoyez une requête GET à l’URI de contenu correspondante qui figure dans la liste du contenu disponible et dans les notifications envoyées au webhook. Le contenu renvoyé correspondra à une collection d’un ou de plusieurs événements ou actions au format JSON.
Exemple de demande
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
Exemple de réponse
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"
}
]
Répertorier les notifications
Cette opération répertorie toutes les tentatives de notification associées au type de contenu spécifié. Si vous n’avez pas inclus un webhook au démarrage de l’abonnement souscrit pour le type de contenu, aucune notification ne pourra être récupérée. Dans la mesure où nous renvoyons les notifications en cas d’échec de l’envoi initial, cette opération peut renvoyer plusieurs notifications pour le même contenu. Par ailleurs, l’ordre dans lequel les notifications sont envoyées ne correspond pas nécessairement à l’ordre de parution du contenu (en particulier en cas d’échecs et de nouvelles tentatives).
Vous pouvez utiliser cette opération pour vous aider à résoudre les problèmes liés aux webhooks et aux notifications, mais nous vous déconseillons de l’utiliser pour déterminer le contenu disponible que vous pouvez récupérer. Pour cela, utilisez plutôt l’opération /content. Nous renvoyons une erreur si l’état de l’abonnement est désactivé.
| Abonnement | Description |
|---|---|
| Chemin | /subscriptions/notifications?contentType={ContentType}&startTime={0}&endTime={1} |
| Paramètres | contentType : doit être un type de contenu valide. |
| PublisherIdentifier | GUID de locataire de l’éditeur qui code l’API. Il ne s’agit pas du GUID de l’application ou du GUID du client qui utilise l’application, mais bien du GUID de l’entreprise qui écrit le code. Ce paramètre permet de limiter le taux de requêtes émises. Vérifiez que ce paramètre est spécifié dans toutes les requêtes émises pour obtenir un quota dédié. Toutes les requêtes reçues sans ce paramètre auront le même quota. |
| startTime endTime | Date/Heure (UTC) facultative indiquant l’intervalle de temps à prendre en compte pour renvoyer le contenu, selon le moment à partir duquel le contenu est devenu disponible. L’intervalle de temps est inclusif en ce qui concerne startTime ( startTime<= contentCreated) et exclusif par rapport à endTime (contentCreated< endTime), de sorte que les intervalles de temps incrémentiels qui ne se chevauchent pas peuvent être utilisés pour paginer le contenu disponible.
|
| Réponse | Tableau JSON : les notifications sont représentées par des objets JSON comprenant les propriétés suivantes :
|
Exemple de demande
GET {root}/subscriptions/notifications?contentType=Audit.SharePoint&PublisherIdentifier=46b472a7-c68e-4adf-8ade-3db49497518e
Authorization: Bearer eyJ0e...Qa6wg
Exemple de réponse
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"
},
...
]
Pagination
Quand vous répertoriez l’historique de notification au cours d’un intervalle de temps donné, le nombre de résultats renvoyés est limité pour éviter de dépasser le délai de réponse. Si d’autres résultats correspondent à l’intervalle de temps spécifié mais ne peuvent pas être renvoyés dans une seule réponse, les résultats sont tronqués et un en-tête est ajouté à la réponse indiquant l’URL à utiliser pour accéder à la page de résultats suivante. L’URL contient les mêmes paramètres startTime et endTime qui ont été spécifiés dans la requête d’origine, ainsi qu’un paramètre indiquant l’ID interne de la page suivante. Si les paramètres startTime et endTime ne sont pas spécifiés dans la requête d’origine, ils indiquent l’intervalle de 24 heures qui précède la requête d’origine.
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
Pour répertorier tout le contenu disponible dans un intervalle de temps spécifié, vous devrez peut-être récupérer plusieurs pages jusqu’à ce que vous receviez une réponse qui ne contient pas l’en-tête NextPageUri.
Récupération des noms conviviaux des ressources
Cette opération récupère les noms conviviaux des ressources pour les objets du flux de données identifiés par un GUID. « DlpSensitiveType » est actuellement le seul objet pris en charge.
| Objet | Abonnement | Description |
|---|---|---|
| Chemin | /resources/dlpSensitiveTypes |
|
| Paramètres | PublisherIdentifier | GUID de locataire de l’éditeur qui code l’API. Il ne s’agit pas du GUID de l’application ou du GUID du client qui utilise l’application, mais bien du GUID de l’entreprise qui écrit le code. Ce paramètre permet de limiter le taux de requêtes émises. Vérifiez que ce paramètre est spécifié dans toutes les requêtes émises pour obtenir un quota dédié. Toutes les requêtes reçues sans ce paramètre auront le même quota. |
| En-têtes | Accept-Language | En-tête pour spécifier la langue dans laquelle les noms doivent être localisés. Par exemple, utilisez « en-US » pour l’anglais ou « es » pour l’espagnol. La langue par défaut (en-US) est renvoyée si cet en-tête n’est pas présent. |
| Corps | (vide) | |
| Réponse | Tableau JSON | Le contenu disponible est représenté par des objets JSON comprenant les propriétés suivantes :
|
Exemple de demande
GET {root}/resources/dlpSensitiveTypes?PublisherIdentifier=46b472a7-c68e-4adf-8ade-3db49497518e
Authorization: Bearer eyJ0e...Qa6wg
Accept-Language: {language code}
Exemple de réponse
HTTP/1.1 200 OK
[
{
"id": "50842eb7-edc8-4019-85dd-5a5c1f2bb085",
"name": "CreditCardNumber"
},
{
"id": "0e9b3178-9678-47dd-a509-37222ca96b42",
"name": "EUDebitCardNumber"
},
...
{
}
]
Limitation des requêtes de l’API
Les organisations accédant à des journaux d’audit via l’API Activité de gestion d’Office 365 étaient restreintes par des seuils de limitation au niveau de l’éditeur. Cela signifie que pour un éditeur faisant une extraction de données pour le compte de plusieurs clients, la limite était partagée par tous les clients.
Nous allons passer d’une limite au niveau éditeur à une limite au niveau du client. Chaque organisation obtient ainsi son propre quota de bande passante entièrement allouée pour accéder à leurs données d’audit. Les organisations reçoivent une ligne de base de 2 000 demandes par minute. Il ne s’agit pas d’une limite statique prédéfinie, mais elle est modelée sur la combinaison de facteurs, tels que le nombre de sièges au sein de l’organisation, et les organisations Office 365 et Microsoft 365 E5 obtiennent une bande passante à peu près deux fois plus importante que les organisations non E5. La bande passante aura également un plafond maximal pour protéger l’état d’intégrité du service.
Pour plus d’informations, voir la section « Accès à large bande passante à l'API Activité de gestionOffice 365 » dans l'Audit avancé de Microsoft 365.
Remarque
Même si chaque client peut initialement envoyer 2 000 requêtes par minute, Microsoft ne peut garantir le taux de réponse. Le taux de réponse dépend de différents facteurs, tels que les performances du système client, la capacité et la vitesse du réseau.
Errors
Quand le service rencontre une erreur, il signale le code de la réponse d’erreur à l’appelant en utilisant la syntaxe du code d’erreur HTTP standard. . Des informations complémentaires sont incluses dans le corps de l’appel ayant échoué en tant qu’objet JSON unique. Voici un exemple du corps complet de l’erreur JSON :
{
"error":{
"code":"AF50000",
"message": "An internal server error occurred. Retry the request."
}
}
| Code | Message |
|---|---|
| AF10001 | Le jeu d’autorisations ({0}) envoyé dans la requête n’inclut pas l’autorisation ActivityFeed.Read attendue. {0} = jeu d’autorisations défini dans le jeton d’accès. |
| AF20001 | Paramètre manquant : {0}. {0} = nom du paramètre manquant. |
| AF20002 | Type de paramètre non valide : {0}. Type attendu : {1}. {0} = nom du paramètre non valide. {1} = type attendu (int, datetime, guid). |
| AF20003 | L’expiration {0} fournie indique une date et une heure passées. {0} = expiration transmise dans l’appel de l’API. |
| AF20010 | L’ID de locataire transmis dans l’URL ({0}) ne correspond pas à l’ID de locataire transmis dans le jeton d’accès ({1}). {0} = ID client passé dans l’URL{1} = ID client passé dans le jeton d’accès |
| AF20011 | L’ID de locataire spécifié ({0}) n’existe pas dans le système ou a été supprimé. {0} = ID de locataire transmis dans l’URL |
| AF20012 | L’ID de locataire spécifié ({0}) est configuré de façon incorrecte dans le système. {0} = ID de locataire transmis dans l’URL |
| AF20013 | L’ID de locataire transmis dans l’URL ({0}) n’est pas un GUID valide. {0} = ID de locataire transmis dans l’URL |
| AF20020 | Le type de contenu spécifié n’est pas valide. |
| AF20021 | Le point de terminaison de webhook {{0}) n’a pas été validé. {1} {0} = adresse de webhook. {1} = « Le point de terminaison n’a pas retourné HTTP 200 . » ou « L’adresse doit commencer par HTTPS ». |
| AF20022 | Aucun abonnement trouvé pour le type de contenu spécifié. |
| AF20023 | L’abonnement a été désactivé par {0}. {0} = « un administrateur du locataire » ou « administrateur du service » |
| AF20030 | L’heure de début et l’heure de fin doivent être toutes les deux renseignées (ou omises), doivent être espacées d’un intervalle de moins de 24 heures, et l’heure de début ne doit pas dater de plus de 7 jours. |
| AF20031 | Saisie nextPage non valide : {0}. {0} = indicateur de la page suivante transmis dans l’URL |
| AF20050 | Le contenu spécifié ({0}) n’existe pas. {0} = ID ou URL de la ressource |
| AF20051 | Le contenu demandé avec la touche {0} a déjà expiré. Le contenu datant de plus de 7 jours ne peut pas être récupéré.< {0} = ID de la ressource ou URL de la ressource |
| AF20052 | L’ID de contenu {0} dans l’URL n’est pas valide. {0} = ID ou URL de la ressource |
| AF20053 | Une seule langue peut être indiquée dans l’en-tête Accept-Language. |
| AF20054 | Syntaxe non valide dans l’en-tête Accept-Language. |
| AF429 | Trop de demandes. Method={0}, PublisherId={1} {0} = méthode HTTP {1} = GUID de locataire utilisé en tant que PublisherIdentifier |
| AF50000 | Une erreur interne s’est produite. Retentez la requête. |