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

Článek
07/03/2024

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

Důležité

Microsoft doporučuje používat role s nejmenšími oprávněními. To pomáhá zlepšit zabezpečení pro vaši organizaci. Globální správce je vysoce privilegovaná role, která by měla být omezená na scénáře tísňového volání, pokud nemůžete použít existující roli.

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`

Konfigurace dalších možností propojení

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 `true`sníží odsazení výšky, aby se ušetřilo místo.
rozšířený		Logická hodnota	Pokud `true`se 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 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 `SecurityEvent`buď , 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"
                  }
                }
              ]
            }
          ]
        }
    }
}

Sdílet prostřednictvím