Freigeben über

Datenkonnektordefinitionsreferenz für die Codeless Verbinden or Platform

  • Artikel

Um einen Datenkonnektor mit der Codeless Verbinden or Platform (CCP) zu erstellen, verwenden Sie dieses Dokument als Ergänzung zur Microsoft Sentinel-REST-API für Data Verbinden or Definitions-Referenzdokumente. Insbesondere dieses Referenzdokument wird im folgenden Abschnitt erweitert:

  • connectorUiConfig – definiert die visuellen Elemente und Text, die auf der Datenkonnektorseite in Microsoft Sentinel angezeigt werden.

Weitere Informationen finden Sie unter Erstellen eines codelosen Connectors.

Datenkonnektordefinitionen – Erstellen oder Aktualisieren

Verweisen Sie auf den Vorgang "Erstellen oder Aktualisieren" in den REST-API-Dokumenten, um die neueste stabile oder Vorschau-API-Version zu finden. Nur der update Vorgang erfordert den etag Wert.

PUT-Methode

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

URI-Parameter

Weitere Informationen zur neuesten API-Version finden Sie unter Data Verbinden or Definitions – Create or Update URI Parameters

Name Beschreibung
data Verbinden orDefinitionName Die Datenkonnektordefinition muss ein eindeutiger Name sein und ist identisch mit dem name Parameter im Anforderungstext.
resourceGroupName Der Name der Ressourcengruppe, nicht die Groß-/Kleinschreibung.
subscriptionId Hierbei handelt es sich um die ID des Zielabonnements.
workspaceName Der Name des Arbeitsbereichs, nicht die ID.
RegEx-Muster: ^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$
api-version Hierbei handelt es sich um die für diesen Vorgang zu verwendende API-Version.

Anforderungstext

Der Anforderungstext zum Erstellen einer CCP-Datenkonnektordefinition mit der API weist die folgende Struktur auf:

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

data Verbinden orDefinition hat die folgenden Eigenschaften:

Name Erforderlich Type Beschreibung
Variante True String Customizable für API-Abrufdatenconnector oder Static anderweitig
Eigenschaften.connectorUiConfig True Geschachteltes JSON
connectorUiConfig		 Die Ui-Konfigurationseigenschaften des Datenconnectors

Konfigurieren der Benutzeroberfläche Ihres Connectors

In diesem Abschnitt werden die Konfigurationsoptionen beschrieben, die zum Anpassen der Benutzeroberfläche der Seite „Datenconnector“ verfügbar sind.

Der folgende Screenshot zeigt eine Beispielseite für den Datenkonnektor, hervorgehoben mit Zahlen, die wichtigen Bereichen der Benutzeroberfläche entsprechen.

Screenshot of a sample data connector page with sections labeled 1 through 9.

Jedes der folgenden Elemente des Abschnitts, die connectorUiConfig zum Konfigurieren der Benutzeroberfläche erforderlich sind, entspricht dem Customizeable Verbinden orUiConfig-Teil der API.

Feld Erforderlich Type Beschreibung Screenshot des wichtigen Bereichs #
title True Zeichenfolge Titel, der auf der Datenkonnektorseite angezeigt wird 1
id Zeichenfolge Legt benutzerdefinierte Connector-ID für die interne Verwendung fest
Logo Zeichenfolge Pfad zur Bilddatei im SVG-Format. Wenn kein Wert konfiguriert ist, wird ein Standardlogo verwendet. 2
publisher True Zeichenfolge Der Anbieter des Connectors 3
descriptionMarkdown True Zeichenfolge im Markdown Eine Beschreibung für den Connector mit der Möglichkeit, Markdown-Sprachen hinzuzufügen, um sie zu verbessern. 4
sampleQueries True Geschachteltes JSON
sampleQueries		 Fragt den Kunden ab, wie die Daten im Ereignisprotokoll gefunden werden.
graphQueries True Geschachteltes JSON
graphQueries		 Abfragen, die Datenaufnahme in den letzten zwei Wochen darstellen.

