Udostępnij za pośrednictwem

Dokumentacja definicji łącznika danych dla platformy łącznika bez kodu

  • Artykuł

Aby utworzyć łącznik danych za pomocą platformy łącznika bez kodu (KPCH), skorzystaj z tego dokumentu jako dodatku do dokumentacji referencyjnej interfejsu API REST usługi Microsoft Sentinel dla definicji łącznika danych. W szczególności ten dokument referencyjny rozszerza się w następującej sekcji:

  • connectorUiConfig — definiuje elementy wizualne i tekst wyświetlany na stronie łącznika danych w usłudze Microsoft Sentinel.

Aby uzyskać więcej informacji, zobacz Tworzenie łącznika bez kodu.

Definicje łącznika danych — tworzenie lub aktualizowanie

Zapoznaj się z operacją Tworzenie lub aktualizowanie w dokumentacji interfejsu API REST, aby znaleźć najnowszą stabilną lub zapoznawczą wersję interfejsu API. update Tylko operacja wymaga etag wartości.

PUT , metoda

https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.OperationalInsights/workspaces/{{workspaceName}}/providers/Microsoft.SecurityInsights/dataConnectorDefinitions/{{dataConnectorDefinitionName}}?api-version={{apiVersion}}

Parametry identyfikatora URI

Aby uzyskać więcej informacji na temat najnowszej wersji interfejsu API, zobacz Definicje łącznika danych — tworzenie lub aktualizowanie parametrów identyfikatora URI

Nazwa/nazwisko opis
dataConnectorDefinitionName Definicja łącznika danych musi być unikatową nazwą i jest taka sama jak name parametr w treści żądania.
resourceGroupName Nazwa grupy zasobów, a nie uwzględnia wielkości liter.
subscriptionId Identyfikator subskrypcji docelowej.
workspaceName Nazwa obszaru roboczego, a nie identyfikator.
Wzorzec wyrażenia regularnego: ^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$
wersja interfejsu API Wersja interfejsu API do użycia dla tej operacji.

Treść żądania

Treść żądania do utworzenia definicji łącznika danych PROTOKOŁU KPCH za pomocą interfejsu API ma następującą strukturę:

{
    "kind": "Customizable",
    "properties": {
        "connectorUIConfig": {}
    }
}

Element dataConnectorDefinition ma następujące właściwości:

Nazwisko Wymagania Type Opis
Rodzaj Prawda String Customizable w przypadku łącznika danych sondowania interfejsu API lub Static w inny sposób
Właściwości.connectorUiConfig Prawda Zagnieżdżony kod JSON
connectorUiConfig		 Właściwości konfiguracji interfejsu użytkownika łącznika danych

Konfigurowanie interfejsu użytkownika łącznika

W tej sekcji opisano opcje konfiguracji dostępne do dostosowania interfejsu użytkownika strony łącznika danych.

Poniższy zrzut ekranu przedstawia stronę przykładowego łącznika danych wyróżnioną numerami odpowiadającymi godnym uwagi obszarom interfejsu użytkownika.

Zrzut ekranu przedstawiający stronę przykładowego łącznika danych z sekcjami oznaczonymi etykietą od 1 do 9.

Każdy z poniższych connectorUiConfig elementów sekcji potrzebnych do skonfigurowania interfejsu użytkownika odpowiada części CustomableConnectorUiConfig interfejsu API.

Pole Wymagania Type Opis Zrzut ekranu przedstawiający obszar godny uwagi #
title Prawda string Tytuł wyświetlany na stronie łącznika danych 1
id string Ustawia identyfikator łącznika niestandardowego dla użycia wewnętrznego
logo string Ścieżka do pliku obrazu w formacie SVG. Jeśli żadna wartość nie jest skonfigurowana, zostanie użyte domyślne logo. 2
wydawca Prawda string Dostawca łącznika 3
descriptionMarkdown Prawda ciąg w języku znaczników markdown Opis łącznika z możliwością dodawania języka markdown w celu jego ulepszenia. 100
sampleQueries Prawda Zagnieżdżony kod JSON
sampleQueries		 Wysyła zapytanie do klienta, aby zrozumieć, jak znaleźć dane w dzienniku zdarzeń.
graphQueries Prawda Zagnieżdżony kod JSON
graphQueries		 Zapytania przedstawiające pozyskiwanie danych w ciągu ostatnich dwóch tygodni.

