API REST Cloud App SecurityCloud App Security REST 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.

Cet article explique comment interagir avec Cloud App Security via HTTPs.This article describes how to interact with Cloud App Security over HTTPS.

L’API Microsoft Cloud App Security fournit l’accès par programmation à Cloud App Security par le biais de points de terminaison API REST.The Microsoft Cloud App Security API provides programmatic access to Cloud App Security through REST API endpoints. Les applications peuvent utiliser l’API pour effectuer des opérations de lecture et de mise à jour sur les objets et les données Cloud App Security.Applications can use the API to perform read and update operations on Cloud App Security data and objects. Par exemple, l’API Cloud App Security prend en charge les opérations courantes suivantes pour un objet utilisateur :For example, the Cloud App Security API supports the following common operations for a user object:

  • Charger des fichiers journaux pour Cloud DiscoveryUpload log files for Cloud Discovery
  • Générer un script de blocageGenerate block scripts
  • Répertorier les activités et les alertesList activities and alerts
  • Ignorer ou résoudre les alertesDismiss or resolve alerts

Structure de l’URL de l’APIAPI URL structure

Pour utiliser l’API Cloud App Security, vous devez d’abord obtenir l’URL de l’API à partir de votre locataire.To use the Cloud App Security API, you must first obtain the API URL from your tenant. L’URL de l’API utilise le format suivant : https://<portal_url>/api/<endpoint> .The API URL uses the following format: https://<portal_url>/api/<endpoint>.

Pour obtenir l’URL du portail Cloud App Security pour votre locataire, procédez comme suit :To obtain the Cloud App Security portal URL for your tenant, do the following steps:

  1. Dans le portail Cloud App Security, cliquez sur l’icône de point d’interrogation dans la barre de menus.In the Cloud App Security portal, click the question mark icon in the menu bar. Ensuite, sélectionnez À propos de.Then, select About.

    cliquez sur À propos de

  2. Dans l’écran Cloud App Security à propos de, vous pouvez voir l’URL du portail.In the Cloud App Security about screen, you can see the portal url.

    Afficher votre centre de données

Une fois que vous avez l’URL du portail, ajoutez /api -lui le suffixe pour obtenir votre URL d’API.Once you have the portal url, add the /api suffix to it to obtain your API URL. Par exemple, si l’URL de votre portail est https://mytenant.us2.contoso.com , votre URL d’API est https://mytenant.us2.contoso.com/api .For example, if your portal's URL is https://mytenant.us2.contoso.com, then your API URL is https://mytenant.us2.contoso.com/api.

Jetons d’APIAPI tokens

Cloud App Security nécessite un jeton d’API dans l’en-tête de toutes les requêtes d’API sur le serveur, comme suit :Cloud App Security requires an API token in the header of all API requests to the server, such as the following:

Authorization: Token <your_token_key>

<your_token_key> est votre jeton d’API personnel.Where <your_token_key> is your personal API token.

Pour plus d’informations sur les jetons d’API, consultez gestion des jetons d’API.For more information about API tokens, see Managing API tokens.

 ExempleExample

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

Quelles sont les actions prises en charge ?What actions are supported?

Le tableau suivant décrit les actions prises en charge :The following table describes the actions supported:

RessourceResource Verbes HTTPHTTP verbs Itinéraires URIURI routes
DécouverteDiscovery Obtient, publie ou PUTGET, POST, or PUT /api/v1/discovery//api/v1/discovery/
Enrichissement des donnéesData enrichment POSTPOST /api/subnet//api/subnet/
ActivitésActivities GET ou POSTGET or POST /api/v1/activities//api/v1/activities/
AlertesAlerts GET ou POSTGET or POST /api/v1/alerts//api/v1/alerts/
EntitésEntities GET ou POSTGET or POST /api/v1/entities//api/v1/entities/
FilesFiles GET ou POSTGET or POST /api/v1/files//api/v1/files/

Où la ressource représente un groupe d’entités associées.Where Resource represents a group of related entities.

Quels sont les types de champs pris en charge ?What field types are supported?

Le tableau suivant décrit les types de champs pris en charge :The following table describes the supported field types:

ChampField DescriptionDescription
stringstring Chaîne textuelleA textual string
booleanboolean Valeur booléenne représentant true/falseA boolean value representing true/false
entierinteger Entier 32 bits signé32-bit signed integer
timestamptimestamp Millisecondes écoulées depuis l’époqueMilliseconds since epoch

LimitesLimits

Vous pouvez choisir de limiter vos demandes en fournissant un paramètre Limit dans la demande.You can choose to limit your requests by providing a limit parameter in the request.

Les méthodes suivantes sont prises en charge pour fournir le paramètre Limit :The following methods are supported for providing the limit parameter:

  • Encodé URL (avec Content-Type: application/x-www-form-urlencoded en-tête)URL-encoded (with Content-Type: application/x-www-form-urlencoded header)
  • Données de formulaireForm data
  • Corps JSON (avec Content-Type: multipart/form-data et un en-tête de limite approprié)JSON body (with Content-Type: multipart/form-data and an appropriate boundary header)

Notes

  • Si aucune limite n’est spécifiée, la valeur par défaut 100 est définie.If no limit is provided a default of 100 will be set.
  • Les réponses pour toutes les requêtes effectuées avec le jeton d’API sont limitées à un maximum de 100 éléments.Responses for all requests made with the API token are limited to a maximum of 100 items.
  • La limite de limitation pour toutes les demandes d’API est de 30 demandes par minute par client.The throttle limit for all API requests is 30 requests per minute per tenant.