Stellen Sie entweder eine Abfrage für alle Datentypen des Datenconnectors oder eine andere Abfrage für die einzelnen Datentypen zur Verfügung.		 5
graphQueriesTableName Legt den Namen der Tabelle fest, in die der Verbinder Daten einfügt. Dieser Name kann in anderen Abfragen verwendet werden, indem Platzhalter in graphQueries und lastDataReceivedQuery Werte angegeben {{graphQueriesTableName}} werden.
dataTypes True Geschachteltes JSON
dataTypes		 Eine Liste aller Datentypen für Ihren Connector und eine Abfrage zum Abrufen des Zeitpunkts des letzten Ereignisses für jeden Datentyp. 6
connectivityCriteria True Geschachteltes JSON
connectivityCriteria		 Ein Objekt, das definiert, wie überprüft wird, ob der Verbinder verbunden ist. 7
Berechtigungen True Geschachteltes JSON
Berechtigungen		 Die Informationen, die im Abschnitt "Voraussetzungen" der Benutzeroberfläche angezeigt werden, in dem die zum Aktivieren oder Deaktivieren des Connectors erforderlichen Berechtigungen aufgeführt sind. 8
instructionSteps True Geschachteltes JSON
instructions		 Ein Array von Widgetteilen, die erläutern, wie der Verbinder installiert wird, und Aktionen erfordernde Steuerelemente, die auf der Registerkarte "Anweisungen " angezeigt werden. 9

connectivityCriteria

Feld Erforderlich Type Beschreibung
Typ True String Eine der beiden folgenden Optionen: HasDataConnectors – dieser Wert eignet sich am besten für API-Abrufdatenconnectors wie die CCP. Der Verbinder gilt als verbunden mit mindestens einer aktiven Verbindung.

isConnectedQuery – Dieser Wert eignet sich am besten für andere Arten von Datenconnectors. Der Connector wird als verbunden betrachtet, wenn die bereitgestellte Abfrage Daten zurückgibt.
Wert True, wenn typ ist isConnectedQuery String Eine Abfrage, um festzustellen, ob Daten innerhalb eines bestimmten Zeitraums empfangen werden. Beispiel: CommonSecurityLog | where DeviceVendor == \"Vectra Networks\"\n| where DeviceProduct == \"X Series\"\n | summarize LastLogReceived = max(TimeGenerated)\n | project IsConnected = LastLogReceived > ago(7d)"

dataTypes

Arraywert type BESCHREIBUNG
name String Eine aussagekräftige Beschreibung für dielastDataReceivedQuery Variable, einschließlich der Unterstützung für die graphQueriesTableName Variable.

Beispiel: {{graphQueriesTableName}}
lastDataReceivedQuery String Eine KQL-Abfrage, die eine Zeile zurückgibt und angibt, wie lange Daten zuletzt empfangen wurden, oder keine Daten, wenn keine Ergebnisse vorhanden sind.

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

graphQueries

Definiert eine Abfrage, die datenaufnahme in den letzten zwei Wochen darstellt.

Stellen Sie entweder eine Abfrage für alle Datentypen des Datenconnectors oder eine andere Abfrage für die einzelnen Datentypen zur Verfügung.

Arraywert type BESCHREIBUNG
metricName String Ein aussagekräftiger Name für Ihren Graphen.

Beispiel: Total data received
legend String Die Zeichenfolge, die in der Legende rechts neben dem Diagramm angezeigt wird, einschließlich eines Variablenverweises.

Beispiel: {{graphQueriesTableName}}
baseQuery String Die Abfrage, die nach relevanten Ereignissen filtert, einschließlich eines Variablenverweises.

Beispiel: TableName_CL | where ProviderName == "myprovider" oder {{graphQueriesTableName}}

konfigurieren

