Naslaginformatie over definities van gegevensconnectors voor het Codeless Verbinding maken or Platform

Artikel
02/15/2024

Als u een gegevensconnector wilt maken met het Codeless Verbinding maken or Platform (CCP), gebruikt u dit document als aanvulling op de Microsoft Sentinel REST API voor Data Verbinding maken or Definitions-referentiedocumenten. Dit referentiedocument wordt specifiek uitgebreid in de volgende sectie:

connectorUiConfig - definieert de visuele elementen en tekst die wordt weergegeven op de pagina gegevensconnector in Microsoft Sentinel.

Zie Een connector zonder code maken voor meer informatie.

Definities van gegevensconnector - Maken of bijwerken

Raadpleeg de bewerking Maken of bijwerken in de REST API-documenten om de nieuwste stabiele of preview-API-versie te vinden. Alleen voor de update bewerking is de etag waarde vereist.

PUT-methode

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

URI-parameters

Zie Data Verbinding maken or Definitions - Create or Update URI Parameters (URI-parameters maken of bijwerken) voor meer informatie over de nieuwste API-versie

Name	Beschrijving
data Verbinding maken orDefinitionName	De definitie van de gegevensconnector moet een unieke naam zijn en is hetzelfde als de `name` parameter in de aanvraagbody.
resourceGroupName	De naam van de resourcegroep, niet hoofdlettergevoelig.
subscriptionId	De id van het doelabonnement.
workspaceName	De naam van de werkruimte, niet de id. Regex-patroon: `^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$`
api-version	De API-versie die voor deze bewerking moet worden gebruikt.

Aanvraagtekst

De aanvraagbody voor het maken van een definitie van een CCP-gegevensconnector met de API heeft de volgende structuur:

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

data Verbinding maken orDefinition heeft de volgende eigenschappen:

Naam	Vereist	Type	Beschrijving
Soort	Waar	String	`Customizable` voor api-polling-gegevensconnector of `Static` anderszins
Eigenschappen.connectorUiConfig	Waar	Geneste JSON connectorUiConfig	De eigenschappen van de gebruikersinterfaceconfiguratie van de gegevensconnector

De gebruikersinterface van uw connector configureren

In deze sectie worden de configuratieopties beschreven die beschikbaar zijn om de gebruikersinterface van de pagina gegevensconnector aan te passen.

In de volgende schermopname ziet u een pagina met voorbeeldgegevensconnector, gemarkeerd met getallen die overeenkomen met belangrijke gebieden van de gebruikersinterface.

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

Elk van de volgende elementen van de connectorUiConfig sectie die nodig is om de gebruikersinterface te configureren, komt overeen met het gedeelte Aanpasbare Verbinding maken orUiConfig van de API.

Veld	Vereist	Type	Description	Schermopname van een opmerkelijk gebied #
title	Waar	tekenreeks	Titel weergegeven op de pagina gegevensconnector	1
id		tekenreeks	Hiermee stelt u de aangepaste connector-id in voor intern gebruik
Logo		tekenreeks	Pad naar afbeeldingsbestand in SVG-indeling. Als er geen waarde is geconfigureerd, wordt een standaardlogo gebruikt.	2
Publisher	Waar	tekenreeks	De provider van de connector	3
descriptionMarkdown	Waar	tekenreeks in Markdown	Een beschrijving voor de connector met de mogelijkheid om markdown-taal toe te voegen om deze te verbeteren.	4
sampleQueries	Waar	Geneste JSON sampleQueries	Query's voor de klant om te begrijpen hoe u de gegevens in het gebeurtenislogboek kunt vinden.
graphQueries	Waar	Geneste JSON graphQueries	Query's die gegevensopname in de afgelopen twee weken presenteren. Geef één query op voor alle gegevenstypen van de gegevensconnector of een andere query voor elk gegevenstype.	5
graphQueriesTableName		Hiermee stelt u de naam van de tabel in waarnaar de connector gegevens invoegt. Deze naam kan worden gebruikt in andere query's door een tijdelijke aanduiding in `graphQueries` en `lastDataReceivedQuery` waarden op te `{{graphQueriesTableName}}` geven.
Datatypes	Waar	Geneste JSON Datatypes	Een lijst met alle gegevenstypen voor uw connector en een query voor het ophalen van de tijd van de laatste gebeurtenis voor elk gegevenstype.	6
connectivityCriteria	Waar	Geneste JSON connectivityCriteria	Een object dat definieert hoe u controleert of de connector is verbonden.	7
permissions	Waar	Geneste JSON permissions	De informatie die wordt weergegeven in de sectie Vereisten van de gebruikersinterface, waarin de machtigingen worden vermeld die nodig zijn om de connector in of uit te schakelen.	8
instructionSteps	Waar	Geneste JSON Instructies	Een matrix met widgetonderdelen die uitleggen hoe u de connector installeert en besturingselementen waarop actie kan worden uitgevoerd die worden weergegeven op het tabblad Instructies .	9

