Udostępnij za pośrednictwem

Dokumentacja interfejsu API zarządzania alertami dla lokalnych konsol zarządzania

  • Artykuł

W tym artykule wymieniono interfejsy API REST zarządzania alertami obsługiwane przez lokalne konsole zarządzania usługi Microsoft Defender dla IoT.

alerty (pobieranie informacji o alertach)

Ten interfejs API służy do pobierania wszystkich lub filtrowanych alertów z lokalnej konsoli zarządzania.

identyfikatora URI : lub

POBIERZ

  • żądania
  • odpowiedzi
  • polecenia cURL

parametry zapytania:

Nazwa Opis Przykład Wymagane/opcjonalne
stanu Uzyskaj tylko obsługiwane lub nieobsługiwane alerty. Obsługiwane wartości:
- handled
- unhandled
Wszystkie inne wartości są ignorowane.		 /api/v1/alerts?state=handled Fakultatywny
fromTime Pobierz alerty utworzone od danego czasu w milisekundach z czasu epoki i strefy czasowej UTC. /api/v1/alerts?fromTime=<epoch> Fakultatywny
toTime Pobierz alerty utworzone tylko wcześniej w danym momencie w milisekundach z czasu epoki i w strefie czasowej UTC. /api/v1/alerts?toTime=<epoch> Fakultatywny
siteId Witryna, w której wykryto alert. /api/v1/alerts?siteId=1 Fakultatywny
zoneId Strefa, w której wykryto alert. /api/v1/alerts?zoneId=1 Fakultatywny
sensorId Czujnik, na którym wykryto alert. /api/v1/alerts?sensorId=1 Fakultatywny

Nuta

Być może nie masz identyfikatora witryny i strefy. W takim przypadku należy najpierw wysłać zapytanie do wszystkich urządzeń w celu pobrania identyfikatora witryny i strefy. Aby uzyskać więcej informacji, zobacz Integration API reference for on-premises management consoles (Publiczna wersja zapoznawcza).

UUID (Zarządzanie alertami na podstawie identyfikatora UUID)

Użyj tego interfejsu API, aby podjąć określoną akcję dla określonego alertu wykrytego przez usługę Defender dla IoT.

Możesz na przykład użyć tego interfejsu API, aby utworzyć regułę przekazywania przekazującą dane do usługi QRadar. Aby uzyskać więcej informacji, zobacz Integrate Qradar with Microsoft Defender for IoT(Integracja qradar z usługą Microsoft Defender dla IoT).

identyfikatora URI: /external/v1/alerts/<UUID>

KŁAŚĆ

  • żądania
  • odpowiedzi
  • polecenia cURL

typ: JSON

parametry zapytania:

Nazwa Opis Przykład Wymagane/opcjonalne
identyfikatora UUID Definiuje unikatowy identyfikator (UUID) dla alertu, który chcesz obsługiwać lub obsługiwać i uczyć. /api/v1/alerts/7903F632-H7EJ-4N69-F40F-4B1E689G00Q0 Wymagane

Parametry treści

Nazwa Opis Przykład Wymagane/opcjonalne
akcja Struna handle lub handleAndLearn Wymagane

przykład żądania 

{
    "action": "handle"
}

maintenanceWindow (Tworzenie wykluczeń alertów)

Zarządza oknami obsługi, w których alerty nie będą wysyłane. Ten interfejs API służy do definiowania i aktualizowania czasów zatrzymywania i uruchamiania, urządzeń lub podsieci, które należy wykluczyć podczas wyzwalania alertów, lub definiowania i aktualizowania aparatów usługi Defender for IoT, które powinny zostać wykluczone.

Na przykład podczas okna obsługi możesz zatrzymać dostarczanie alertów wszystkich alertów, z wyjątkiem alertów dotyczących złośliwego oprogramowania na urządzeniach krytycznych.

Okna obsługi zdefiniowane za pomocą interfejsu API maintenanceWindow są wyświetlane w oknie Wykluczenia alertów lokalnej konsoli zarządzania jako reguła wykluczania tylko do odczytu o nazwie z następującą składnią: Maintenance-{token name}-{ticket ID}.

Ważny

Ten interfejs API jest obsługiwany tylko do celów konserwacji i przez ograniczony czas i nie jest przeznaczony do użycia zamiast reguł wykluczania alertów. Użyj tego interfejsu API tylko w przypadku jednorazowych operacji konserwacji tymczasowej.

identyfikatora URI: /external/v1/maintenanceWindow

POST

Tworzy nowe okno obsługi.

  • żądania
  • odpowiedzi
  • polecenia cURL

Parametry treści:

Nazwa Opis Przykład Wymagane/opcjonalne
ticketId Struna. Definiuje identyfikator biletu konserwacji w systemach użytkownika. Upewnij się, że identyfikator biletu nie jest połączony z istniejącym otwartym oknem. 2987345p98234 Wymagane
czasu wygaśnięcia Dodatnia liczba całkowita. Definiuje czas wygaśnięcia (czas wygaśnięcia), czyli czas trwania okna obsługi w minutach. Po zakończeniu zdefiniowanego okresu okno obsługi zostanie zakończone, a system zachowuje się normalnie ponownie. 180 Wymagane
aparatów Tablica JSON ciągów. Określa aparat pomijania alertów w oknie obsługi. Możliwe wartości:

- ANOMALY
- MALWARE
- OPERATIONAL
- POLICY_VIOLATION
- PROTOCOL_VIOLATION		 ANOMALY,OPERATIONAL Fakultatywny
sensorIds Tablica JSON ciągów. Określa, które czujniki mają pomijać alerty w oknie obsługi. Te identyfikatory czujników można uzyskać z urządzeń (Zarządzanie urządzeniami czujników OT) interfejsu API. 1,35,63 Fakultatywny
podsieci Tablica JSON ciągów. Definiuje podsieci w celu pomijania alertów w oknie obsługi. Zdefiniuj każdą podsieć w notacji CIDR. 192.168.0.0/16,138.136.80.0/14,112.138.10.0/8 Fakultatywny

USUNĄĆ

Zamyka istniejące okno obsługi.

  • żądania
  • odpowiedzi
  • polecenia cURL

parametry zapytania:

Nazwa Opis Przykład Wymagane/opcjonalne
ticketId Definiuje identyfikator biletu konserwacji w systemach użytkownika. Upewnij się, że identyfikator biletu jest połączony z istniejącym otwartym oknem. 2987345p98234 Wymagane

POBIERZ

Pobierz dziennik wszystkich otwartych (POST), zamknij (DELETE) i update (PUT) akcji, które zostały wykonane przy użyciu tego interfejsu API do obsługi okien obsługi. T

  • żądania
  • odpowiedzi
  • polecenia cURL

parametry zapytania:

Nazwa Opis Przykład Wymagane/opcjonalne
fromDate Filtruje dzienniki ze wstępnie zdefiniowanej daty i później. Format to YYYY-MM-DD. 2022-08-10 Fakultatywny
toDate Filtruje dzienniki do wstępnie zdefiniowanej daty. Format to YYYY-MM-DD. 2022-08-10 Fakultatywny
ticketId Filtruje dzienniki powiązane z określonym identyfikatorem biletu. 9a5fe99c-d914-4bda-9332-307384fe40bf Fakultatywny
tokenName Filtruje dzienniki powiązane z określoną nazwą tokenu. kwartalne okno sanity Fakultatywny

kody błędów :

Kod Komunikat Opis
200 OK Akcja została ukończona pomyślnie.
204: Brak zawartości Brak danych do pokazania.
400 Nieprawidłowe żądanie Format daty jest niepoprawny.
500 Wewnętrzny błąd serwera Wszelkie inne nieoczekiwane błędy.

KŁAŚĆ

Umożliwia zaktualizowanie czasu trwania okna obsługi po rozpoczęciu procesu konserwacji przez zmianę parametru ttl. Nowa definicja czasu trwania zastępuje poprzednią definicję.

Ta metoda jest przydatna, gdy chcesz ustawić dłuższy czas trwania niż aktualnie skonfigurowany czas trwania. Jeśli na przykład pierwotnie zdefiniowano 180 minut, minęło 90 minut i chcesz dodać kolejne 30 minut, zaktualizuj ttl, aby 120 minutę, aby zresetować liczbę trwania.

  • żądania
  • odpowiedzi
  • polecenia cURL

parametry zapytania:

Nazwa Opis Przykład Wymagane/opcjonalne
ticketId Struna. Definiuje identyfikator biletu konserwacji w systemach użytkownika. 2987345p98234 Wymagane
czasu wygaśnięcia Dodatnia liczba całkowita. Definiuje czas trwania okna w minutach. 210 Wymagane

pcap (Żądanie alertu PCAP)

Użyj tego interfejsu API, aby zażądać pliku PCAP powiązanego z alertem.

identyfikatora URI: /external/v2/alerts/

POBIERZ

  • żądania
  • odpowiedzi
  • polecenia cURL

parametry zapytania:

Nazwa Opis Przykład Wymagane/opcjonalne
identyfikatora Identyfikator alertu z lokalnej konsoli zarządzania /external/v2/alerts/pcap/<id> Wymagane

Następne kroki

Aby uzyskać więcej informacji, zobacz omówienie interfejsu API usługi Defender for IoT.