Arraywert type BESCHREIBUNG
customs String Beschreibt alle benutzerdefinierten Berechtigungen, die für Ihre Datenverbindung erforderlich sind, in der folgenden Syntax:
{
"name":string,
"description":Zeichenfolge
}

Beispiel: Der Wert Zoll wird im Abschnitt „Microsoft Sentinel-Voraussetzungen“ mit einem blauen Informationssymbol angezeigt. Im GitHub-Beispiel korreliert dieser Wert mit dem persönlichen GitHub-API-Tokenschlüssel: Sie benötigen Zugriff auf das persönliche GitHub-Token...
Lizenzen ENUM Definiert die erforderlichen Lizenzen als einen der folgenden Werte: OfficeIRM, OfficeATP, Office365, AadP1P2, Mcas, Aatp, Mdatp, Mtp, IoT

Beispiel: Der licenses-Wert wird in Microsoft Sentinel als Lizenz: Azure AD Premium P2 erforderlich angezeigt.
resourceProvider resourceProvider Beschreibt alle Voraussetzungen für Ihre Azure-Ressource.

Beispiel: Der Wert resourceProvider wird im Abschnitt „Microsoft Sentinel Voraussetzungen“ folgendermaßen angezeigt:
Arbeitsbereich: Lese- und Schreibberechtigung ist erforderlich.
Schlüssel: Es sind Leseberechtigungen für freigegebene Schlüssel für den Arbeitsbereich erforderlich.
tenant Array von ENUM-Werten
Beispiel:

"tenant": [
"GlobalADmin",
"SecurityAdmin"
]
 Definiert die erforderlichen Berechtigungen als einen oder mehrere der folgenden Werte: "GlobalAdmin", "SecurityAdmin", "SecurityReader", "InformationProtection"

Beispiel: Der Wert Mandant wird in Microsoft Sentinel als „Mandantenberechtigungen: Erfordert Global Administrator oder Security Administrator für den Mandanten des Arbeitsbereichs“ angezeigt.

resourceProvider

Subarraywert type BESCHREIBUNG
Anbieter ENUM Beschreibt den Ressourcenanbieter mit einem der folgenden Werte:
- Microsoft.OperationalInsights/workspaces
- Microsoft.OperationalInsights/solutions
- Microsoft.OperationalInsights/workspaces/datasources
- microsoft.aadiam/diagnosticSettings
- Microsoft.OperationalInsights/workspaces/sharedKeys
- Microsoft.Authorization/policyAssignments
providerDisplayName String Ein Listenelement unter "Voraussetzungen", das ein rotes "x" oder ein grünes Häkchen anzeigt, wenn die erforderlichenPermissions auf der Connectorseite überprüft werden. Beispiel: "Workspace"
permissionsDisplayText String Anzeigen von Text für Lese-, Schreib- oder Lese- und Schreibberechtigungen, die den Werten, die in requiredPermissions konfiguriert wurden, entsprechen sollen
requiredPermissions {
"action":Boolescher Wert,
"delete":Boolescher Wert,
"read":Boolescher Wert,
"write": Boolescher Wert
}		 Beschreibt die Mindestberechtigungen, die für den Connector erforderlich sind.
scope ENUM Beschreibt den Bereich des Datenconnectors als einen der folgenden Werte: "Subscription", "ResourceGroup", "Workspace"

sampleQueries

Arraywert type BESCHREIBUNG
description String Eine aussagekräftige Beschreibung für die Beispielabfrage.

Beispiel: Top 10 vulnerabilities detected
query String Eine Beispielabfrage zum Abrufen der Daten des Datentyps.

Beispiel: {{graphQueriesTableName}}\n | sort by TimeGenerated\n | take 10

Verwenden Sie das folgende Beispiel, um einen Inlinelink mit Markdown zu definieren.

{
   "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)"
}

Um einen Link als ARM-Vorlage zu definieren, verwenden Sie das folgende Beispiel als Leitfaden:

{
   "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})"
}

instructionSteps

