interfejs API REST usługi Defender dla Chmury Apps

W tym artykule opisano sposób interakcji z aplikacjami Defender dla Chmury za pośrednictwem protokołu HTTPS.

Interfejs API usługi Microsoft Defender dla Chmury Apps zapewnia programowy dostęp do aplikacji Defender dla Chmury za pośrednictwem punktów końcowych interfejsu API REST. Aplikacje mogą używać interfejsu API do wykonywania operacji odczytu i aktualizacji na danych i obiektach usługi Defender dla Chmury Apps. Na przykład interfejs API usługi Defender dla Chmury Apps obsługuje następujące typowe operacje dla obiektu użytkownika:

  • Przekazywanie plików dziennika dla rozwiązania Cloud Discovery
  • Generowanie skryptów blokowych
  • Wyświetlanie listy działań i alertów
  • Odrzucanie lub rozwiązywanie alertów

Struktura adresu URL interfejsu API

Aby użyć interfejsu API Defender dla Chmury Apps, musisz najpierw uzyskać adres URL interfejsu API z dzierżawy. Adres URL interfejsu API używa następującego formatu: https://<portal_url>/api/<endpoint>.

Aby uzyskać adres URL interfejsu API usługi Defender dla Chmury Apps dla dzierżawy, wykonaj następujące czynności:

  1. W witrynie Microsoft Defender Portal wybierz pozycję Ustawienia. Następnie wybierz pozycję Aplikacje w chmurze. W obszarze System wybierz pozycję Informacje.

  2. Na ekranie Defender dla Chmury Aplikacje można wyświetlić adres URL interfejsu API.

    View your data center.

Po utworzeniu adresu URL interfejsu API dodaj /api do niego sufiks, aby uzyskać adres URL interfejsu API. Jeśli na przykład adres URL portalu to https://mytenant.us2.contoso.com, adres URL interfejsu API to https://mytenant.us2.portal.cloudappsecurity.com/api.

Tokeny interfejsu API

Defender dla Chmury Apps wymaga tokenu interfejsu API w nagłówku wszystkich żądań interfejsu API do serwera, takich jak:

Authorization: Token <your_token_key>

Gdzie <your_token_key> to osobisty token interfejsu API.

Aby uzyskać więcej informacji na temat tokenów interfejsu API, zobacz Zarządzanie tokenami interfejsu API.

Tokeny interfejsu API — przykład

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

Jakie akcje są obsługiwane?

W poniższej tabeli opisano obsługiwane akcje:

Zasób Czasowniki HTTP Trasy identyfikatora URI
Działania GET lub POST /api/v1/activities/
Alerty GET lub POST /api/v1/alerts/
Wzbogacanie danych GET, POST lub DELETE /api/subnet/
Jednostki GET lub POST /api/v1/entities/
Files GET lub POST /api/v1/files/

Gdzie zasób reprezentuje grupę powiązanych jednostek.

Jakie typy pól są obsługiwane?

W poniższej tabeli opisano obsługiwane typy pól:

Pole opis
string Ciąg tekstowy
boolean Wartość logiczna reprezentująca wartość true/false
integer 32-bitowa liczba całkowita ze znakiem
timestamp Milisekundy od epoki

Znaczniki czasu

Wzmianki o znacznikach czasu w interfejsie API usługi Defender dla Chmury Apps odnoszą się do znacznika czasu systemu Unix w milisekundach. Ten znacznik czasu jest określany przez liczbę milisekund od 1970-01-01 01 0:00:00. Możesz użyć polecenia cmdlet get-date programu PowerShell, aby przekonwertować daty na znaczniki czasu.

Limity

Możesz ograniczyć żądania, podając parametr limitu w żądaniu.

Obsługiwane są następujące metody udostępniania parametru limitu:

  • Kodowany adres URL (z nagłówkiem Content-Type: application/x-www-form-urlencoded )
  • Dane formularza
  • Treść JSON (z Content-Type: multipart/form-data odpowiednim nagłówkiem granicy)

