Sdílet prostřednictvím

Referenční informace o definicích datových konektorů pro platformu bez kódu

  • Článek

Pokud chcete vytvořit datový konektor s platformou konektoru bez kódu (CCP), použijte tento dokument jako doplněk k referenční dokumentaci k rozhraní REST API služby Microsoft Sentinel pro definice datových konektorů . Konkrétně tento referenční dokument rozbalí následující část:

  • connectorUiConfig – definuje vizuální prvky a text zobrazený na stránce datového konektoru v Microsoft Sentinelu.

Další informace najdete v tématu Vytvoření bezkódového konektoru.

Definice datových konektorů – Vytvoření nebo aktualizace

V dokumentaci k rozhraní REST API vyhledejte nejnovější stabilní nebo náhledové verze rozhraní API. update Tuto hodnotu vyžaduje etag pouze operace.

Metoda PUT

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

Parametry identifikátoru URI

Další informace o nejnovější verzi rozhraní API najdete v tématu Definice datového konektoru – Vytvoření nebo aktualizace parametrů identifikátoru URI.

Název Popis
dataConnectorDefinitionName Definice datového konektoru musí být jedinečný název a je stejný jako name parametr v textu požadavku.
resourceGroupName Název skupiny prostředků, nerozlišuje se malá a velká písmena.
subscriptionId ID cílového předplatného.
workspaceName Název pracovního prostoru, nikoli ID.
Vzor regulárních výrazů: ^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$
api-version Verze rozhraní API, která se má použít pro tuto operaci.

Text požadavku

Text požadavku pro vytvoření definice datového konektoru ÚSTŘEDNÍ PROTISTRANy s rozhraním API má následující strukturu:

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

dataConnectorDefinition má následující vlastnosti:

Název Požadováno Type Popis
Kind True String Customizable pro datový konektor pro dotazování rozhraní API nebo Static jinak
vlastnosti.connectorUiConfig True Vnořený JSON
connectorUiConfig		 Vlastnosti konfigurace uživatelského rozhraní datového konektoru

Konfigurace uživatelského rozhraní konektoru

Tato část popisuje možnosti konfigurace, které jsou k dispozici pro přizpůsobení uživatelského rozhraní stránky datového konektoru.

Následující snímek obrazovky ukazuje ukázkovou stránku datového konektoru se zvýrazněnou čísly, která odpovídají oblastem uživatelského rozhraní.

Snímek obrazovky se stránkou ukázkového datového konektoru s oddíly označenými jako 1 až 9

Každý z následujících prvků oddílu connectorUiConfig potřebných ke konfiguraci uživatelského rozhraní odpovídá části PřizpůsobitelnéConnectorUiConfig rozhraní API.

Pole Požaduje se Type Popis Snímek obrazovky s výsečnou oblastí #
title True string Název zobrazený na stránce datového konektoru 0
id řetězec Nastaví ID vlastního konektoru pro interní použití.
logo string Cesta k souboru obrázku ve formátu SVG Pokud není nakonfigurovaná žádná hodnota, použije se výchozí logo. 2
vydavatel True string Poskytovatel konektoru 3
descriptionMarkdown True řetězec v markdownu Popis konektoru s možností přidat jazyk Markdown, který ho vylepšuje. 4
sampleQueries True Vnořený JSON
sampleQueries		 Dotazy pro zákazníka, aby pochopili, jak najít data v protokolu událostí.
GraphQueries True Vnořený JSON
GraphQueries		 Dotazy, které představují příjem dat za poslední dva týdny

Zadejte jeden dotaz pro všechny datové typy datového konektoru nebo jiný dotaz pro každý datový typ.		 5
graphQueriesTableName Nastaví název tabulky, do které konektor vloží data. Tento název lze použít v jiných dotazech zadáním {{graphQueriesTableName}} zástupného symbolu graphQueries a lastDataReceivedQuery hodnot.
datové typy True Vnořený JSON
datové typy		 Seznam všech datových typů konektoru a dotaz pro načtení času poslední události pro každý datový typ. 6
connectivityCriteria True Vnořený JSON
connectivityCriteria		 Objekt, který definuje, jak ověřit, jestli je konektor připojený. 7
permissions True Vnořený JSON
permissions		 Informace zobrazené v části Požadavky uživatelského rozhraní uvádějící oprávnění potřebná k povolení nebo zakázání konektoru. 8
instructionSteps True Vnořený JSON
instrukce		 Pole částí widgetu, které vysvětlují, jak nainstalovat konektor, a ovládací prvky s možností akce zobrazené na kartě Pokyny . 9

