Informazioni di riferimento sulle definizioni del connettore dati per la piattaforma del connettore codeless

Articolo
07/03/2024

Per creare un connettore dati con codeless Connector Platform (CCP), usare questo documento come supplemento alla documentazione di riferimento sulle definizioni del connettore dati dell'API REST di Microsoft Sentinel per data connector. In particolare, questo documento di riferimento si espande nella sezione seguente:

connectorUiConfig : definisce gli elementi visivi e il testo visualizzati nella pagina del connettore dati in Microsoft Sentinel.

Per altre informazioni, vedere Creare un connettore senza codice.

Definizioni del connettore dati - Creare o aggiornare

Fare riferimento all'operazione Di creazione o aggiornamento nella documentazione dell'API REST per trovare la versione più recente dell'API stabile o di anteprima. Solo l'operazione update richiede il etag valore .

PUT , metodo

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

Parametri URI

Per altre informazioni sulla versione più recente dell'API, vedere Definizioni del connettore dati - Creare o aggiornare i parametri URI

Nome	Descrizione
dataConnectorDefinitionName	La definizione del connettore dati deve essere un nome univoco e corrisponde al `name` parametro nel corpo della richiesta.
resourceGroupName	Nome del gruppo di risorse, senza distinzione tra maiuscole e minuscole.
subscriptionId	ID della sottoscrizione di destinazione.
workspaceName	Nome dell'area di lavoro, non ID. Modello regex: `^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$`
api-version	Versione dell'API da usare per questa operazione.

Testo della richiesta

Il corpo della richiesta per la creazione di una definizione di connettore dati CCP con l'API ha la struttura seguente:

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

dataConnectorDefinition ha le proprietà seguenti:

Nome	Obbligatorio	Type	Descrizione
Tipologia	Vero	String	`Customizable` per il connettore dati di polling dell'API o `Static` in caso contrario
proprietà.connectorUiConfig	Vero	JSON annidato connectorUiConfig	Proprietà di configurazione dell'interfaccia utente del connettore dati

Configurare l'interfaccia utente del connettore

Questa sezione descrive le opzioni di configurazione disponibili per personalizzare l'interfaccia utente della pagina del connettore dati.

Lo screenshot seguente mostra una pagina del connettore dati di esempio, evidenziata con numeri che corrispondono alle aree rilevanti dell'interfaccia utente.

Screenshot di una pagina del connettore dati di esempio con sezioni con etichetta da 1 a 9.

Ognuno degli elementi seguenti della connectorUiConfig sezione necessaria per configurare l'interfaccia utente corrisponde alla parte PersonalizzabileConnectorUiConfig dell'API.

Campo	Richiesto	Type	Descrizione	Screenshot dell'area rilevante #
title	Vero	string	Titolo visualizzato nella pagina del connettore dati	1
id		string	Imposta l'ID connettore personalizzato per l'utilizzo interno
logo		string	Percorso del file di immagine in formato SVG. Se non è configurato alcun valore, viene usato un logo predefinito.	2
publisher	Vero	string	Provider del connettore	3
descriptionMarkdown	Vero	stringa in markdown	Descrizione per il connettore con la possibilità di aggiungere il linguaggio markdown per migliorarlo.	4
sampleQueries	Vero	JSON annidato sampleQueries	Query per il cliente per comprendere come trovare i dati nel registro eventi.
graphQueries	Vero	JSON annidato graphQueries	Query che presentano l'inserimento dati nelle ultime due settimane. Specificare una query per tutti i tipi di dati del connettore dati o una query differente per ogni tipo di dati.	5
graphQueriesTableName		Imposta il nome della tabella su cui il connettore inserisce i dati. Questo nome può essere usato in altre query specificando `{{graphQueriesTableName}}` il segnaposto in `graphQueries` e `lastDataReceivedQuery` i valori.
dataTypes	Vero	JSON annidato dataTypes	Elenco di tutti i tipi di dati per il connettore e una query per recuperare l'ora dell'ultimo evento per ogni tipo di dati.	6
connectivityCriteria	Vero	JSON annidato connectivityCriteria	Oggetto che definisce come verificare se il connettore è connesso.	7
autorizzazioni	Vero	JSON annidato autorizzazioni	Le informazioni visualizzate nella sezione Prerequisiti dell'interfaccia utente, in cui sono elencate le autorizzazioni necessarie per abilitare o disabilitare il connettore.	8
instructionSteps	Vero	JSON annidato disposizioni	Matrice di parti del widget che spiegano come installare il connettore e i controlli interattivi visualizzati nella scheda Istruzioni .	9