FiltresFilters

Lorsque vous avez un grand nombre de résultats, il est utile d’affiner les demandes à l’aide de filtres.When you have a large number of results, you'll find it useful to fine-tune requests using filters. Cette section décrit la structure des opérateurs et, qui peuvent être utilisés avec les filtres.This section describes the structure of, and operators that can be used with, filters.

StructureStructure

Certains de nos points de terminaison d’API prennent en charge les filtres lors de l’exécution de requêtes.Some of our API endpoints support filters when performing queries. Dans les sections correspondantes, vous trouverez une référence qui répertorie tous les champs filtrables disponibles et les opérateurs pris en charge pour cette ressource.In their relevant sections, you will find a reference listing all available filterable fields and supported operators for that resource.

La plupart des filtres prennent en charge plusieurs valeurs pour vous fournir des requêtes puissantes.Most filters support multiple values to provide you with powerful queries. Lors de la combinaison des filtres et des opérateurs, nous utilisons et comme opérateur logique entre les filtres.When combining filters and operators we use AND as the logical operator between the filters.

 ExempleExample

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

OpérateursOperators

Notes

Tous les opérateurs ne sont pas compatibles avec tous les filtres.Not all operators are compatible with all filters.

Le tableau suivant décrit les opérateurs pris en charge :The following table describes the supported operators:

OpérateurOperator Type de réponseResponse type DescriptionDescription
containscontains Liste de chaîneslist of strings Retourne tous les enregistrements pertinents contenant l’une des chaînes fournies.Returns all relevant records containing one of the provided strings
deqdeq liste de valeurslist of values Retourne tous les enregistrements qui contiennent une valeur qui n’est pas égale à l’une des valeurs fournies.Returns all records who contain one value that does not equal one the provided values
descendantofdescendantof liste de valeurslist of values Retourne tous les enregistrements pertinents correspondant aux valeurs ou descendants de ceux-ciReturns all relevant records matching values or descendants of them
doesnotstartwithdoesnotstartwith Liste de chaîneslist of strings Retourne tous les enregistrements pertinents ne commençant pas par chacune des chaînes fourniesReturns all relevant records not starting with each of the provided strings
endswithendswith Liste de chaîneslist of strings Retourne tous les enregistrements pertinents se terminant par l’une des chaînes fournies.Returns all relevant records ending with one of the provided strings
eqeq liste de valeurslist of values Retourne tous les enregistrements pertinents contenant l’une des valeurs fournies.Returns all relevant records containing one of the provided values
gtgt valeur uniquesingle value Retourne tous les enregistrements dont la valeur est supérieure à la valeur fournie.Returns all records whose value is greater than the provided value
GTEgte valeur uniquesingle value Retourne tous les enregistrements dont la valeur est supérieure ou égale à la valeur fournie.Returns all records whose value is greater than or equal to the provided value
gte_ndaysgte_ndays nombrenumber Retourne tous les enregistrements dont la date est postérieure à N joursReturns all records with date later than N days ago
isnotsetisnotset booleanboolean Quand la valeur est définie sur « true », retourne tous les enregistrements pertinents qui n’ont pas de valeur dans le champ spécifiéWhen set to "true", returns all relevant records that don't have a value in the specified field
issetisset booleanboolean Quand la valeur est définie sur « true », retourne tous les enregistrements pertinents qui ont une valeur dans le champ spécifiéWhen set to "true", returns all relevant records that have a value in the specified field
ltlt valeur uniquesingle value Retourne tous les enregistrements dont la valeur est inférieure à la valeur fournie.Returns all records whose value is less than the provided value
ltelte valeur uniquesingle value Retourne tous les enregistrements dont la valeur est inférieure ou égale à la valeur fournie.Returns all records whose value is less than or equal to the provided value
lte_ndayslte_ndays nombrenumber Retourne tous les enregistrements dont la date est antérieure à N joursReturns all records with date earlier than N days ago
ncontainsncontains Liste de chaîneslist of strings Retourne tous les enregistrements pertinents qui ne contiennent pas l’une des chaînes fournies.Returns all relevant records not containing one of the provided strings
ndescendantofndescendantof liste de valeurslist of values Retourne tous les enregistrements pertinents qui ne correspondent pas à des valeurs ou descendants de ceux-ciReturns all relevant records not matching values or descendants of them
NEQneq liste de valeurslist of values Retourne tous les enregistrements pertinents qui ne contiennent pas toutes les valeurs fournies.Returns all relevant records not containing all the provided values
rangerange liste d’objets contenant les champs « Start » et « end »list of objects containing "start" and "end" fields Retourne tous les enregistrements dans l’une des plages fourniesReturns all records within one of the provided ranges
startswithstartswith Liste de chaîneslist of strings Retourne tous les enregistrements pertinents commençant par l’une des chaînes fourniesReturns all relevant records starting with one of the provided strings
startswithsinglestartswithsingle stringstring Retourne tous les enregistrements pertinents commençant par la chaîne fournie.Returns all relevant records starting with the provided string
texttext stringstring Effectue une recherche en texte intégral sur tous les enregistrementsPerforms a full-text search of all 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.