connectivityCriteria

Pole Požaduje se Type Popis
Typ True String Jedna ze dvou následujících možností: HasDataConnectors tato hodnota je nejvhodnější pro datové konektory rozhraní API pro dotazování, jako je ústřední protistrana. Konektor se považuje za připojený aspoň s jedním aktivním připojením.

isConnectedQuery – tato hodnota je nejvhodnější pro jiné typy datových konektorů. Konektor se považuje za připojený, když zadaný dotaz vrátí data.
Hodnota True when type is isConnectedQuery String Dotaz, který určí, jestli se data přijímají během určitého časového období. Příklad: CommonSecurityLog | where DeviceVendor == \"Vectra Networks\"\n| where DeviceProduct == \"X Series\"\n | summarize LastLogReceived = max(TimeGenerated)\n | project IsConnected = LastLogReceived > ago(7d)"

datové typy

Hodnota pole Typ Popis
Jméno String Smysluplný popis proměnnélastDataReceivedQuery, včetně podpory graphQueriesTableName proměnné.

Příklad: {{graphQueriesTableName}}
lastDataReceivedQuery String Dotaz KQL, který vrátí jeden řádek, a označuje čas posledního přijetí dat nebo žádná data, pokud neexistují žádné výsledky.

Příklad: {{graphQueriesTableName}}\n | summarize Time = max(TimeGenerated)\n | where isnotempty(Time)

GraphQueries

Definuje dotaz, který prezentuje příjem dat za poslední dva týdny.

Zadejte jeden dotaz pro všechny datové typy datového konektoru nebo jiný dotaz pro každý datový typ.

Hodnota pole Typ Popis
metricName String Smysluplný název grafu

Příklad: Total data received
legenda String Řetězec, který se zobrazí v legendě napravo od grafu, včetně odkazu na proměnnou.

Příklad: {{graphQueriesTableName}}
baseQuery String Dotaz, který filtruje relevantní události, včetně odkazu na proměnnou.

Příklad: TableName_CL | where ProviderName == "myprovider" nebo {{graphQueriesTableName}}

oprávnění

Hodnota pole Typ Popis
clo String Popisuje všechna vlastní oprávnění požadovaná pro vaše datové připojení v následující syntaxi:
{
"name":string,
"description":řetězec
}

Příklad: Celní hodnota se zobrazí v části Požadavky služby Microsoft Sentinel s modrou informační ikonou. V příkladu GitHubu tato hodnota koreluje s řádkem klíč osobního tokenu rozhraní API GitHubu: Potřebujete přístup k osobnímu tokenu GitHubu...
opravňuje licencí VÝČET Definuje požadované licence jako jednu z následujících hodnot: OfficeIRM,OfficeATP, Office365, AadP1P2, Mcas, Aatp, Mdatp, MtpIoT

Příklad: Hodnota licencí se zobrazí v Microsoft Sentinelu jako: Licence: Povinné Azure AD Premium P2
resourceProvider resourceProvider Popisuje všechny požadavky pro váš prostředek Azure.

Příklad: Hodnota resourceProvider se zobrazí v části Požadavky služby Microsoft Sentinel jako:
Pracovní prostor: Vyžaduje se oprávnění ke čtení a zápisu.
Klíče: Vyžaduje se oprávnění ke čtení sdílených klíčů pro pracovní prostor.
nájemce pole hodnot ENUM
Příklad:

"tenant": [
"GlobalADmin",
"SecurityAdmin"
]
 Definuje požadovaná oprávnění jako jednu nebo více následujících hodnot: "GlobalAdmin", "SecurityAdmin", , "SecurityReader""InformationProtection"

Příklad: Zobrazí hodnotu tenanta v Microsoft Sentinelu jako: Oprávnění tenanta: Vyžaduje Global Administrator nebo Security Administrator v tenantovi pracovního prostoru.

resourceProvider

