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 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 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:
W witrynie Microsoft Defender Portal wybierz pozycję Ustawienia. Następnie wybierz pozycję Aplikacje w chmurze. W obszarze System wybierz pozycję Informacje.
Na ekranie Defender dla Chmury Aplikacje można wyświetlić adres URL interfejsu API.
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/ |
| 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 |
|---|---|
| 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-dataodpowiednim 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.