API REST Defender pour le cloud Apps

Cet article explique comment interagir avec Defender for Cloud Apps via HTTPS.

L’API Microsoft Defender for Cloud Apps fournit un accès programmatique à Defender for Cloud Apps via des points de terminaison d’API REST. Les applications peuvent utiliser l’API pour effectuer des opérations de lecture et de mise à jour sur les données et les objets Defender for Cloud Apps. Par exemple, l’API Defender for Cloud Apps prend en charge les opérations courantes suivantes pour un objet utilisateur :

  • Charger des fichiers journaux pour Cloud Discovery
  • Générer un script de blocage
  • Lister les activités et les alertes
  • Ignorer ou résoudre les alertes

Structure URL de l'API

Pour utiliser l’API Defender for Cloud Apps, vous devez d’abord obtenir l’URL de l’API de votre client. L’URL de l’API utilise le format suivant : https://<portal_url>/api/<endpoint>.

Pour obtenir l’URL de l’API Defender for Cloud Apps pour votre client, procédez comme suit :

  1. Dans le portail Microsoft Defender, sélectionnez Paramètres. Choisissez ensuite Logiciels cloud. Sous Système, sélectionnez À propos.

  2. Dans Defender for Cloud Apps à propos de l’écran, vous pouvez voir l’URL de l’API.

    View your data center.

Une fois que vous avez l’URL de l’API, ajoutez-y le suffixe /api pour obtenir votre URL d’API. Par exemple, si l’URL de votre portail est https://mytenant.us2.contoso.com, l’URL de votre API est https://mytenant.us2.portal.cloudappsecurity.com/api.

Jetons d’API

Defender for Cloud Apps nécessite un jeton d’API dans l’en-tête de toutes les demandes d’API adressées au serveur, par exemple :

Authorization: Token <your_token_key>

<your_token_key> est votre jeton d’API personnel.

Pour plus d’informations sur les jetons d’API, consultez Gestion des jetons d’API.

Jetons d’API - exemple

curl -XGET -H "Authorization:Token <your_token_key>" "https://<tenant_id>.<tenant_region>.portal.cloudappsecurity.com/api/example-endpoint"

Quelles sont les actions prises en charge ?

La table suivante décrit les actions sont prises en charge :

Ressource Verbes HTTP Itinéraires d’URI
Activités GET ou POST /api/v1/activities/
Alertes GET ou POST /api/v1/alerts/
Enrichissement des données GET, POST, ou DELETE /api/subnet/
Entités GET ou POST /api/v1/entities/
Fichiers GET ou POST /api/v1/files/

Ressource représente un groupe d’entités associées.

Quels types de champs sont pris en charge ?

Le tableau suivant décrit les types de champ pris en charge :

Champ Description
string Une chaîne textuelle
booléen Une valeur booléenne représentant vrai/faux
entier Entier 32 bits signé
timestamp Millisecondes depuis l’époque

Horodatages

Les mentions d’horodatages dans l’API Defender pour le cloud Apps font référence à l’horodateur Unix en millisecondes. Cet horodatage est déterminé par le nombre de millisecondes depuis 1970-01-01 0:00:00. Vous pouvez utiliser le cmdlet get-date de PowerShell pour convertir des dates en horodatages.

Limites

Vous pouvez choisir de limiter vos demandes en fournissant un paramètre de limite dans la requête.

Les méthodes suivantes sont prises en charge pour fournir le paramètre limite :

  • Codé en URL (avec Content-Type: application/x-www-form-urlencoded en-tête)
  • Données de formulaires
  • Corps JSON (avec Content-Type: multipart/form-data et un en-tête de limite approprié)

Remarque

  • Si aucune limite n’est fournie, une valeur par défaut de 100 est définie.
  • Les réponses pour toutes les demandes effectuées avec le jeton d’API sont limitées à un maximum de 100 éléments.
  • La limite de limitation pour toutes les demandes d’API est de 30 requêtes par minute par client.