connectivityCriteria

Veld	Vereist	Type	Description
Type	Waar	String	Een van de volgende opties: `HasDataConnectors` deze waarde is het meest geschikt voor API-pollinggegevensconnectors zoals de CTP. De connector wordt beschouwd als verbonden met ten minste één actieve verbinding. `isConnectedQuery` – deze waarde is het meest geschikt voor andere typen gegevensconnectors. De connector wordt beschouwd als verbonden wanneer de opgegeven query gegevens retourneert.
Weergegeven als	Waar wanneer het type is `isConnectedQuery`	String	Een query om te bepalen of gegevens binnen een bepaalde periode worden ontvangen. Bijvoorbeeld: `CommonSecurityLog \| where DeviceVendor == \"Vectra Networks\"\n\| where DeviceProduct == \"X Series\"\n \| summarize LastLogReceived = max(TimeGenerated)\n \| project IsConnected = LastLogReceived > ago(7d)"`

Datatypes

Matrixwaarde	Type	Description
name	String	Een zinvolle beschrijving voor de`lastDataReceivedQuery` variabele, inclusief ondersteuning voor de `graphQueriesTableName` variabele. Voorbeeld: `{{graphQueriesTableName}}`
lastDataReceivedQuery	String	Een KQL-query die één rij retourneert en de laatste keer dat gegevens zijn ontvangen, of geen gegevens als er geen resultaten zijn. Voorbeeld: `{{graphQueriesTableName}}\n \| summarize Time = max(TimeGenerated)\n \| where isnotempty(Time)`

graphQueries

Hiermee definieert u een query die gegevensopname in de afgelopen twee weken weergeeft.

Geef één query op voor alle gegevenstypen van de gegevensconnector of een andere query voor elk gegevenstype.

Matrixwaarde	Type	Description
metricName	String	Een betekenisvolle naam voor uw grafiek. Voorbeeld: `Total data received`
Legende	String	De tekenreeks die in de legenda rechts van de grafiek wordt weergegeven, inclusief een verwijzing naar een variabele. Voorbeeld: `{{graphQueriesTableName}}`
baseQuery	String	De query die filtert op relevante gebeurtenissen, inclusief een variabelereferentie. Bijvoorbeeld: `TableName_CL \| where ProviderName == "myprovider"` of `{{graphQueriesTableName}}`

permissions

Matrixwaarde	Type	Description
Douane	String	Beschrijft eventuele aangepaste machtigingen die vereist zijn voor uw gegevensverbinding, in de volgende syntaxis: `{` `"name":`Tekenreeks`,` `"description":`Tekenreeks `}` Voorbeeld: De douanewaarde wordt weergegeven in de sectie Vereisten van Microsoft Sentinel met een blauw informatiepictogram. In het GitHub-voorbeeld correleert deze waarde met de persoonlijke tokensleutel van de GitHub-API: u hebt toegang nodig tot het persoonlijke GitHub-token...
Licenties	ENUM	Definieert de vereiste licenties als een van de volgende waarden: `OfficeIRM`,`OfficeATP`, `Office365`, , `AadP1P2`, `Mcas`, `Aatp`, `Mdatp`, , `MtpIoT` Voorbeeld: De licentiewaarde wordt weergegeven in Microsoft Sentinel als: Licentie: Vereiste Azure AD Premium P2
resourceProvider	resourceProvider	Beschrijft eventuele vereisten voor uw Azure-resource. Voorbeeld: De waarde resourceProvider wordt weergegeven in de sectie Vereisten voor Microsoft Sentinel als: Werkruimte: lees- en schrijfmachtiging is vereist. Sleutels: leesmachtigingen voor gedeelde sleutels voor de werkruimte zijn vereist.
tenant	matrix van ENUM-waarden Voorbeeld: `"tenant": [` `"GlobalADmin",` `"SecurityAdmin"` `]`	Definieert de vereiste machtigingen als een of meer van de volgende waarden: `"GlobalAdmin"`, `"SecurityAdmin"`, `"SecurityReader"`, `"InformationProtection"` Voorbeeld: geeft de tenantwaarde in Microsoft Sentinel weer als: Tenantmachtigingen: Vereist `Global Administrator` of `Security Administrator` op de tenant van de werkruimte

resourceProvider

