Datenkonnektordefinitionsreferenz für die Codeless Connector Platform

Artikel
07/03/2024

Um einen Datenkonnektor mit der Codeless Connector Platform (CCP) zu erstellen, verwenden Sie dieses Dokument als Ergänzung zu den Referenzdokumenten der Microsoft Sentinel-REST-API für Datenkonnektordefinitionen . 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 Connector Definitions – Create or Update URI Parameters

Name	Beschreibung
dataConnectorDefinitionName	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": {}
    }
}

dataConnectorDefinition verfügt über 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 einer Beispiel-Datenkonnektorseite mit Abschnitten mit der Bezeichnung 1 bis 9.

Jedes der folgenden Elemente des Abschnitts, die connectorUiConfig zum Konfigurieren der Benutzeroberfläche erforderlich sind, entspricht dem CustomizeableConnectorUiConfig-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
type	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 die`lastDataReceivedQuery` 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.

Wichtig

Microsoft empfiehlt, Rollen mit den geringsten Berechtigungen zu verwenden. Dies trägt zur Verbesserung der Sicherheit Ihrer Organisation bei. „Globaler Administrator“ ist eine Rolle mit umfangreichen Berechtigungen, die auf Notfallszenarios beschränkt sein sollte, in denen Sie keine vorhandene Rolle verwenden können.

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`

Konfigurieren anderer Linkoptionen

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

type	Arrayeigenschaft	Beschreibung
OAuthForm	OAuthForm	Verbinden mit OAuth
Textfeld	Textfeld	Dieses Paar mit `ConnectionToggleButton`. Es gibt vier verfügbare Typen: `password` `text` `number` `email`
ConnectionToggleButton	ConnectionToggleButton	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 in der Datenconnectors-Referenz auth für die Codeless Connector 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"
  }
}
]

ConnectionToggleButton

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

CopyableLabel

Beispiel:

Screenshot: Schaltfläche „Wert kopieren“ in einem Feld.

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: Inlineinformationsmeldung.

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

Screenshot einer Informationsnachricht, die nicht inline ist.

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: erweiterbare, zusätzliche Anweisungsgruppe.

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: Link als Inlinetext hinzugefügt.

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 `SecurityEvent`oder `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"
                  }
                }
              ]
            }
          ]
        }
    }
}

Freigeben über