hodnota dílčího pole Typ Popis
poskytovatel VÝČET Popisuje poskytovatele prostředků s jednou z následujících hodnot:
- Microsoft.OperationalInsights/workspaces
- Microsoft.OperationalInsights/solutions
- Microsoft.OperationalInsights/workspaces/datasources
- microsoft.aadiam/diagnosticSettings
- Microsoft.OperationalInsights/workspaces/sharedKeys
- Microsoft.Authorization/policyAssignments
providerDisplayName String Položka seznamu v části Požadavky, která při ověření požadovaného zadání na stránce konektoru zobrazí červenou značku x nebo zelené zaškrtnutí. Příklad "Workspace"
permissionsDisplayText String Zobrazovaný text pro oprávnění ke čtení, zápisu nebo čtení a zápisu, která by měla odpovídat hodnotám nakonfigurovaným v requiredPermissions
requiredPermissions {
"action":Logická hodnota,
"delete":Logická hodnota,
"read":Logická hodnota,
"write":Booleovský
}		 Popisuje minimální oprávnění požadovaná pro konektor.
rozsah VÝČET Popisuje rozsah datového konektoru jako jednu z následujících hodnot: "Subscription", , "ResourceGroup""Workspace"

sampleQueries

maticová hodnota Typ Popis
popis String Smysluplný popis ukázkového dotazu

Příklad: Top 10 vulnerabilities detected
query String Ukázkový dotaz použitý k načtení dat datového typu

Příklad: {{graphQueriesTableName}}\n | sort by TimeGenerated\n | take 10

Pokud chcete definovat vložený odkaz pomocí markdownu, použijte následující příklad.

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

Pokud chcete definovat odkaz jako šablonu ARM, použijte jako vodítko následující příklad:

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

Tato část obsahuje parametry, které definují sadu instrukcí, které se zobrazují na stránce datového konektoru v Microsoft Sentinelu a mají následující strukturu:

"instructionSteps": [
    {
        "title": "",
        "description": "",
        "instructions": [
        {
            "type": "",
            "parameters": {}
        }
        ],
        "innerSteps": {}
    }
]
Array – vlastnost Požaduje se Type Popis
title String Definuje název pro vaše pokyny.
popis String Definuje smysluplný popis pokynů.
innerSteps Pole Definuje pole vnitřních kroků instrukce.
instrukce True Pole instrukcí Definuje pole instrukcí konkrétního typu parametru.

pokyny

Zobrazí skupinu instrukcí s různými parametry a možností vnořit do skupin další pokyny. Parametry definované zde odpovídají

