Aktualizowanie interfejsu API zdarzeń

  • Artykuł

Uwaga

Chcesz skorzystać z usługi Microsoft Defender XDR? Dowiedz się więcej o tym, jak można oceniać i pilotować usługę Microsoft Defender XDR.

Dotyczy:

Uwaga

Wypróbuj nasze nowe interfejsy API przy użyciu interfejsu API zabezpieczeń programu MS Graph. Dowiedz się więcej na stronie: Korzystanie z interfejsu API zabezpieczeń programu Microsoft Graph — Microsoft Graph | Microsoft Learn. Aby uzyskać informacje o nowym interfejsie API zdarzeń aktualizacji przy użyciu interfejsu API zabezpieczeń programu MS Graph, zobacz Update incident (Aktualizowanie zdarzenia).

Ważna

Niektóre informacje odnoszą się do wstępnie wydanego produktu, który może zostać znacząco zmodyfikowany przed jego komercyjną premierą. Firma Microsoft nie udziela żadnych gwarancji, wyraźnych ani dorozumianych, w odniesieniu do podanych tutaj informacji.

Opis interfejsu API

Aktualizacje właściwości istniejącego zdarzenia. Właściwości możliwe do zaktualizowania to: status, determination, classification, assignedTo, , tagsi comments.

Limity przydziału, alokacja zasobów i inne ograniczenia

  1. Możesz wykonać maksymalnie 50 wywołań na minutę lub 1500 wywołań na godzinę, zanim osiągniesz próg ograniczania przepustowości.
  2. Właściwość można ustawić tylko wtedy determination , gdy classification ustawiono wartość TruePositive.

Jeśli żądanie jest ograniczone, zwraca 429 kod odpowiedzi. Treść odpowiedzi wskazuje czas rozpoczęcia wykonywania nowych wywołań.

Uprawnienia

Do wywołania tego interfejsu API jest wymagane jedno z następujących uprawnień. Aby dowiedzieć się więcej, w tym jak wybrać uprawnienia, zobacz Uzyskiwanie dostępu do interfejsów API Microsoft Defender XDR.

Typ uprawnień Uprawnienie Nazwa wyświetlana uprawnień
Aplikacja Incident.ReadWrite.All Odczytywanie i zapisywanie wszystkich zdarzeń
Delegowane (konto służbowe) Incident.ReadWrite Odczytywanie i zapisywanie zdarzeń

Uwaga

Podczas uzyskiwania tokenu przy użyciu poświadczeń użytkownika użytkownik musi mieć uprawnienia do aktualizowania zdarzenia w portalu.

Żądanie HTTP

PATCH /api/incidents/{id}

Nagłówki żądań

Name (Nazwa) Wpisać Opis
Autoryzacji Ciąg Element nośny {token}. Wymagane.
Typ zawartości Ciąg application/json. Wymagane.

Treść żądania

W treści żądania podaj wartości pól, które powinny zostać zaktualizowane. Istniejące właściwości, które nie są uwzględnione w treści żądania, zachowują swoje wartości, chyba że muszą zostać ponownie obliczone z powodu zmian powiązanych wartości. Aby uzyskać najlepszą wydajność, należy pominąć istniejące wartości, które nie uległy zmianie.

Właściwość Wpisać Opis
Stan Enum Określa bieżący stan zdarzenia. Możliwe wartości to: Active, Resolved, InProgress, i Redirected.
Assignedto Ciąg Właściciel zdarzenia.
Klasyfikacji Enum Specyfikacja zdarzenia. Możliwe wartości to: TruePositive (prawdziwie dodatnie), InformationalExpectedActivity (działanie informacyjne, oczekiwane) i FalsePositive (fałszywie dodatnie).
Oznaczanie Enum Określa określenie zdarzenia.

Możliwe wartości określania dla każdej klasyfikacji to:

  • Prawdziwie dodatnie: MultiStagedAttack (atak wieloetapowy), MaliciousUserActivity (złośliwe działanie użytkownika), CompromisedAccount (konto z naruszeniem zabezpieczeń) — rozważ odpowiednio zmianę nazwy wyliczenia w publicznym interfejsie API ( Malware Złośliwe oprogramowanie), Phishing (wyłudzanie informacji), UnwantedSoftware (Niechciane oprogramowanie) i Other (Inne).
  • Działanie informacyjne, oczekiwane:SecurityTesting (Test zabezpieczeń), LineOfBusinessApplication (aplikacja biznesowa), ConfirmedActivity (potwierdzone działanie) — rozważ odpowiednio zmianę nazwy wyliczenia w publicznym interfejsie API i Other (Inne).
  • Wynik fałszywie dodatni:Clean (Nie złośliwy) — rozważ odpowiednio zmianę nazwy wyliczenia w publicznym interfejsie NoEnoughDataToValidate API (Za mało danych do zweryfikowania) i Other (Inne).
    		•
    Tagi lista ciągów Lista tagów zdarzenia.
    Komentarz Ciąg Komentarz do dodania do zdarzenia.

    Uwaga

    Około 29 sierpnia 2022 r. wcześniej obsługiwane wartości określania alertów ("Apt" i "SecurityPersonnel") będą przestarzałe i nie będą już dostępne za pośrednictwem interfejsu API.

    Odpowiedzi

    Jeśli to się powiedzie, ta metoda zwróci wartość 200 OK. Treść odpowiedzi zawiera jednostkę zdarzenia ze zaktualizowanymi właściwościami. Jeśli nie znaleziono zdarzenia o określonym identyfikatorze, metoda zwraca wartość 404 Not Found.

    Przykład

    Przykład żądania

    Oto przykład żądania.

     PATCH https://api.security.microsoft.com/api/incidents/{id}

    Przykład żądania danych

    {
    "status": "Resolved",
    "assignedTo": "secop2@contoso.com",
    "classification": "TruePositive",
    "determination": "Malware",
    "tags": ["Yossi's playground", "Don't mess with the Zohan"],
    "comments": [
          {
              "comment": "pen testing",
              "createdBy": "secop2@contoso.com",
              "createdTime": "2021-05-02T09:34:21.5519738Z"
          },
          {
              "comment": "valid incident",
              "createdBy": "secop2@contoso.comt",
              "createdTime": "2021-05-02T09:36:27.6652581Z"
          }
      ]
}

    Porada

    Chcesz dowiedzieć się więcej? Zaangażuj się w społeczność rozwiązań zabezpieczających firmy Microsoft w naszej społeczności technicznej Społeczność techniczna usługi Microsoft Defender XDR.