connectivityCriteria

Campo	Richiesto	Type	Descrizione
Tipo	Vero	String	Una delle due opzioni seguenti: `HasDataConnectors` questo valore è ideale per i connettori dati di polling dell'API, ad esempio il CCP. Il connettore viene considerato connesso con almeno una connessione attiva. `isConnectedQuery` : questo valore è ideale per altri tipi di connettori dati. Il connettore viene considerato connesso quando la query specificata restituisce dati.
Valore	True quando il tipo è `isConnectedQuery`	String	Query per determinare se i dati sono ricevuti entro un determinato periodo di tempo. Ad esempio: `CommonSecurityLog \| where DeviceVendor == \"Vectra Networks\"\n\| where DeviceProduct == \"X Series\"\n \| summarize LastLogReceived = max(TimeGenerated)\n \| project IsConnected = LastLogReceived > ago(7d)"`

dataTypes

Valore array	Tipo	Descrizione
name	string	Descrizione significativa per ,`lastDataReceivedQuery` incluso il supporto per la `graphQueriesTableName` variabile. Esempio: `{{graphQueriesTableName}}`
lastDataReceivedQuery	String	Query KQL che restituisce una riga e indica l'ultima volta in cui sono stati ricevuti i dati oppure nessun dato se non sono presenti risultati. Esempio: `{{graphQueriesTableName}}\n \| summarize Time = max(TimeGenerated)\n \| where isnotempty(Time)`

graphQueries

Definisce una query che presenta l'inserimento dati nelle ultime due settimane.

Specificare una query per tutti i tipi di dati del connettore dati o una query differente per ogni tipo di dati.

Valore array	Tipo	Descrizione
metricName	String	Nome significativo per il grafico. Esempio: `Total data received`
legenda	String	Stringa visualizzata nella legenda a destra del grafico, incluso un riferimento a una variabile. Esempio: `{{graphQueriesTableName}}`
baseQuery	String	Query che filtra gli eventi pertinenti, incluso un riferimento a una variabile. Ad esempio: `TableName_CL \| where ProviderName == "myprovider"` o `{{graphQueriesTableName}}`

autorizzazioni

Valore array	Tipo	Descrizione
dogana	String	Descrive le autorizzazioni personalizzate necessarie per la connessione dati, nella sintassi seguente: `{` `"name":`string`,` `"description":`stringa `}` Esempio: il valore doganale viene visualizzato nella sezione Prerequisiti di Microsoft Sentinel con un'icona informativa blu. Nell'esempio di GitHub questo valore è correlato alla riga Chiave del token personale dell'API GitHub: è necessario accedere al token personale di GitHub...
licenze	ENUM	Definisce le licenze necessarie, come uno dei valori seguenti: `OfficeIRM`,`OfficeATP`, `Office365`, `AadP1P2` `Aatp` `Mcas`, `Mdatp`, `Mtp`, `IoT` Esempio: il valore licenze viene visualizzato in Microsoft Sentinel come Licenza: Obbligatoria Azure AD Premium P2
resourceProvider	resourceProvider	Descrive tutti i prerequisiti per la risorsa di Azure. Esempio: il valore resourceProvider viene visualizzato nella sezione Prerequisiti di Microsoft Sentinel come: Area di lavoro: è necessaria l'autorizzazione di lettura e scrittura. Chiavi: sono necessarie le autorizzazioni di lettura per le chiavi condivise per l'area di lavoro.
tenant	array di valori ENUM Esempio: `"tenant": [` `"GlobalADmin",` `"SecurityAdmin"` `]`	Definisce le autorizzazioni necessarie, come uno o più dei valori seguenti: `"GlobalAdmin"`, `"SecurityAdmin"`, `"SecurityReader"`, `"InformationProtection"` Esempio: visualizza il valore del tenant in Microsoft Sentinel come: Autorizzazioni tenant: Richiede `Global Administrator` o `Security Administrator` nel tenant dell'area di lavoro

Importante

