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 :
Dans le portail Microsoft Defender, sélectionnez Paramètres. Choisissez ensuite Logiciels cloud. Sous Système, sélectionnez À propos.
Dans Defender for Cloud Apps à propos de l’écran, vous pouvez voir l’URL de l’API.
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>
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 ?
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/ |
Où 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.