API REST Defender pour Cloud Apps

Article
11/28/2024

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

L’API Microsoft Defender for Cloud Apps fournit un accès par programmation à 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 Defender for Cloud Apps données et objets. 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 la découverte du cloud
Générer des scripts de bloc
Répertorier les activités et les alertes
Ignorer ou résoudre les alertes

Structure d’URL d’API

Pour utiliser l’API Defender for Cloud Apps, vous devez d’abord obtenir l’URL de l’API auprès de votre locataire. 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 locataire, procédez comme suit :

Dans le portail Microsoft Defender, sélectionnez Paramètres. Choisissez ensuite Cloud Apps. Sous Système, sélectionnez À propos de.
Dans l’écran Defender for Cloud Apps about, vous pouvez voir l’URL de l’API.

Une fois que vous avez l’URL de l’API, ajoutez-y le /api suffixe pour obtenir votre URL d’API. Par exemple, si l’URL de votre portail est https://mytenant.us2.contoso.com, votre URL d’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>

Où <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 ?

Le tableau suivant décrit les actions prises en charge :

Resource	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/

Où Resource 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 champs pris en charge :

Field	Description
string	Chaîne textuelle
valeur booléenne	Valeur booléenne représentant true/false
entier	Entier signé 32 bits
horodatage	Millisecondes depuis l’époque

Timestamps

Les mentions d’horodatages dans l’API Defender for Cloud Apps font référence à l’horodatage Unix en millisecondes. Ce timestamp est déterminé par le nombre de millisecondes depuis 1970-01-01 00:00:00. Vous pouvez utiliser l’applet de commande PowerShell get-date pour convertir des dates en horodatages.

Limites

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

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

Encodé 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, la valeur par défaut est 100.
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 et par locataire.

Filtres

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

Structure

Certains de nos points de terminaison d’API prennent en charge les filtres lors de l’exécution de requêtes. Dans les sections correspondantes, 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 à une des valeurs fournies
descendantof	liste de valeurs	Retourne tous les enregistrements pertinents correspondant à des 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	Retourne tous les enregistrements pertinents contenant l’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 postérieure à N jours
isnotset	valeur booléenne	Lorsqu’il est défini sur « true », retourne tous les enregistrements pertinents qui n’ont pas de valeur dans le champ spécifié
isset	valeur booléenne	Lorsque la valeur est « true », 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
ncontains	liste de chaînes	Retourne tous les enregistrements pertinents qui ne contiennent pas l’une des chaînes fournies
ndescendantof	liste de valeurs	Retourne tous les enregistrements pertinents ne correspondant pas aux valeurs ou descendants d’entre eux
neq	liste de valeurs	Retourne tous les enregistrements pertinents qui ne contiennent pas toutes les valeurs fournies
plage	liste d’objets contenant les champs « start » et « end »	Retourne tous les enregistrements dans l’une des plages fournies
startswith	liste de chaînes	Retourne tous les enregistrements pertinents en commençant par l’une des chaînes fournies
startswithsingle	string	Retourne tous les enregistrements pertinents commençant par la chaîne fournie.
text	string	Effectue une recherche en texte intégral de tous les enregistrements

Étapes suivantes

Authentification d’API

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, ouvrez un ticket de support.

Partager via