Uwaga

  • Jeśli nie zostanie podany limit, zostanie ustawiona wartość domyślna 100.
  • Odpowiedzi dla wszystkich żądań wysyłanych za pomocą tokenu interfejsu API są ograniczone do maksymalnie 100 elementów.
  • Limit ograniczania dla wszystkich żądań interfejsu API wynosi 30 żądań na minutę na dzierżawę.

Filtry

Jeśli masz dużą liczbę wyników, warto dostosować żądania przy użyciu filtrów. W tej sekcji opisano strukturę operatorów, których można używać z filtrami.

Struktura

Niektóre z naszych punktów końcowych interfejsu API obsługują filtry podczas wykonywania zapytań. W odpowiednich sekcjach znajdziesz dokumentację zawierającą listę wszystkich dostępnych pól z możliwością filtrowania i obsługiwanych operatorów dla tego zasobu.

Większość filtrów obsługuje wiele wartości, aby zapewnić zaawansowane zapytania. Podczas łączenia filtrów i operatorów używamy operatora AND jako operatora logicznego między filtrami.

Filtry — przykład

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

Operatory

Uwaga

Nie wszystkie operatory są zgodne ze wszystkimi filtrami.

W poniższej tabeli opisano obsługiwane operatory:

Operator Typ odpowiedzi opis
zawiera lista ciągów Zwraca wszystkie odpowiednie rekordy zawierające jeden z podanych ciągów
Deq lista wartości Zwraca wszystkie rekordy, które zawierają jedną wartość, która nie jest równa podanej wartości
potomny lista wartości Zwraca wszystkie odpowiednie rekordy pasujące do wartości lub elementów potomnych z nich
doesnotstartwith lista ciągów Zwraca wszystkie odpowiednie rekordy, które nie zaczynają się od każdego z podanych ciągów
kończy się na lista ciągów Zwraca wszystkie odpowiednie rekordy kończące się jednym z podanych ciągów
eq lista wartości Zwraca wszystkie odpowiednie rekordy zawierające jedną z podanych wartości
gt pojedyncza wartość Zwraca wszystkie rekordy, których wartość jest większa niż podana wartość
gte pojedyncza wartość Zwraca wszystkie rekordy, których wartość jest większa lub równa podanej wartości
gte_ndays Liczba Zwraca wszystkie rekordy z datą później niż N dni temu
isnotset boolean Po ustawieniu wartości "true" zwraca wszystkie odpowiednie rekordy, które nie mają wartości w określonym polu
Isset boolean Po ustawieniu wartości "true" zwraca wszystkie odpowiednie rekordy, które mają wartość w określonym polu
lt pojedyncza wartość Zwraca wszystkie rekordy, których wartość jest mniejsza niż podana wartość
lte pojedyncza wartość Zwraca wszystkie rekordy, których wartość jest mniejsza lub równa podanej wartości
lte_ndays Liczba Zwraca wszystkie rekordy z datą wcześniejszą niż N dni temu
ncontains lista ciągów Zwraca wszystkie odpowiednie rekordy, które nie zawierają jednego z podanych ciągów
ndescendantof lista wartości Zwraca wszystkie odpowiednie rekordy, które nie pasują do wartości lub elementów potomnych
Neq lista wartości Zwraca wszystkie odpowiednie rekordy, które nie zawierają wszystkich podanych wartości
range lista obiektów zawierających pola "start" i "end" Zwraca wszystkie rekordy w jednym z podanych zakresów
startswith lista ciągów Zwraca wszystkie odpowiednie rekordy rozpoczynające się od jednego z podanych ciągów
startswithsingle string Zwraca wszystkie odpowiednie rekordy rozpoczynające się od podanego ciągu
text string Wykonuje wyszukiwanie pełnotekstowe wszystkich rekordów

Następne kroki

Jeśli napotkasz jakiekolwiek problemy, jesteśmy tutaj, aby pomóc. Aby uzyskać pomoc lub pomoc techniczną dotyczącą problemu z produktem, otwórz bilet pomocy technicznej.