Dieser Abschnitt enthält Parameter, die den Satz von Anweisungen definieren, die auf Ihrer Datenkonnektorseite in Microsoft Sentinel angezeigt werden und die folgende Struktur aufweisen:

"instructionSteps": [
    {
        "title": "",
        "description": "",
        "instructions": [
        {
            "type": "",
            "parameters": {}
        }
        ],
        "innerSteps": {}
    }
]
Arrayeigenschaft Erforderlich Type BESCHREIBUNG
title String Definiert einen Titel für Ihre Anweisungen.
description String Definiert eine aussagekräftige Beschreibung für Ihre Anweisungen.
innerSteps Array Definiert ein Array von inneren Anweisungsschritten.
instructions True Array von Anweisungen Definiert ein Array von Anweisungen eines bestimmten Parametertyps.

Setup

Zeigt eine Gruppe von Anweisungen mit verschiedenen Parametern und der Möglichkeit an, weitere Anweisungen in Gruppen zu verschachteln. Hier definierte Parameter entsprechen

Typ Arrayeigenschaft Beschreibung
OAuthForm OAuthForm Verbinden mit OAuth
Textfeld Textfeld Dieses Paar mit ConnectionToggleButton. Es gibt vier verfügbare Typen:
  • password
  • text
  • number
  • email
    		•
    Verbinden ionToggleButton Verbinden ionToggleButton Auslösen der Bereitstellung des DCR basierend auf den Verbindungsinformationen, die über Platzhalterparameter bereitgestellt werden. Die folgenden Parameter werden unterstützt:
  • name :Obligatorisch
  • disabled
  • isPrimary
  • connectLabel
  • disconnectLabel
    		•
    CopyableLabel CopyableLabel Zeigt ein Textfeld mit der Schaltfläche „Kopieren“ am Ende an. Wenn die Schaltfläche ausgewählt ist, wird der Wert des Felds kopiert.
    InfoMessage InfoMessage Definiert eine Inlineinformationsmeldung.
    InstructionStepsGroup InstructionStepsGroup Zeigt eine Gruppe von Anweisungen, die optional erweiterbar oder reduzierbar sind, in einem separaten Abschnitt mit Anweisungen an.
    InstallAgent InstallAgent Zeigt einen Link zu anderen Teilen von Azure an, um verschiedene Installationsanforderungen zu erfüllen.

    OAuthForm

    Diese Komponente erfordert, dass der OAuth2 Typ in der auth Eigenschaft der Datenkonnektorvorlage vorhanden ist.

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

    Textfeld

    Hier sind einige Beispiele für den Textbox Typ. Diese Beispiele entsprechen den Parametern, die im Beispielabschnitt auth in der Datenconnectorsreferenz für die Codeless Verbinden or Platform verwendet werden. Für jeden der 4 Typen verfügt labeljedes über , placeholderund 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"
  }
}
]

    Verbinden ionToggleButton

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

    CopyableLabel

    Beispiel:

    Screenshot of a copy value button in a field.

    Beispielcode:

    {
    "parameters": {
        "fillWith": [
            "WorkspaceId",
            "PrimaryKey"
            ],
        "label": "Here are some values you'll need to proceed.",
        "value": "Workspace is {0} and PrimaryKey is {1}"
    },
    "type": "CopyableLabel"
}
    Arraywert Erforderlich Type BESCHREIBUNG
    fillWith ENUM Array von Umgebungsvariablen, die zum Auffüllen eines Platzhalters verwendet werden. Trennen Sie mehrere Platzhalter durch Kommas. Beispiel: {0},{1}

    Unterstützte Werte: workspaceId, workspaceName, primaryKey, MicrosoftAwsAccount, subscriptionId
    label True String Definiert den Text für die Bezeichnung über einem Textfeld.
    value True String Definiert den Wert, der im Textfeld angezeigt werden soll, unterstützt Platzhalter.
    rows Zeilen Definiert die Zeilen im Benutzeroberflächenbereich. Legen Sie dies standardmäßig auf 1 fest.
    wideLabel Boolean Bestimmt eine breite Bezeichnung für lange Zeichenfolgen. Legen Sie dies standardmäßig auf false fest.

    InfoMessage

    Hier sehen Sie ein Beispiel für eine Inlineinformationsmeldung:

    Screenshot of an inline information message.

    Im Gegensatz dazu zeigt die folgende Abbildung eine Informationsmeldung, die nicht inline ist:

    Screenshot of an information message that's not inline.

    Arraywert type BESCHREIBUNG
    text String Definiert den in der Meldung anzuzeigenden Text.
    visible Boolean Bestimmt, ob die Meldung angezeigt wird.
    inline Boolean Bestimmt, wie die Informationsmeldung angezeigt wird.

    - true: (Empfohlen) Zeigt die In den Anweisungen eingebettete Informationsmeldung an.
    - false: Fügt einen blauen Hintergrund hinzu.

    InstructionStepsGroup

    Hier sehen Sie ein Beispiel für eine erweiterbare Anweisungsgruppe:

    Screenshot of an expandable, extra instruction group.

    Arraywert Erforderlich Type BESCHREIBUNG
    title True String Definiert den Titel für den Anweisungsschritt.
    Beschreibung String Optionaler beschreibender Text.
    canCollapseAllSections Boolean Bestimmt, ob es sich bei dem Abschnitt um ein reduzierbares Akkordeon handelt.
    noFxPadding Boolean Bei true wird der Höhenabstand reduziert, um Platz zu sparen.
    expanded Boolean Bei true erfolgt die erweiterte Anzeige.

    Ein ausführliches Beispiel finden Sie in der JSON-Konfiguration des Windows DNS-Connectors.

    InstallAgent

    Einige InstallAgent-Typen werden als Schaltfläche angezeigt, andere werden als Link angezeigt. Hier sehen Sie Beispiele für beides:

    Screenshot of a link added as a button.

    Screenshot of a link added as inline text.

    Arraywerte Erforderlich Type BESCHREIBUNG
    linkType True ENUM Bestimmt den Linktyp als einen der folgenden Werte:

    InstallAgentOnWindowsVirtualMachine
    InstallAgentOnWindowsNonAzure
    InstallAgentOnLinuxVirtualMachine
    InstallAgentOnLinuxNonAzure
    OpenSyslogSettings
    OpenCustomLogsSettings
    OpenWaf
    OpenAzureFirewall OpenMicrosoftAzureMonitoring
    OpenFrontDoors
    OpenCdnProfile
    AutomaticDeploymentCEF
    OpenAzureInformationProtection
    OpenAzureActivityLog
    OpenIotPricingModel
    OpenPolicyAssignment
    OpenAllAssignmentsBlade
    OpenCreateDataCollectionRule
    policyDefinitionGuid True bei Verwendung von OpenPolicyAssignment linkType. String Definiert für richtlinienbasierte Connectors die GUID der integrierten Richtliniendefinition.
    assignMode ENUM Definiert für richtlinienbasierte Connectors den Zuweisungsmodus als einen der folgenden Werte: Initiative, Policy
    dataCollectionRuleType ENUM Definiert für DCR-basierte Connectors den Typ des Regeltyps der Datensammlung als entweder SecurityEventoder ForwardEvent.

    Beispieldefinition für Datenkonnektor

    Im folgenden Beispiel werden einige der in diesem Artikel definierten Komponenten als JSON-Textkörperformat zusammengefasst, das mit der Definitions-API zum Erstellen oder Aktualisieren von Datenkonnektoren verwendet werden soll.

    Weitere Beispiele für die Überprüfung anderer connectorUiConfig CCP-Datenconnectors. Selbst Connectors, die die legacy-CCP verwenden, weisen gültige Beispiele für die Erstellung der Benutzeroberfläche auf.

    {
    "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"
                  }
                }
              ]
            }
          ]
        }
    }
}