Podaj jedno zapytanie dla wszystkich typów danych łącznika danych lub inne zapytanie dla każdego typu danych.		 5
graphQueriesTableName Ustawia nazwę tabeli, do których łącznik wstawia dane. Ta nazwa może być używana w innych zapytaniach, określając {{graphQueriesTableName}} symbol zastępczy w graphQueries wartościach i lastDataReceivedQuery .
dataTypes Prawda Zagnieżdżony kod JSON
dataTypes		 Lista wszystkich typów danych dla łącznika oraz zapytanie służące do pobierania czasu ostatniego zdarzenia dla każdego typu danych. 6
connectivityCriteria Prawda Zagnieżdżony kod JSON
connectivityCriteria		 Obiekt, który definiuje, jak sprawdzić, czy łącznik jest połączony. 7
permissions Prawda Zagnieżdżony kod JSON
permissions		 Informacje wyświetlane w sekcji Wymagania wstępne interfejsu użytkownika zawierające listę uprawnień wymaganych do włączenia lub wyłączenia łącznika. 8
instrukcjeKroki Prawda Zagnieżdżony kod JSON
instrukcje		 Tablica części widżetów wyjaśniających sposób instalowania łącznika i kontrolek z możliwością akcji wyświetlanych na karcie Instrukcje . 9

connectivityCriteria

Pole Wymagania Type Opis
Type Prawda String Jedna z dwóch następujących opcji: HasDataConnectors — ta wartość jest najlepsza w przypadku łączników danych sondowania interfejsu API, takich jak TRANSLATOR. Łącznik jest uznawany za połączony z co najmniej jednym aktywnym połączeniem.

isConnectedQuery — ta wartość jest najlepsza dla innych typów łączników danych. Łącznik jest traktowany jako połączony, gdy podane zapytanie zwraca dane.
Wartość Prawda, gdy typ ma wartość isConnectedQuery String Zapytanie określające, czy dane są odbierane w określonym przedziale czasu. Na przykład: CommonSecurityLog | where DeviceVendor == \"Vectra Networks\"\n| where DeviceProduct == \"X Series\"\n | summarize LastLogReceived = max(TimeGenerated)\n | project IsConnected = LastLogReceived > ago(7d)".

dataTypes

Wartość tablicy Type opis
name String Opis zrozumiały dla zmiennejlastDataReceivedQuery, w tym obsługa zmiennej graphQueriesTableName .

Przykład: {{graphQueriesTableName}}
lastDataReceivedQuery String Zapytanie KQL zwracające jeden wiersz i wskazujące ostatni raz dane odebrane lub brak danych, jeśli nie ma wyników.

Przykład: {{graphQueriesTableName}}\n | summarize Time = max(TimeGenerated)\n | where isnotempty(Time)

graphQueries

Definiuje zapytanie, które przedstawia pozyskiwanie danych w ciągu ostatnich dwóch tygodni.

Podaj jedno zapytanie dla wszystkich typów danych łącznika danych lub inne zapytanie dla każdego typu danych.

Wartość tablicy Type Opis
metricName String Zrozumiała nazwa grafu.

Przykład: Total data received
legenda String Ciąg wyświetlany w legendzie po prawej stronie wykresu, w tym odwołanie do zmiennej.

Przykład: {{graphQueriesTableName}}
baseQuery String Zapytanie, które filtruje pod kątem odpowiednich zdarzeń, w tym odwołanie do zmiennej.

Przykład: TableName_CL | where ProviderName == "myprovider" lub {{graphQueriesTableName}}

