Examiner les activités à l’aide de l’APIInvestigate activities using the API

S’applique à : Microsoft Cloud App SecurityApplies to: Microsoft Cloud App Security

Important

Les noms des produits Microsoft de protection contre les menaces changent.Threat protection product names from Microsoft are changing. Vous trouverez ici plus d’informations sur ce sujet et sur les autres mises à jour.Read more about this and other updates here. Nous allons très prochainement mettre à jour les noms des produits et des documents.We'll be updating names in products and in the docs in the near future.

Vous pouvez utiliser les API d’activités pour analyser les activités effectuées par vos utilisateurs dans les applications Cloud connectées.You can use the Activities APIs to investigate the activities performed by your users across connected cloud apps.

Le mode API des activités est optimisé pour l’analyse et la récupération de grandes quantités de données (plus de 5 000 activités).The activities API mode is optimized for scanning and retrieval of large quantities of data (over 5,000 activities). L’analyse des API interroge les données d’activité à plusieurs reprises jusqu’à ce que tous les résultats aient été analysés.The API scan queries the activity data repeatedly until all the results have been scanned.

Notes

Pour les grandes quantités d’activités et les déploiements à grande échelle, nous vous recommandons d’utiliser l' agent Siem pour l’analyse des activités.For large quantities of activities and large scale deployments, we recommended that you use the SIEM agent for activity scanning.

Pour utiliser le script d’analyse des activitésTo use the activity scan script

  1. Exécutez la requête sur vos données.Run the query on your data.
  2. S’il y a plus d’enregistrements qu’il n’est possible de répertorier dans une seule analyse, vous recevrez une commande de retour avec nextQueryFilters que vous devez exécuter.If there are more records than could be listed in a single scan, you will get a return command with nextQueryFilters that you should run. Vous obtiendrez cette commande chaque fois que vous analyserez jusqu’à ce que la requête retournait tous les résultats.You will get this command each time you scan until the query has returned all the results.

Paramètres du corps de la demandeRequest body parameters

  • « filters » : filtrez les objets avec tous les filtres de recherche de la demande. pour plus d’informations, consultez filtres d’activité ."filters": Filter objects with all the search filters for the request, see Activity filters for more information. Pour éviter que vos demandes ne soient limitées, veillez à inclure une limitation sur votre requête, par exemple, à interroger les activités du dernier jour ou à filtrer une application particulière.To avoid having your requests be throttled, make sure to include a limitation on your query, for example, query the last day's activities, or filter for a particular app.
  • « isScan » : valeur booléenne."isScan": Boolean. Active le mode d’analyse.Enables the scanning mode.
  • "sortDirection" : le sens de tri, les valeurs possibles sont "ASC" et "desc""sortDirection": The sorting direction, possible values are "asc" and "desc"
  • « sortField » : champs utilisés pour trier les activités."sortField": Fields used to sort activities. Les valeurs possibles sont les suivantes :Possible values are:
    • Date : date à laquelle l’activité s’est produite (valeur par défaut).date - The date when then the activity occurred (this is the default).
    • created : horodatage de l’enregistrement de l’activité.created - The timestamp when the activity was saved.
  • « Limit » : entier."limit": Integer. En mode d’analyse, entre 500 et 5000 (la valeur par défaut est 500).In scan mode, between 500 and 5000 (defaults to 500). Contrôle le nombre d’itérations utilisées pour l’analyse de toutes les données.Controls the number of iterations used for scanning all the data.

Paramètres de réponseResponse parameters

  • « Data » : données retournées."data": the returned data. Va contenir jusqu’à « Limit » le nombre d’enregistrements de chaque itération.Will contain up to "limit" number of records each iteration. S’il y a plus d’enregistrements à extraire (hasNext = true), les derniers enregistrements seront supprimés pour s’assurer que toutes les données ne sont répertoriées qu’une seule fois.If there are more records to be pulled (hasNext=true), the last few records will be dropped to ensure that all data is listed only once.
  • « hasNext » : valeur booléenne."hasNext": Boolean. Indique si une autre itération sur les données est nécessaire.Denotes whether another iteration on the data is needed.
  • « nextQueryFilters » : si une autre itération est nécessaire, elle contient la requête JSON consécutive à exécuter."nextQueryFilters": If another iteration is needed, it contains the consecutive JSON query to be run. Utilisez-le comme paramètre « Filters » dans la requête suivante.Use this as the "filters" parameter in the next request.

L’exemple Python suivant obtient toutes les activités du jour précédent à partir d’Exchange Online.The following Python example gets all the activities from the past day from Exchange Online.

import requests
import json
ACTIVITIES_URL = 'https://<your_tenant>.<tenant_region>.contoso.com/api/v1/activities/'

your_token = '<your_token>'
headers = {
'Authorization': 'Token {}'.format(your_token),
}

filters = {
  # optionally, edit to match your filters
  'date': {'gte_ndays': 1},
  'service': {'eq': [20893]}
}
request_data = {
  'filters': filters,
  'isScan': True
}

records = []
has_next = True
while has_next:
    content = json.loads(requests.post(ACTIVITIES_URL, json=request_data, headers=headers).content)
    response_data = content.get('data', [])
    records += response_data
    print('Got {} more records'.format(len(response_data)))
    has_next = content.get('hasNext', False)
    request_data['filters'] = content.get('nextQueryFilters')

print('Got {} records in total'.format(len(records)))

Étapes suivantesNext steps

Si vous rencontrez des problèmes, nous sommes là pour vous aider.If you run into any problems, we're here to help. Pour obtenir de l’aide ou une assistance concernant votre produit, veuillez ouvrir un ticket de support.To get assistance or support for your product issue, please open a support ticket.