interfejs API REST Defender for Cloud Apps

Artykuł
11/28/2024

W tym artykule opisano sposób interakcji z Defender for Cloud Apps za pośrednictwem protokołu HTTPS.

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

Przekazywanie plików dziennika na potrzeby odnajdywania w chmurze
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 for Cloud 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 Defender for Cloud Apps dla dzierżawy, wykonaj następujące kroki:

W portalu Microsoft Defender wybierz pozycję Ustawienia. Następnie wybierz pozycję Cloud Apps. W obszarze System wybierz pozycję Informacje.
Na ekranie Defender for Cloud Apps informacje możesz zobaczyć adres URL interfejsu API.

Po utworzeniu adresu URL interfejsu API dodaj do niego sufiks /api w celu uzyskania adresu 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 for Cloud 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> jest twój 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/podsieć/
Podmioty	GET lub POST	/api/v1/entities/
Pliki	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
ciąg	Ciąg tekstowy
boolowski	Wartość logiczna reprezentująca wartość true/false
liczba całkowita	Liczba całkowita z podpisem 32-bitowym
Sygnatury czasowej	Milisekundy od epoki

Sygnatury czasowe

Wzmianki o znacznikach czasu w interfejsie API Defender for Cloud Apps odnoszą się do sygnatury czasowej Systemu Unix w milisekundach. Ten znacznik czasu jest określany przez liczbę milisekund od 1970-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.

Następujące metody są obsługiwane w przypadku podawania parametru limitu:

Zakodowane w adresie URL (z nagłówkiem Content-Type: application/x-www-form-urlencoded )
Dane formularzy
Treść JSON (z Content-Type: multipart/form-data i odpowiednim nagłówkiem granicy)

Uwaga

Jeśli limit nie zostanie określony, zostanie ustawiona wartość domyślna 100.
Odpowiedzi dla wszystkich żądań złożonych przy użyciu 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ę i operatory, z których można używać filtrów.

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 możliwych do 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 funkcji 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
}'

Operatorów

Uwaga

Nie wszystkie operatory są zgodne ze wszystkimi filtrami.

W poniższej tabeli opisano obsługiwane operatory:

Operator	Typ odpowiedzi	Opis
Contains	lista ciągów	Zwraca wszystkie odpowiednie rekordy zawierające jeden z podanych ciągów
deq	lista wartości	Zwraca wszystkie rekordy zawierające jedną wartość, która nie jest równa podanej wartości
element potomny	lista wartości	Zwraca wszystkie odpowiednie rekordy pasujące do wartości lub elementów potomnych
doesnotstartwith	lista ciągów	Zwraca wszystkie odpowiednie rekordy, które nie zaczynają się od każdego z podanych ciągów
endswith	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	numer	Zwraca wszystkie rekordy z datą późniejszą niż N dni temu
isnotset	boolowski	Po ustawieniu wartości "true" zwraca wszystkie odpowiednie rekordy, które nie mają wartości w określonym polu
isset	boolowski	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	numer	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
zakres	lista obiektów zawierających pola "start" i "end"	Zwraca wszystkie rekordy w jednym z podanych zakresów
rozpoczyna się	lista ciągów	Zwraca wszystkie odpowiednie rekordy rozpoczynające się od jednego z podanych ciągów
startswithsingle	ciąg	Zwraca wszystkie odpowiednie rekordy rozpoczynające się od podanej ciągu
Tekst	ciąg	Wykonuje wyszukiwanie pełnotekstowe wszystkich rekordów

Następne kroki

Uwierzytelnianie interfejsu API

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.

Udostępnij za pośrednictwem