uprawnienia

Wartość tablicy Type Opis
urząd celny String Opisuje wszelkie uprawnienia niestandardowe wymagane dla połączenia danych w następującej składni:
{
"name":string,
"description":struna
}

Przykład: wartość celna jest wyświetlana w sekcji Wymagania wstępne usługi Microsoft Sentinel z niebieską ikoną informacyjną. W przykładzie usługi GitHub ta wartość jest skorelowana z wierszem Klucz osobistego tokenu interfejsu API usługi GitHub: potrzebujesz dostępu do osobistego tokenu usługi GitHub...
Licencje ENUM Definiuje wymagane licencje jako jedną z następujących wartości: OfficeIRM,OfficeATP, Office365, AadP1P2AatpMcasMdatp, , , , MtpIoT

Przykład: wartość licencji jest wyświetlana w usłudze Microsoft Sentinel jako: Licencja: Wymagana Azure AD — wersja Premium P2
resourceProvider resourceProvider Opisuje wszelkie wymagania wstępne dotyczące zasobu platformy Azure.

Przykład: wartość resourceProvider jest wyświetlana w sekcji Wymagania wstępne usługi Microsoft Sentinel jako:
Obszar roboczy: wymagane jest uprawnienie do odczytu i zapisu.
Klucze: wymagane są uprawnienia do odczytu kluczy udostępnionych dla obszaru roboczego.
tenant tablica wartości ENUM
Przykład:

"tenant": [
"GlobalADmin",
"SecurityAdmin"
]
 Definiuje wymagane uprawnienia jako co najmniej jedną z następujących wartości: "GlobalAdmin", , "SecurityAdmin", "SecurityReader""InformationProtection"

Przykład: wyświetla wartość dzierżawy w usłudze Microsoft Sentinel jako: Uprawnienia dzierżawy : Wymagane Global Administrator lub Security Administrator w dzierżawie obszaru roboczego

Ważne

Firma Microsoft zaleca używanie ról z najmniejszymi uprawnieniami. Pomaga to zwiększyć bezpieczeństwo organizacji. Administrator globalny to wysoce uprzywilejowana rola, która powinna być ograniczona do scenariuszy awaryjnych, gdy nie można użyć istniejącej roli.

resourceProvider

wartość tablicy podrzędnej Type Opis
dostawca ENUM Opisuje dostawcę zasobów z jedną z następujących wartości:
- Microsoft.OperationalInsights/workspaces
- Microsoft.OperationalInsights/solutions
- Microsoft.OperationalInsights/workspaces/datasources
- microsoft.aadiam/diagnosticSettings
- Microsoft.OperationalInsights/workspaces/sharedKeys
- Microsoft.Authorization/policyAssignments
providerDisplayName String Element listy w obszarze Wymagania wstępne , który wyświetla czerwony znacznik wyboru "x" lub zielony, gdy wymaganePermissions są weryfikowane na stronie łącznika. Przykład "Workspace"
permissionsDisplayText String Wyświetlanie tekstu dla uprawnień do odczytu, zapisu lub odczytu i zapisu , które powinny odpowiadać wartościom skonfigurowanym w wymaganychpermisjach
requiredPermissions {
"action":Wartość logiczna,
"delete":Wartość logiczna,
"read":Wartość logiczna,
"write":Boolowski
}		 Opisuje minimalne uprawnienia wymagane dla łącznika.
zakres ENUM Opisuje zakres łącznika danych jako jedną z następujących wartości: "Subscription", , "ResourceGroup""Workspace"

sampleQueries

wartość tablicy Type Opis
opis String Opis opisowy przykładowego zapytania.

Przykład: Top 10 vulnerabilities detected
query String Przykładowe zapytanie używane do pobierania danych typu danych.

Przykład: {{graphQueriesTableName}}\n | sort by TimeGenerated\n | take 10

Aby zdefiniować link wbudowany przy użyciu języka Markdown, użyj poniższego przykładu.