Typ Vlastnost Pole Popis
OAuthForm OAuthForm Připojení pomocí OAuth
Textové pole Textové pole To se páruje s ConnectionToggleButton. Existují 4 dostupné typy:
  • password
  • text
  • number
  • email
    		•
    ConnectionToggleButton ConnectionToggleButton Aktivujte nasazení dcR na základě informací o připojení poskytovaných prostřednictvím parametrů zástupného symbolu. Podporují se následující parametry:
  • name :povinný
  • disabled
  • isPrimary
  • connectLabel
  • disconnectLabel
    		•
    CopyableLabel CopyableLabel Zobrazuje textové pole s tlačítkem pro kopírování na konci. Po výběru tlačítka se hodnota pole zkopíruje.
    InfoMessage InfoMessage Definuje vloženou informační zprávu.
    InstructionStepsGroup InstructionStepsGroup Zobrazí skupinu instrukcí, volitelně rozbalené nebo sbalitelné, v samostatné části s pokyny.
    InstallAgent InstallAgent Zobrazí odkaz na další části Azure, aby bylo možné splnit různé požadavky na instalaci.

    OAuthForm

    Tato komponenta vyžaduje, aby OAuth2 typ byl ve auth vlastnosti šablony datového konektoru.

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

    Textové pole

    Tady je několik příkladů Textbox typu. Tyto příklady odpovídají parametrům použitým v ukázkové auth části v referenčních informacích datových konektorů pro platformu bez kódu. Pro každý ze 4 typů má labelkaždý z nich , placeholdera 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

    Příklad:

    Snímek obrazovky s tlačítkem kopírovat hodnotu v poli

    Ukázkový kód:

    {
    "parameters": {
        "fillWith": [
            "WorkspaceId",
            "PrimaryKey"
            ],
        "label": "Here are some values you'll need to proceed.",
        "value": "Workspace is {0} and PrimaryKey is {1}"
    },
    "type": "CopyableLabel"
}
    Hodnota pole Požaduje se Type Popis
    fillWith VÝČET Pole proměnných prostředí sloužících k naplnění zástupného symbolu Oddělte více zástupných symbolů čárkami. Příklad: {0},{1}

    Podporované hodnoty: workspaceId, workspaceName, primaryKey, MicrosoftAwsAccountsubscriptionId
    označit True String Definuje text pro popisek nad textovým polem.
    value True String Definuje hodnotu, která se má v textovém poli prezentovat, podporuje zástupné symboly.
    řádky Řádky Definuje řádky v oblasti uživatelského rozhraní. Ve výchozím nastavení je nastavená hodnota 1.
    wideLabel Logická hodnota Určuje široký popisek dlouhých řetězců. Ve výchozím nastavení je nastavena hodnota false.

    InfoMessage

    Tady je příklad vložené informační zprávy:

    Snímek obrazovky s vloženou informační zprávou

    Naproti tomu následující obrázek ukazuje informační zprávu, která není vložená:

    Snímek obrazovky s informační zprávou, která není vložená

    Hodnota pole Typ Popis
    text String Definujte text, který se má zobrazit ve zprávě.
    viditelný Logická hodnota Určuje, zda je zpráva zobrazena.
    vložený Logická hodnota Určuje způsob zobrazení informační zprávy.

    - true: (Doporučeno) Zobrazí informační zprávu vloženou v pokynech.
    - false: Přidá modré pozadí.

    InstructionStepsGroup

    Tady je příklad rozbalitelné skupiny instrukcí:

    Snímek obrazovky s rozbalitelnou skupinou s dalšími instrukcemi

    Hodnota pole Požaduje se Type Popis
    title True String Definuje název kroku instrukce.
    popis String Nepovinný popisný text
    canCollapseAllSections Logická hodnota Určuje, zda je oddíl sbalitelným akordeonem nebo ne.
    noFxPadding Logická hodnota Pokud truesníží odsazení výšky, aby se ušetřilo místo.
    rozšířený Logická hodnota Pokud truese ve výchozím nastavení zobrazí jako rozbalené.

    Podrobný příklad najdete v souboru JSON konfigurace konektoru DNS systému Windows.

    InstallAgent

    Některé typy InstallAgent se zobrazují jako tlačítko, jiné se zobrazují jako odkaz. Tady jsou příklady obou:

    Snímek obrazovky s odkazem přidaným jako tlačítko

    Snímek obrazovky s odkazem přidaným jako vložený text

    Hodnoty pole Požaduje se Type Popis
    linkType True VÝČET Určuje typ propojení jako jednu z následujících hodnot:

    InstallAgentOnWindowsVirtualMachine
    InstallAgentOnWindowsNonAzure
    InstallAgentOnLinuxVirtualMachine
    InstallAgentOnLinuxNonAzure
    OpenSyslogSettings
    OpenCustomLogsSettings
    OpenWaf
    OpenAzureFirewall OpenMicrosoftAzureMonitoring
    OpenFrontDoors
    OpenCdnProfile
    AutomaticDeploymentCEF
    OpenAzureInformationProtection
    OpenAzureActivityLog
    OpenIotPricingModel
    OpenPolicyAssignment
    OpenAllAssignmentsBlade
    OpenCreateDataCollectionRule
    policyDefinitionGuid True při použití OpenPolicyAssignment linkType. String Pro konektory založené na zásadách definuje identifikátor GUID předdefinované definice zásad.
    assignMode VÝČET Pro konektory založené na zásadách definuje režim přiřazení jako jednu z následujících hodnot: Initiative, Policy
    dataCollectionRuleType VÝČET Pro konektory založené na DCR definuje typ pravidla shromažďování dat jako SecurityEventbuď , nebo ForwardEvent.

    Příklad definice datového konektoru

    Následující příklad spojuje některé komponenty definované v tomto článku jako základní formát JSON pro použití s rozhraním API pro vytvoření nebo aktualizaci definice datového konektoru.

    Další příklady kontroly jiných datových connectorUiConfig konektorů ústřední protistrany. Platné příklady vytvoření uživatelského rozhraní mají dokonce i konektory používající starší verzi ústřední protistrany.

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