Microsoft consiglia di usare i ruoli con le autorizzazioni più poche. Ciò consente di migliorare la sicurezza per l'organizzazione. L'amministratore globale è un ruolo con privilegi elevati che deve essere limitato agli scenari di emergenza quando non è possibile usare un ruolo esistente.

resourceProvider

valore della array secondaria	Tipo	Descrizione
provider	ENUM	Descrive il provider di risorse, con uno dei valori seguenti: - `Microsoft.OperationalInsights/workspaces` - `Microsoft.OperationalInsights/solutions` - `Microsoft.OperationalInsights/workspaces/datasources` - `microsoft.aadiam/diagnosticSettings` - `Microsoft.OperationalInsights/workspaces/sharedKeys` - `Microsoft.Authorization/policyAssignments`
providerDisplayName	String	Voce di elenco in Prerequisiti che visualizza un segno di spunta rosso "x" o verde quando le richiestePermission vengono convalidate nella pagina del connettore. Esempio `"Workspace"`
permissionsDisplayText	String	Visualizzare il testo per le autorizzazioni Lettura, Scrittura o Lettura e scrittura che devono corrispondere ai valori configurati in requiredPermissions
requiredPermissions	`{` `"action":`Booleano`,` `"delete":`Booleano`,` `"read":`Booleano`,` `"write":`Booleano `}`	Descrive le autorizzazioni minime necessarie per il connettore.
ambito	ENUM	Descrive l'ambito del connettore dati, come uno dei valori seguenti: `"Subscription"`, `"ResourceGroup"`, `"Workspace"`

sampleQueries

valore array	Tipo	Descrizione
description	Stringa	Descrizione significativa per la query di esempio. Esempio: `Top 10 vulnerabilities detected`
query	String	Query di esempio usata per recuperare i dati del tipo di dati. Esempio: `{{graphQueriesTableName}}\n \| sort by TimeGenerated\n \| take 10`

Configurare altre opzioni di link

Per definire un link inline usando markdown, usare l'esempio seguente.

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

Per definire un link come modello di ARM, usare l'esempio seguente come guida:

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

Questa sezione fornisce i parametri che definiscono il set di istruzioni visualizzate nella pagina del connettore dati in Microsoft Sentinel e presenta la struttura seguente:

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

Array, proprietà	Richiesto	Type	Descrizione
title		String	Definisce un titolo per le istruzioni.
description		Stringa	Definisce una descrizione significativa per le istruzioni.
innerSteps		Array	Definisce un array di passaggi interni dell'istruzione.
disposizioni	Vero	Array di istruzioni	Definisce un array di istruzioni di un tipo di parametro specifico.

istruzioni

Visualizza un gruppo di istruzioni, con vari parametri e la possibilità di annidare più istruzioniSteps in gruppi. I parametri definiti qui corrispondono

Type	Proprietà Array	Descrizione
OAuthForm	OAuthForm	Connettersi con OAuth
Casella di testo	Casella di testo	Questa coppia con `ConnectionToggleButton`. Esistono 4 tipi disponibili: `password` `text` `number` `email`
ConnectionToggleButton	ConnectionToggleButton	Attivare la distribuzione del Registro Azure Container in base alle informazioni di connessione fornite tramite parametri segnaposto. Sono supportati i seguenti parametri: `name` :obbligatorio `disabled` `isPrimary` `connectLabel` `disconnectLabel`
CopyableLabel	CopyableLabel	Mostra un campo di testo con un pulsante di copia alla fine. Quando il pulsante è selezionato, il valore del campo viene copiato.
InfoMessage	InfoMessage	Definisce un messaggio informativo inline.
InstructionStepsGroup	InstructionStepsGroup	Visualizza un gruppo di istruzioni, facoltativamente espanso o comprimibile, in una sezione separata delle istruzioni.
InstallAgent	InstallAgent	Visualizza un link ad altre parti di Azure per soddisfare vari requisiti di installazione.

OAuthForm

Questo componente richiede che il OAuth2 tipo sia presente nella auth proprietà del modello di connettore dati.

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

Casella di testo

Ecco alcuni esempi del Textbox tipo. Questi esempi corrispondono ai parametri usati nella sezione di esempio auth dei riferimenti ai connettori dati per la piattaforma del connettore codeless. Per ognuno dei 4 tipi, ognuno ha label, placeholdere 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