{
   "title": "",
   "description": "Make sure to configure the machine's security according to your organization's security policy\n\n\n[Learn more >](https://aka.ms/SecureCEF)"
}

Aby zdefiniować link jako szablon usługi ARM, użyj następującego przykładu jako przewodnika:

{
   "title": "Azure Resource Manager (ARM) template",
   "description": "1. Click the **Deploy to Azure** button below.\n\n\t[![Deploy To Azure](https://aka.ms/deploytoazurebutton)]({URL to custom ARM template})"
}

instrukcjeKroki

Ta sekcja zawiera parametry, które definiują zestaw instrukcji wyświetlanych na stronie łącznika danych w usłudze Microsoft Sentinel i mają następującą strukturę:

"instructionSteps": [
    {
        "title": "",
        "description": "",
        "instructions": [
        {
            "type": "",
            "parameters": {}
        }
        ],
        "innerSteps": {}
    }
]
Właściwość tablicy Wymagania Type Opis
title String Definiuje tytuł instrukcji.
opis String Definiuje zrozumiały opis instrukcji.
innerSteps Tablica Definiuje tablicę kroków instrukcji wewnętrznych.
instrukcje Prawda Tablica instrukcji Definiuje tablicę instrukcji określonego typu parametru.

instrukcje

Przedstawia grupę instrukcji z różnymi parametrami i możliwością zagnieżdżania większej liczby instrukcjiKrok w grupach. Parametry zdefiniowane tutaj odpowiadają