submatrixwaarde	Type	Description
Provider	ENUM	Beschrijft de resourceprovider, met een van de volgende waarden: - `Microsoft.OperationalInsights/workspaces` - `Microsoft.OperationalInsights/solutions` - `Microsoft.OperationalInsights/workspaces/datasources` - `microsoft.aadiam/diagnosticSettings` - `Microsoft.OperationalInsights/workspaces/sharedKeys` - `Microsoft.Authorization/policyAssignments`
providerDisplayName	String	Een lijstitem onder Vereisten met een rood 'x' of groen vinkje wanneer de requiredPermissions worden gevalideerd op de connectorpagina. Voorbeeld `"Workspace"`
permissionsDisplayText	String	Tekst weergeven voor lees-, schrijf- of lees- en schrijfmachtigingen* die moeten overeenkomen met de waarden die zijn geconfigureerd in* requiredPermissions
requiredPermissions	`{` `"action":`Booleaanse waarde`,` `"delete":`Booleaanse waarde`,` `"read":`Booleaanse waarde`,` `"write":`Booleaanse `}`	Beschrijft de minimale machtigingen die vereist zijn voor de connector.
bereik	ENUM	Beschrijft het bereik van de gegevensconnector als een van de volgende waarden: `"Subscription"`, , `"ResourceGroup""Workspace"`

sampleQueries

matrixwaarde	Type	Description
beschrijving	String	Een zinvolle beschrijving voor de voorbeeldquery. Voorbeeld: `Top 10 vulnerabilities detected`
query	String	Voorbeeldquery die wordt gebruikt om de gegevens van het gegevenstype op te halen. Voorbeeld: `{{graphQueriesTableName}}\n \| sort by TimeGenerated\n \| take 10`

Andere koppelingsopties configureren

Als u een inlinekoppeling wilt definiëren met behulp van Markdown, gebruikt u het volgende voorbeeld.

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

Als u een koppeling wilt definiëren als een ARM-sjabloon, gebruikt u het volgende voorbeeld als richtlijn:

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

Deze sectie bevat parameters die de set instructies definiëren die worden weergegeven op de pagina van uw gegevensconnector in Microsoft Sentinel en heeft de volgende structuur:

"instructionSteps": [
    {
        "title": "",
        "description": "",
        "instructions": [
        {
            "type": "",
            "parameters": {}
        }
        ],
        "innerSteps": {}
    }
]

Matrixeigenschap	Vereist	Type	Description
title		String	Definieert een titel voor uw instructies.
beschrijving		String	Definieert een beschrijvende beschrijving voor uw instructies.
innerSteps		Matrix	Definieert een matrix van interne instructiestappen.
Instructies	Waar	Matrix met instructies	Hiermee definieert u een matrix met instructies van een specifiek parametertype.

Instructies

Geeft een groep instructies weer, met verschillende parameters en de mogelijkheid om meer instructiesteps in groepen te nesten. Parameters die hier zijn gedefinieerd, komen overeen

Type	Matrixeigenschap	Beschrijving
OAuthForm	OAuthForm	Verbinding maken met OAuth
Textbox	Textbox	Deze paren met `ConnectionToggleButton`. Er zijn vier beschikbare typen: `password` `text` `number` `email`
Verbinding maken ionToggleButton	Verbinding maken ionToggleButton	Activeer de implementatie van de DCR op basis van de verbindingsgegevens die zijn opgegeven via tijdelijke aanduidingsparameters. De volgende parameters worden ondersteund: `name` :Verplicht `disabled` `isPrimary` `connectLabel` `disconnectLabel`
CopyableLabel	CopyableLabel	Toont een tekstveld met een knop Kopiëren aan het einde. Wanneer de knop is geselecteerd, wordt de waarde van het veld gekopieerd.
InfoMessage	InfoMessage	Definieert een inline informatiebericht.
InstructionStepsGroup	InstructionStepsGroup	Geeft een groep instructies weer, eventueel uitgevouwen of samenvouwbaar, in een afzonderlijke sectie met instructies.
InstallAgent	InstallAgent	Geeft een koppeling weer naar andere gedeelten van Azure om aan verschillende installatievereisten te voldoen.

OAuthForm

Dit onderdeel vereist dat het OAuth2 type aanwezig is in de auth eigenschap van de gegevensconnectorsjabloon.

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

Textbox

Hier volgen enkele voorbeelden van het Textbox type. Deze voorbeelden komen overeen met de parameters die worden gebruikt in de voorbeeldsectie auth in de naslaginformatie over gegevensconnectors voor het codeloze Verbinding maken orPlatform. Voor elk van de vier typen heeft elk type label, placeholderen 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"
  }
}
]

Verbinding maken ionToggleButton

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

CopyableLabel

Voorbeeld:

Screenshot of a copy value button in a field.

Voorbeeldcode:

{
    "parameters": {
        "fillWith": [
            "WorkspaceId",
            "PrimaryKey"
            ],
        "label": "Here are some values you'll need to proceed.",
        "value": "Workspace is {0} and PrimaryKey is {1}"
    },
    "type": "CopyableLabel"
}

Matrixwaarde	Vereist	Type	Description
fillWith		ENUM	Matrix van omgevingsvariabelen die worden gebruikt om een tijdelijke aanduiding te vullen. Scheid meerdere tijdelijke aanduidingen met komma's. Bijvoorbeeld: `{0},{1}` Ondersteunde waarden: `workspaceId`, `workspaceName`, `primaryKey`, , `MicrosoftAwsAccountsubscriptionId`
Label	Waar	String	Hiermee definieert u de tekst voor het label boven een tekstvak.
value	Waar	String	Definieert de waarde die in het tekstvak moet worden weergegeven, ondersteunt tijdelijke aanduidingen.
Rijen		Rijen	Hiermee definieert u de rijen in het gebied van de gebruikersinterface. Standaard ingesteld op 1.
wideLabel		Booleaanse waarde	Bepaalt een breed label voor lange tekenreeksen. Standaard ingesteld op `false`.

InfoMessage

Hier volgt een voorbeeld van een inline informatiebericht:

Screenshot of an inline information message.

In de volgende afbeelding ziet u daarentegen een informatiebericht dat niet inline is:

Screenshot of an information message that's not inline.

Matrixwaarde	Type	Beschrijving
tekst	String	Definieer de tekst die in het bericht moet worden weergegeven.
Zichtbaar	Booleaanse waarde	Bepaalt of het bericht wordt weergegeven.
Inline	Booleaanse waarde	Bepaalt hoe het informatiebericht wordt weergegeven. - `true`: (Aanbevolen) Toont het informatiebericht dat is ingesloten in de instructies. - `false`: Voegt een blauwe achtergrond toe.

InstructionStepsGroup

Hier volgt een voorbeeld van een uitbreidbare instructiegroep:

Screenshot of an expandable, extra instruction group.

Matrixwaarde	Vereist	Type	Description
title	Waar	String	Hiermee definieert u de titel voor de instructiestap.
beschrijving		String	Optionele beschrijvende tekst.
canCollapseAllSections		Booleaanse waarde	Bepaalt of de sectie een samenvouwbare accordeon is of niet.
noFxPadding		Booleaanse waarde	Als `true`, vermindert de hoogte opvulling om ruimte te besparen.
Uitgebreid		Booleaanse waarde	Als `true`, wordt standaard weergegeven als uitgevouwen.

Zie de configuratie-JSON voor de Windows DNS-connector voor een gedetailleerd voorbeeld.

InstallAgent

Sommige InstallAgent-typen worden weergegeven als een knop, andere worden weergegeven als een koppeling. Hier volgen voorbeelden van beide:

Screenshot of a link added as inline text.

Matrixwaarden	Vereist	Type	Description
linkType	Waar	ENUM	Bepaalt het koppelingstype als een van de volgende waarden: `InstallAgentOnWindowsVirtualMachine` `InstallAgentOnWindowsNonAzure` `InstallAgentOnLinuxVirtualMachine` `InstallAgentOnLinuxNonAzure` `OpenSyslogSettings` `OpenCustomLogsSettings` `OpenWaf` `OpenAzureFirewall` `OpenMicrosoftAzureMonitoring` `OpenFrontDoors` `OpenCdnProfile` `AutomaticDeploymentCEF` `OpenAzureInformationProtection` `OpenAzureActivityLog` `OpenIotPricingModel` `OpenPolicyAssignment` `OpenAllAssignmentsBlade` `OpenCreateDataCollectionRule`
policyDefinitionGuid	Waar wanneer u linkType gebruikt `OpenPolicyAssignment` .	String	Voor connectors op basis van beleid definieert u de GUID van de ingebouwde beleidsdefinitie.
assignMode		ENUM	Voor connectors op basis van beleid definieert u de toewijzingsmodus als een van de volgende waarden: `InitiativePolicy`
dataCollectionRuleType		ENUM	Voor connectors op basis van DCR definieert u het type regeltype voor gegevensverzameling als , `SecurityEvent`of `ForwardEvent`.

Voorbeeld van definitie van gegevensconnector

In het volgende voorbeeld worden enkele van de onderdelen die in dit artikel zijn gedefinieerd, samengevoegd als een JSON-hoofdtekstindeling voor gebruik met de definitie-API voor het maken of bijwerken van de gegevensconnector.

Voor meer voorbeelden van de connectorUiConfig beoordeling van andere CTP-gegevensconnectors. Zelfs connectors die de verouderde CTP gebruiken, hebben geldige voorbeelden van het maken van de gebruikersinterface.

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

Delen via