Filtres

Lorsque vous avez un grand nombre de résultats, vous trouverez qu’il est utile d’ajuster les requêtes à l’aide de filtres. Cette section décrit la structure des opérateurs qui peuvent être utilisés avec des filtres.

Structure

Certains de nos points de terminaison d’API prennent en charge les filtres lors de l’exécution de requêtes. Dans leurs sections pertinentes, vous trouverez une référence répertoriant tous les champs filtrables disponibles et les opérateurs pris en charge pour cette ressource.

La plupart des filtres prennent en charge plusieurs valeurs pour vous fournir des requêtes puissantes. Lors de la combinaison de filtres et d’opérateurs, nous utilisons AND comme opérateur logique entre les filtres.

Filtres : exemple

curl -XGET -H "Authorization:Token <your_token_key>" "https://<tenant_id>.<tenant_region>.portal.cloudappsecurity.com/api/example-endpoint" -d '{
  "filters": {
    "some.field": {
      "eq": ["value1", "value2"],
      "isset": true
    },
    "some.field2": {
      "gte": 5
    }
  },
  "skip": 5,
  "limit": 10
}'

Opérateurs

Remarque

Tous les opérateurs ne sont pas compatibles avec tous les filtres.

Le tableau suivant décrit les opérateurs pris en charge :

Opérateur Type de réponse Description
contains Liste de chaînes Retourne tous les enregistrements pertinents contenant l’une des chaînes fournies
deq liste de valeurs Retourne tous les enregistrements qui contiennent une valeur qui n’est pas égale aux valeurs fournies
descendantof liste de valeurs Retourne tous les enregistrements pertinents correspondant aux valeurs ou descendants d’entre eux
doesnotstartwith Liste de chaînes Retourne tous les enregistrements pertinents qui ne commencent pas par chacune des chaînes fournies
endswith Liste de chaînes Retourne tous les enregistrements pertinents se terminant par l’une des chaînes fournies
eq liste de valeurs Renvoie tous les enregistrements pertinents contenant une des valeurs fournies
gt valeur unique Retourne tous les enregistrements dont la valeur est supérieure à la valeur fournie
gte valeur unique Retourne tous les enregistrements dont la valeur est supérieure ou égale à la valeur fournie
gte_ndays number Retourne tous les enregistrements dont la date est antérieure à N jours
isnotset booléen Lorsque la valeur est « vrai », retourne tous les enregistrements pertinents qui n’ont pas de valeur dans le champ spécifié
isset booléen Lorsque la valeur est « vrai », retourne tous les enregistrements pertinents qui ont une valeur dans le champ spécifié
lt valeur unique Retourne tous les enregistrements dont la valeur est inférieure à la valeur fournie
lte valeur unique Retourne tous les enregistrements dont la valeur est inférieure ou égale à la valeur fournie
lte_ndays number Retourne tous les enregistrements dont la date est antérieure à N jours il y a
ncontains Liste de chaînes Renvoie tous les enregistrements pertinents ne contenant pas une des chaines fournies
ndescendantof liste de valeurs Retourne tous les enregistrements pertinents qui ne correspondent pas aux valeurs ni aux descendants d’entre eux
neq liste de valeurs Renvoie tous les enregistrements pertinents ne contenant pas toutes les valeurs fournies
range liste d’objets contenant des champs « start » et « end » Retourne tous les enregistrements dans l’une des plages fournies
startswith Liste de chaînes Renvoie tous les enregistrements pertinents qui commencent avec une des chaînes fournies
startswithsingle string Renvoie tous les enregistrements pertinents qui commencent avec la chaîne fournie
texte string Effectue une recherche en texte intégral de tous les enregistrements

Étapes suivantes

Si vous rencontrez des problèmes, nous sommes là pour vous aider. Pour obtenir de l’aide ou du support pour votre problème de produit, veuillez ouvrir un ticket de support.