Typ Właściwość Tablica opis
OAuthForm OAuthForm Nawiązywanie połączenia za pomocą protokołu OAuth
Pole tekstowe Pole tekstowe Ta para z parametrem ConnectionToggleButton. Dostępne są 4 typy:
  • password
  • text
  • number
  • email
    		•
    ConnectionToggleButton ConnectionToggleButton Wyzwól wdrożenie kontrolera domeny na podstawie informacji o połączeniu dostarczonych za pomocą parametrów zastępczych. Obsługiwane są następujące parametry:
  • name :obowiązkowy
  • disabled
  • isPrimary
  • connectLabel
  • disconnectLabel
    		•
    Etykieta do kopiowania Etykieta do kopiowania Pokazuje pole tekstowe z przyciskiem kopiowania na końcu. Po wybraniu przycisku wartość pola zostanie skopiowana.
    InfoMessage InfoMessage Definiuje wbudowany komunikat informacyjny.
    InstrukcjaStepsGroup InstrukcjaStepsGroup Przedstawia grupę instrukcji, opcjonalnie rozwiniętych lub zwijanych, w oddzielnej sekcji instrukcji.
    InstallAgent InstallAgent Wyświetla link do innych części platformy Azure w celu spełnienia różnych wymagań dotyczących instalacji.

    OAuthForm

    Ten składnik wymaga obecności OAuth2 typu we auth właściwości szablonu łącznika danych.

    "instructions": [
{
  "type": "OAuthForm",
  "parameters": {
    "clientIdLabel": "Client ID",
    "clientSecretLabel": "Client Secret",
    "connectButtonLabel": "Connect",
    "disconnectButtonLabel": "Disconnect"
  }          
}
]

    Pole tekstowe

    Oto kilka przykładów Textbox typu. Te przykłady odpowiadają parametrom używanym w przykładowej auth sekcji w dokumentacji łączników danych dla platformy łącznika bez kodu. Dla każdego z 4 typów każdy ma labelwartości , placeholderi name.

    "instructions": [
{
  "type": "Textbox",
  "parameters": {
      {
        "label": "User name",
        "placeholder": "User name",
        "type": "text",
        "name": "username"
      }
  }
},
{
  "type": "Textbox",
  "parameters": {
      "label": "Secret",
      "placeholder": "Secret",
      "type": "password",
      "name": "password"
  }
}
]

    ConnectionToggleButton

    "instructions": [
{
  "type": "ConnectionToggleButton",
  "parameters": {
    "connectLabel": "toggle",
    "name": "toggle"
  }          
}
]

    Etykieta do kopiowania

    Przykład:

    Zrzut ekranu przedstawiający przycisk kopiowania wartości w polu.

    Przykładowy kod:

    {
    "parameters": {
        "fillWith": [
            "WorkspaceId",
            "PrimaryKey"
            ],
        "label": "Here are some values you'll need to proceed.",
        "value": "Workspace is {0} and PrimaryKey is {1}"
    },
    "type": "CopyableLabel"
}
    Wartość tablicy Wymagania Type Opis
    fillWith ENUM Tablica zmiennych środowiskowych używanych do wypełniania symbolu zastępczego. Rozdziel wiele symboli zastępczych przecinkami. Na przykład: {0},{1}.

    Obsługiwane wartości: workspaceId, , primaryKeyworkspaceName, , MicrosoftAwsAccountsubscriptionId
    etykieta Prawda String Definiuje tekst etykiety powyżej pola tekstowego.
    wartość Prawda String Definiuje wartość, która ma być obecna w polu tekstowym, obsługuje symbole zastępcze.
    Wierszy Wiersze Definiuje wiersze w obszarze interfejsu użytkownika. Domyślnie ustaw wartość 1.
    wideLabel Wartość logiczna Określa szeroką etykietę dla długich ciągów. Domyślnie ustaw wartość false.

    InfoMessage

    Oto przykład komunikatu informacyjnego wbudowanego:

    Zrzut ekranu przedstawiający wbudowany komunikat informacyjny.

    Z kolei na poniższej ilustracji przedstawiono komunikat informacyjny, który nie jest wbudowany:

    Zrzut ekranu przedstawiający komunikat informacyjny, który nie jest wbudowany.

    Wartość tablicy Type Opis
    text String Zdefiniuj tekst do wyświetlenia w wiadomości.
    widoczny Wartość logiczna Określa, czy komunikat jest wyświetlany.
    Wbudowany Wartość logiczna Określa sposób wyświetlania komunikatu informacyjnego.

    - true: (Zalecane) Wyświetla komunikat informacyjny osadzony w instrukcjach.
    - false: Dodaje niebieskie tło.

    InstrukcjaStepsGroup

    Oto przykład rozszerzalnej grupy instrukcji:

    Zrzut ekranu przedstawiający rozwijaną, dodatkową grupę instrukcji.

    Wartość tablicy Wymagania Type Opis
    title Prawda String Definiuje tytuł kroku instrukcji.
    opis String Opcjonalny tekst opisowy.
    canCollapseAllSections Wartość logiczna Określa, czy sekcja jest zwijanym akordeonem, czy nie.
    noFxPadding Wartość logiczna Jeśli trueparametr zmniejsza dopełnienie wysokości, aby zaoszczędzić miejsce.
    Rozszerzony Wartość logiczna Jeśli truewartość jest wyświetlana jako rozwinięta domyślnie.

    Aby uzyskać szczegółowy przykład, zobacz konfigurację JSON łącznika DNS systemu Windows.

    InstallAgent

    Niektóre typy InstallAgent są wyświetlane jako przycisk, inne są wyświetlane jako link. Oto przykłady obu tych elementów:

    Zrzut ekranu przedstawiający link dodany jako przycisk.

    Zrzut ekranu przedstawiający link dodany jako tekst wbudowany.

    Wartości tablicy Wymagania Type Opis
    linkType Prawda ENUM Określa typ łącza jako jedną z następujących wartości:

    InstallAgentOnWindowsVirtualMachine
    InstallAgentOnWindowsNonAzure
    InstallAgentOnLinuxVirtualMachine
    InstallAgentOnLinuxNonAzure
    OpenSyslogSettings
    OpenCustomLogsSettings
    OpenWaf
    OpenAzureFirewall OpenMicrosoftAzureMonitoring
    OpenFrontDoors
    OpenCdnProfile
    AutomaticDeploymentCEF
    OpenAzureInformationProtection
    OpenAzureActivityLog
    OpenIotPricingModel
    OpenPolicyAssignment
    OpenAllAssignmentsBlade
    OpenCreateDataCollectionRule
    policyDefinitionGuid Wartość true w przypadku używania parametru OpenPolicyAssignment linkType. String W przypadku łączników opartych na zasadach definiuje identyfikator GUID wbudowanej definicji zasad.
    assignMode ENUM W przypadku łączników opartych na zasadach definiuje tryb przypisywania jako jedną z następujących wartości: Initiative, Policy
    dataCollectionRuleType ENUM W przypadku łączników opartych na kontrolerze domeny definiuje typ reguły zbierania danych jako SecurityEvent, lub ForwardEvent.

    Przykładowa definicja łącznika danych

    Poniższy przykład łączy niektóre składniki zdefiniowane w tym artykule jako format treści JSON do użycia z interfejsem API definicji łącznika tworzenia lub aktualizowania danych.

    Aby uzyskać więcej przykładów, zapoznaj się connectorUiConfig z innymi łącznikami danych USŁUGI CCP. Nawet łączniki korzystające ze starszej wersji USŁUGI KPI mają prawidłowe przykłady tworzenia interfejsu użytkownika.

    {
    "kind": "Customizable",
    "properties": {
        "connectorUiConfig": {
          "title": "Example CCP Data Connector",
          "publisher": "My Company",
          "descriptionMarkdown": "This is an example of data connector",
          "graphQueriesTableName": "ExampleConnectorAlerts_CL",
          "graphQueries": [
            {
              "metricName": "Alerts received",
              "legend": "My data connector alerts",
              "baseQuery": "{{graphQueriesTableName}}"
            },   
           {
              "metricName": "Events received",
              "legend": "My data connector events",
              "baseQuery": "ASIMFileEventLogs"
            }
          ],
            "sampleQueries": [
            {
                "description": "All alert logs",
                "query": "{{graphQueriesTableName}} \n | take 10"
            }
          ],
          "dataTypes": [
            {
              "name": "{{graphQueriesTableName}}",
              "lastDataReceivedQuery": "{{graphQueriesTableName}} \n | summarize Time = max(TimeGenerated)\n | where isnotempty(Time)"
            },
             {
              "name": "ASIMFileEventLogs",
              "lastDataReceivedQuery": "ASIMFileEventLogs \n | summarize Time = max(TimeGenerated)\n | where isnotempty(Time)"
             }
          ],
          "connectivityCriteria": [
            {
              "type": "HasDataConnectors"
            }
          ],
          "permissions": {
            "resourceProvider": [
              {
                "provider": "Microsoft.OperationalInsights/workspaces",
                "permissionsDisplayText": "Read and Write permissions are required.",
                "providerDisplayName": "Workspace",
                "scope": "Workspace",
                "requiredPermissions": {
                  "write": true,
                  "read": true,
                  "delete": true
                }
              },
            ],
            "customs": [
              {
                "name": "Example Connector API Key",
                "description": "The connector API key username and password is required"
              }
            ] 
        },
          "instructionSteps": [
            {
              "title": "Connect My Connector to Microsoft Sentinel",
              "description": "To enable the connector provide the required information below and click on Connect.\n>",
              "instructions": [
               {
                  "type": "Textbox",
                  "parameters": {
                    "label": "User name",
                    "placeholder": "User name",
                    "type": "text",
                    "name": "username"
                  }
                },
                {
                  "type": "Textbox",
                  "parameters": {
                    "label": "Secret",
                    "placeholder": "Secret",
                    "type": "password",
                    "name": "password"
                  }
                },
                {
                  "type": "ConnectionToggleButton",
                  "parameters": {
                    "connectLabel": "toggle",
                    "name": "toggle"
                  }
                }
              ]
            }
          ]
        }
    }
}