Esempio:

Screenshot di un pulsante copia valore in un campo.

Codice di esempio:

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

Valore array	Richiesto	Type	Descrizione
fillWith		ENUM	Matrice di variabili di ambiente usate per popolare un segnaposto. Separare più segnaposto con virgole. Ad esempio: `{0},{1}` Valori supportati: `workspaceId`, `workspaceName`, `primaryKey`, `MicrosoftAwsAccount`, `subscriptionId`
label	Vero	String	Definisce il testo per l'etichetta sopra una casella di testo.
value	Vero	String	Definisce il valore da presentare nella casella di testo, supporta i segnaposto.
rows		Righe	Definisce le righe nell'area dell'interfaccia utente. Per impostazione predefinita, impostare su 1.
wideLabel		Booleano	Determina un'etichetta wide per stringhe lunghe. Per impostazione predefinita, impostare su `false`.

InfoMessage

Ecco un esempio di messaggio informativo inline:

Screenshot di un messaggio informativo inline.

Al contrario, l'immagine seguente mostra un messaggio informativo non inline:

Screenshot di un messaggio informativo non inline.

Valore array	Tipo	Descrizione
Testo	String	Definire il testo da visualizzare nella finestra di messaggio.
visibile	Booleano	Determina se il messaggio viene visualizzato.
inline	Booleano	Determina la modalità di visualizzazione del messaggio informativo. - `true`: (Scelta consigliata) Mostra il messaggio informativo incorporato nelle istruzioni. - `false`: aggiunge uno sfondo blu.

InstructionStepsGroup

Di seguito è riportato un esempio di gruppo di istruzioni espandibile:

Screenshot di un gruppo di istruzioni aggiuntivo espandibile.

Valore array	Richiesto	Type	Descrizione
title	Vero	String	Definisce il titolo per il passaggio dell'istruzione.
description		Stringa	Testo descrittivo facoltativo.
canCollapseAllSections		Booleano	Determina se la sezione è o meno una fisarmonica comprimibile.
noFxPadding		Booleano	Se `true`, riduce la spaziatura interna dell'altezza per risparmiare spazio.
esteso		Booleano	Se `true`, viene visualizzato come espanso per impostazione predefinita.

Per un esempio dettagliato, vedere il codice JSON di configurazione per il connettore DNS Windows.

InstallAgent

Alcuni tipi InstallAgent vengono visualizzati come pulsante, altri vengono visualizzati come collegamento. Ecco alcuni esempi di entrambi:

Screenshot di un link aggiunto come testo inline.

Valori di matrice	Richiesto	Type	Descrizione
linkType	Vero	ENUM	Determina il tipo di link, come uno dei valori seguenti: `InstallAgentOnWindowsVirtualMachine` `InstallAgentOnWindowsNonAzure` `InstallAgentOnLinuxVirtualMachine` `InstallAgentOnLinuxNonAzure` `OpenSyslogSettings` `OpenCustomLogsSettings` `OpenWaf` `OpenAzureFirewall` `OpenMicrosoftAzureMonitoring` `OpenFrontDoors` `OpenCdnProfile` `AutomaticDeploymentCEF` `OpenAzureInformationProtection` `OpenAzureActivityLog` `OpenIotPricingModel` `OpenPolicyAssignment` `OpenAllAssignmentsBlade` `OpenCreateDataCollectionRule`
policyDefinitionGuid	True quando si usa `OpenPolicyAssignment` linkType.	String	Per i connettori basati su criteri, definisce il GUID della definizione di criteri predefinita.
assignMode		ENUM	Per i connettori basati su criteri, definisce la modalità di assegnazione, come uno dei valori seguenti: `Initiative`, `Policy`
dataCollectionRuleType		ENUM	Per i connettori basati su DCR, definisce il tipo di regola di raccolta dati come `SecurityEvent`, o `ForwardEvent`.

Definizione del connettore dati di esempio

L'esempio seguente riunisce alcuni dei componenti definiti in questo articolo come formato del corpo JSON da usare con l'API di definizione del connettore dati Create Or Update.

Per altri esempi degli connectorUiConfig altri connettori dati CCP. Anche i connettori che usano il CCP legacy hanno esempi validi della creazione dell'interfaccia utente.

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

Condividi tramite