Cloud App Security REST APICloud App Security REST API

Gäller för: Microsoft Cloud App SecurityApplies to: Microsoft Cloud App Security

Viktigt

Hot skydds produkt namn från Microsoft ändras.Threat protection product names from Microsoft are changing. Läs mer om det här och andra uppdateringar här.Read more about this and other updates here. Vi kommer att uppdatera namn i produkter och i dokumenten inom en snar framtid.We'll be updating names in products and in the docs in the near future.

Den här artikeln beskriver hur du interagerar med Cloud App Security över HTTPS.This article describes how to interact with Cloud App Security over HTTPS.

Microsoft Cloud App Security API ger programmatisk åtkomst till Cloud App Security via REST API slut punkter.The Microsoft Cloud App Security API provides programmatic access to Cloud App Security through REST API endpoints. Program kan använda API: et för att utföra Läs-och uppdaterings åtgärder på Cloud App Security data och objekt.Applications can use the API to perform read and update operations on Cloud App Security data and objects. Exempelvis stöder Cloud App Security-API följande vanliga åtgärder för ett användar objekt:For example, the Cloud App Security API supports the following common operations for a user object:

  • Ladda upp loggfiler för Cloud DiscoveryUpload log files for Cloud Discovery
  • Generera block skriptGenerate block scripts
  • Lista aktiviteter och aviseringarList activities and alerts
  • Stäng eller lös aviseringarDismiss or resolve alerts

API-webbadresstrukturAPI URL structure

Om du vill använda Cloud App Security API måste du först hämta API-URL: en från din klient.To use the Cloud App Security API, you must first obtain the API URL from your tenant. API-URL: en använder följande format: https://<portal_url>/api/<endpoint> .The API URL uses the following format: https://<portal_url>/api/<endpoint>.

Gör så här för att hämta Cloud App Security portal-URL för din klient:To obtain the Cloud App Security portal URL for your tenant, do the following steps:

  1. I Cloud App Security-portalen klickar du på frågetecknet i meny raden.In the Cloud App Security portal, click the question mark icon in the menu bar. Välj sedan om.Then, select About.

    Klicka på om

  2. På skärmen Cloud App Security om kan du se portalens URL.In the Cloud App Security about screen, you can see the portal url.

    Visa ditt data Center

När du har portal-URL: en ska du lägga till /api suffixet till den för att hämta din API-URL.Once you have the portal url, add the /api suffix to it to obtain your API URL. Till exempel, om portalens URL är https://mytenant.us2.contoso.com , är din API-URL 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.

API-tokenAPI tokens

Cloud App Security kräver en API-token i rubriken för alla API-begäranden till servern, till exempel följande: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>

Där <your_token_key> är din personliga API-token.Where <your_token_key> is your personal API token.

Mer information om API-token finns i Hantera API-token.For more information about API tokens, see Managing API tokens.

ExempelExample

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

Vilka åtgärder stöds?What actions are supported?

Följande tabell beskriver de åtgärder som stöds:The following table describes the actions supported:

ResursResource HTTP-verbHTTP verbs URI-vägarURI routes
IdentifieringDiscovery Hämta, posta eller placeraGET, POST, or PUT /api/v1/discovery//api/v1/discovery/
DataberikandeData enrichment POSTPOST /api/subnet//api/subnet/
AktiviteterActivities GET eller POSTGET or POST /api/v1/activities//api/v1/activities/
AviseringarAlerts GET eller POSTGET or POST /api/v1/alerts//api/v1/alerts/
EntiteterEntities GET eller POSTGET or POST /api/v1/entities//api/v1/entities/
FilesFiles GET eller POSTGET or POST /api/v1/files//api/v1/files/

Där resurs representerar en grupp relaterade entiteter.Where Resource represents a group of related entities.

Vilka fält typer stöds?What field types are supported?

I följande tabell beskrivs de fält typer som stöds:The following table describes the supported field types:

FältField BeskrivningDescription
strängstring En text strängA textual string
booleanboolean Ett booleskt värde som representerar TRUE/FALSEA boolean value representing true/false
heltalinteger 32-bitars signerat heltal32-bit signed integer
timestamptimestamp Millisekunder sedan epokMilliseconds since epoch

GränserLimits

Du kan välja att begränsa dina begär Anden genom att ange en gräns parameter i begäran.You can choose to limit your requests by providing a limit parameter in the request.

Följande metoder stöds för att tillhandahålla parametern Limit:The following methods are supported for providing the limit parameter:

  • URL-kodad (med Content-Type: application/x-www-form-urlencoded rubrik)URL-encoded (with Content-Type: application/x-www-form-urlencoded header)
  • Formulär dataForm data
  • JSON-brödtext (med Content-Type: multipart/form-data och en lämplig avgränsnings rubrik)JSON body (with Content-Type: multipart/form-data and an appropriate boundary header)

