Delen via

Naslaginformatie over definities van gegevensconnector voor het Platform voor codeloze connectors

  • Artikel

Als u een gegevensconnector wilt maken met het Codeless Connector Platform (CCP), gebruikt u dit document als aanvulling op de Microsoft Sentinel REST API voor dataconnectordefinities 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 Connector Definitions - Create or Update URI Parameters (URI-parameters maken of bijwerken) voor meer informatie over de nieuwste API-versie

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

dataConnectorDefinition 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.

Schermopname van een pagina met voorbeeldgegevensconnector met secties met het label 1 tot en met 9.

Elk van de volgende elementen van de connectorUiConfig sectie die nodig is om de gebruikersinterface te configureren, komt overeen met het gedeelte CustomizableConnectorUiConfig 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
uitgever 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 delastDataReceivedQuery 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":snaar,
"description":snaar
}

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

Belangrijk

Microsoft raadt u aan rollen te gebruiken met de minste machtigingen. Dit helpt de beveiliging voor uw organisatie te verbeteren. Globale beheerder is een zeer bevoorrechte rol die moet worden beperkt tot scenario's voor noodgevallen wanneer u geen bestaande rol kunt gebruiken.

resourceProvider

submatrixwaarde Type Description
aanbieder 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":Booleaans
}		 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

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
Tekstvak Tekstvak Deze paren met ConnectionToggleButton. Er zijn vier beschikbare typen:
  • password
  • text
  • number
  • email
    		•
    ConnectionToggleButton ConnectionToggleButton 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"
  }          
}
]

    Tekstvak

    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 Platform voor codeloze connectors. 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"
  }
}
]

    ConnectionToggleButton

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

    CopyableLabel

    Voorbeeld:

    Schermopname van de knop Waarde kopiëren in een veld.

    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
    etiket 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:

    Schermopname van een inline-informatiebericht.

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

    Schermopname van een informatiebericht dat niet inline is.

    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:

    Schermopname van een uitbreidbare, extra instructiegroep.

    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:

    Schermopname van een koppeling die als knop is toegevoegd.

    Schermopname van een koppeling die is toegevoegd als inlinetekst.

    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 , SecurityEventof 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"
                  }
                }
              ]
            }
          ]
        }
    }
}