Anteckning

  • Om ingen gräns anges anges standardvärdet 100.If no limit is provided a default of 100 will be set.
  • Svar för alla begär Anden som görs med API-token är begränsade till högst 100 objekt.Responses for all requests made with the API token are limited to a maximum of 100 items.
  • Begränsnings gränsen för alla API-begäranden är 30 begär Anden per minut per klient.The throttle limit for all API requests is 30 requests per minute per tenant.

FilterFilters

När du har ett stort antal resultat är det bra att finjustera förfrågningar med hjälp av filter.When you have a large number of results, you'll find it useful to fine-tune requests using filters. I det här avsnittet beskrivs strukturen för och operatorer som kan användas med filter.This section describes the structure of, and operators that can be used with, filters.

StrukturStructure

Några av våra API-slutpunkter stöder filter när du utför frågor.Some of our API endpoints support filters when performing queries. I de relevanta avsnitten hittar du en referens över alla tillgängliga filter bara fält och operatörer som stöds för den resursen.In their relevant sections, you will find a reference listing all available filterable fields and supported operators for that resource.

De flesta filter har stöd för flera värden för att ge dig kraftfulla frågor.Most filters support multiple values to provide you with powerful queries. När du kombinerar filter och operatorer används och som logisk operator mellan filtren.When combining filters and operators we use AND as the logical operator between the filters.

ExempelExample

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
}'

OperatorerOperators

Anteckning

Alla operatorer är inte kompatibla med alla filter.Not all operators are compatible with all filters.

I följande tabell beskrivs de operatorer som stöds:The following table describes the supported operators:

OperatorOperator SvarstypResponse type BeskrivningDescription
innehållercontains lista över strängarlist of strings Returnerar alla relevanta poster som innehåller en av de angivna strängarnaReturns all relevant records containing one of the provided strings
deqdeq lista med värdenlist of values Returnerar alla poster som innehåller ett värde som inte är lika med det angivna värdenaReturns all records who contain one value that does not equal one the provided values
descendantofdescendantof lista med värdenlist of values Returnerar alla relevanta poster som matchar värden eller underordnade objektReturns all relevant records matching values or descendants of them
doesnotstartwithdoesnotstartwith lista över strängarlist of strings Returnerar alla relevanta poster som inte börjar med var och en av de angivna strängarnaReturns all relevant records not starting with each of the provided strings
EndsWithendswith lista över strängarlist of strings Returnerar alla relevanta poster som slutar med en av de angivna strängarnaReturns all relevant records ending with one of the provided strings
eqeq lista med värdenlist of values Returnerar alla relevanta poster som innehåller ett av de angivna värdenaReturns all relevant records containing one of the provided values
gtgt enskilt värdesingle value Returnerar alla poster vars värde är större än det angivna värdetReturns all records whose value is greater than the provided value
gtegte enskilt värdesingle value Returnerar alla poster vars värde är större än eller lika med det angivna värdetReturns all records whose value is greater than or equal to the provided value
gte_ndaysgte_ndays antalnumber Returnerar alla poster med datum senare än N dagar sedanReturns all records with date later than N days ago
isnotsetisnotset booleanboolean När värdet är "true" returnerar alla relevanta poster som inte har något värde i det angivna fältetWhen set to "true", returns all relevant records that don't have a value in the specified field
issetisset booleanboolean När värdet är "true" returnerar alla relevanta poster som har ett värde i det angivna fältetWhen set to "true", returns all relevant records that have a value in the specified field
ltlt enskilt värdesingle value Returnerar alla poster vars värde är mindre än det angivna värdetReturns all records whose value is less than the provided value
samtlte enskilt värdesingle value Returnerar alla poster vars värde är mindre än eller lika med det angivna värdetReturns all records whose value is less than or equal to the provided value
lte_ndayslte_ndays antalnumber Returnerar alla poster med datum som är tidigare än N dagar sedanReturns all records with date earlier than N days ago
ncontainsncontains lista över strängarlist of strings Returnerar alla relevanta poster som inte innehåller någon av de angivna strängarnaReturns all relevant records not containing one of the provided strings
ndescendantofndescendantof lista med värdenlist of values Returnerar alla relevanta poster som inte matchar värden eller underordnade objektReturns all relevant records not matching values or descendants of them
neqneq lista med värdenlist of values Returnerar alla relevanta poster som inte innehåller alla angivna värdenReturns all relevant records not containing all the provided values
intervallrange lista med objekt som innehåller fälten Start och slutlist of objects containing "start" and "end" fields Returnerar alla poster inom ett av de angivna intervallenReturns all records within one of the provided ranges
StartsWithstartswith lista över strängarlist of strings Returnerar alla relevanta poster som börjar med en av de angivna strängarnaReturns all relevant records starting with one of the provided strings
startswithsinglestartswithsingle strängstring Returnerar alla relevanta poster som börjar med den angivna strängenReturns all relevant records starting with the provided string
texttext strängstring Utför en full texts ökning av alla posterPerforms a full-text search of all records

Nästa stegNext steps

Om du stöter på problem är vi här för att hjälpa dig.If you run into any problems, we're here to help. Öppna ett support ärendeom du vill ha hjälp eller support för produkt problemet.To get assistance or support for your product issue, please open a support ticket.