Informations de référence sur les définitions de connecteur de données pour l’infrastructure de connecteur sans code

Pour créer un connecteur de données avec CCF (Codeless Connector Framework), utilisez ce document en complément de la documentation de référence de l’API REST Microsoft Sentinel pour les définitions de connecteur de données. Plus précisément, ce document de référence développe la section suivante :

  • connectorUiConfig: définit les éléments visuels et le texte affichés sur la page du connecteur de données dans Microsoft Sentinel.

Pour plus d’informations, consultez Créer un connecteur sans code.

Définitions de connecteur de données - Créer ou mettre à jour

Reportez-vous à l’opération Créer ou mettre à jour dans la documentation de l’API REST pour trouver la dernière version stable ou préliminaire de l’API. Seule l’opération update nécessite la etag valeur .

PUT , méthode

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

Paramètres d’URI

Pour plus d’informations sur la dernière version de l’API, consultez Définitions de connecteur de données - Créer ou mettre à jour des paramètres d’URI

Nom Description
dataConnectorDefinitionName La définition du connecteur de données doit être un nom unique et est identique au name paramètre dans le corps de la demande.
resourceGroupName Nom du groupe de ressources, qui ne respecte pas la casse.
subscriptionId ID de l’abonnement cible.
workspaceName Nom de l’espace de travail, pas l’ID.
Modèle d’expression régulière : ^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$
api-version Version de l’API à utiliser pour cette opération.

Corps de la demande

Le corps de la demande pour la création d’une définition de connecteur de données CCF avec l’API a la structure suivante :

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

dataConnectorDefinition a les propriétés suivantes :

Nom Obligatoire Type Description
Kind Vrai String Customizable pour le connecteur de données d’interrogation d’API ou Static autrement
Propriétés. connectorUiConfig Vrai JSON imbriqué
connectorUiConfig		 Propriétés de configuration de l’interface utilisateur du connecteur de données

Configurer l’interface utilisateur de votre connecteur

Cette section décrit les options de configuration disponibles pour personnaliser l’interface utilisateur de la page du connecteur de données.

La capture d’écran suivante montre un exemple de page de connecteur de données, mis en surbrillance avec des nombres qui correspondent à des zones notables de l’interface utilisateur.

Capture d’écran d’un exemple de page de connecteur de données avec les sections étiquetées 1 à 9.

Chacun des éléments suivants de la section nécessaire à la connectorUiConfig configuration de l’interface utilisateur correspond à la partie CustomizableConnectorUiConfig de l’API.

Field Obligatoire Type Description Capture d’écran de la zone notable #
title True string Titre affiché dans la page du connecteur de données 1
id chaîne Définit l’ID de connecteur personnalisé pour l’utilisation interne
logo string Chemin d’accès au fichier image au format SVG. Si aucune valeur n’est configurée, un logo par défaut est utilisé. 2
Éditeur True string Fournisseur du connecteur 3
descriptionMarkdown Vrai chaîne dans Markdown Description du connecteur avec la possibilité d’ajouter le langage Markdown pour l’améliorer. 4
sampleQueries Vrai JSON imbriqué
sampleQueries		 Interroge le client pour comprendre comment trouver les données dans le journal des événements.
graphQueries Vrai JSON imbriqué
graphQueries		 Requêtes qui présentent l’ingestion des données au cours des deux dernières semaines.

Fournissez une requête pour tous les types de données du connecteur de données, ou une requête différente pour chaque type de données.		 5
graphQueriesTableName Définit le nom de la table dans laquelle le connecteur insère les données. Ce nom peut être utilisé dans d’autres requêtes en spécifiant un {{graphQueriesTableName}} espace réservé dans graphQueries les valeurs et lastDataReceivedQuery .
dataTypes Vrai JSON imbriqué
dataTypes		 Liste de tous les types de données pour votre connecteur et requête permettant d’extraire l’heure du dernier événement pour chaque type de données. 6
connectivityCriteria Vrai JSON imbriqué
connectivityCriteria		 Objet qui définit comment vérifier si le connecteur est connecté. 7
Disponibilité JSON imbriqué
Disponibilité		 Objet qui définit la status de disponibilité du connecteur.
autorisations Vrai JSON imbriqué
autorisations		 Informations affichées sous la section Prérequis de l’interface utilisateur, qui répertorie les autorisations requises pour activer ou désactiver le connecteur. 8
instructionSteps Vrai JSON imbriqué
Instructions		 Tableau de composants de widget qui expliquent comment installer le connecteur et les contrôles actionnables affichés sous l’onglet Instructions . 9
isConnectivityCriteriasMatchSome Booléen Boolean indiquant s’il faut utiliser 'OR'(SOME) ou 'AND' entre les éléments ConnectivityCriteria.

connectivityCriteria

Field Obligatoire Type Description
Type Vrai String Une des deux options suivantes : HasDataConnectors – cette valeur est idéale pour les connecteurs de données d’interrogation d’API tels que le CCF. Le connecteur est considéré comme connecté avec au moins une connexion active.

isConnectedQuery : cette valeur est idéale pour d’autres types de connecteurs de données. Le connecteur est considéré comme connecté lorsque la requête fournie retourne des données.
Valeur True lorsque le type est isConnectedQuery String Requête permettant de déterminer si des données sont reçues au cours d’une certaine période. Par exemple : CommonSecurityLog | where DeviceVendor == \"Vectra Networks\"\n| where DeviceProduct == \"X Series\"\n | summarize LastLogReceived = max(TimeGenerated)\n | project IsConnected = LastLogReceived > ago(7d)"

dataTypes

Valeur du tableau Type Description
name String Description explicite de, y compris lalastDataReceivedQuery prise en charge de la graphQueriesTableName variable.

Exemple : {{graphQueriesTableName}}
lastDataReceivedQuery String Requête KQL qui retourne une ligne et indique l’heure de la dernière réception des données, ou aucune donnée en l’absence de résultats.

Exemple : {{graphQueriesTableName}}\n | summarize Time = max(TimeGenerated)\n | where isnotempty(Time)

graphQueries

Définit une requête qui présente l’ingestion des données au cours des deux dernières semaines.

Fournissez une requête pour tous les types de données du connecteur de données, ou une requête différente pour chaque type de données.

Valeur du tableau Type Description
metricName String Nom explicite pour votre graphe.

Exemple : Total data received
Légende String Chaîne qui apparaît dans la légende à droite du graphique, y compris une référence de variable.

Exemple : {{graphQueriesTableName}}
baseQuery String Requête qui filtre les événements pertinents, y compris une référence de variable.

Exemple : TableName_CL | where ProviderName == "myprovider" ou {{graphQueriesTableName}}

availability

Field Obligatoire Type Description
status Entier Status de disponibilité du connecteur.
Disponible = 1
Indicateur de fonctionnalité = 2
Bientôt disponible = 3
Interne = 4
isPreview Booléen Valeur booléenne indiquant si le connecteur est en mode aperçu.

autorisations

Valeur du tableau Type Description
Douanes String Décrit toutes les autorisations personnalisées requises pour votre connexion de données, dans la syntaxe suivante :
{
"name":chaîne,
"description":String
}

Exemple : la valeur en douane s’affiche dans Microsoft Sentinel section Conditions préalables avec une icône d’information bleue. Dans l’exemple GitHub, cette valeur est corrélée à la ligne Clé de jeton personnel de l’API GitHub : Vous devez accéder au jeton personnel GitHub...
Licences ENUM Définit les licences requises, comme l’une des valeurs suivantes : OfficeIRM,OfficeATP, Office365, AadP1P2, Mcas, Aatp, Mdatp, , , MtpIoT

Exemple : La valeur des licences s’affiche dans Microsoft Sentinel comme suit : Licence : obligatoire Azure AD Premium P2
resourceProvider resourceProvider Décrit les prérequis pour votre ressource Azure.

Exemple : La valeur resourceProvider s’affiche dans Microsoft Sentinel section Prérequis comme suit :
Espace de travail : l’autorisation de lecture et d’écriture est requise.
Clés : des autorisations de lecture sur les clés partagées pour l’espace de travail sont requises.
tenant tableau de valeurs ENUM
Exemple :

"tenant": [
"GlobalADmin",
"SecurityAdmin"
]
 Définit les autorisations requises, sous la forme d’une ou plusieurs des valeurs suivantes : "GlobalAdmin", "SecurityAdmin", , "SecurityReader""InformationProtection"

Exemple : affiche la valeur du locataire dans Microsoft Sentinel comme suit : Autorisations de locataire : Nécessite Global Administrator ou Security Administrator sur le locataire de l’espace de travail

Importante

Microsoft vous recommande d’utiliser des rôles disposant du moins d’autorisations. Cela contribue à renforcer la sécurité de votre organisation. Le rôle d’administrateur général dispose de privilèges élevés. Il doit être limité aux scénarios d’urgence lorsque vous ne pouvez pas utiliser un rôle existant.

resourceProvider

sous-valeur de tableau Type Description
Fournisseur ENUM Décrit le fournisseur de ressources, avec l’une des valeurs suivantes :
- Microsoft.OperationalInsights/workspaces
- Microsoft.OperationalInsights/solutions
- Microsoft.OperationalInsights/workspaces/datasources
- microsoft.aadiam/diagnosticSettings
- Microsoft.OperationalInsights/workspaces/sharedKeys
- Microsoft.Authorization/policyAssignments
providerDisplayName String Élément de liste sous Prérequis qui affiche une coche rouge « x » ou verte lorsque les autorisations requises sont validées dans la page du connecteur. Exemple "Workspace"
permissionsDisplayText String Afficher du texte pour les autorisations Lecture, Écriture ou Lecture et Écriture qui doivent correspondre aux valeurs configurées dans requiredPermissions
requiredPermissions {
"action":Booléen,
"delete":Booléen,
"read":Booléen,
"write":Booléen
}		 Décrit les autorisations minimales requises pour le connecteur.
étendue ENUM Décrit l’étendue du connecteur de données, comme l’une des valeurs suivantes : "Subscription", "ResourceGroup", "Workspace"

sampleQueries

valeur de tableau Type Description
description String Description explicite de l’exemple de requête.

Exemple : Top 10 vulnerabilities detected
Requête String Exemple de requête utilisé pour extraire les données du type de données.

Exemple : {{graphQueriesTableName}}\n | sort by TimeGenerated\n | take 10

Pour définir un lien inline à l’aide de Markdown, utilisez l’exemple suivant.

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

Pour définir un lien en tant que modèle ARM, utilisez l’exemple suivant comme guide :

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

Cette section fournit des paramètres qui définissent l’ensemble d’instructions qui s’affichent sur la page de votre connecteur de données dans Microsoft Sentinel et qui ont la structure suivante :

"instructionSteps": [
    {
        "title": "",
        "description": "",
        "instructions": [
        {
            "type": "",
            "parameters": {}
        }
        ],
        "innerSteps": {}
    }
]
Array, propriété Obligatoire Type Description
title String Définit un titre pour vos instructions.
description String Définit une description explicite pour vos instructions.
innerSteps Tableau Définit un tableau d’étapes d’instruction internes.
Instructions Vrai Tableau d’instructions Définit un tableau d’instructions d’un type de paramètre spécifique.

Instructions

Affiche un groupe d’instructions, avec différents paramètres et la possibilité d’imbriquer davantage d’instructionsSteps dans des groupes. Les paramètres définis ici correspondent

Type Array, propriété Description
OAuthForm OAuthForm Se connecter avec OAuth
Textbox Textbox Cette paire est associée à ConnectionToggleButton. Il existe 4 types disponibles :
  • password
  • text
  • number
  • email
    		•
    ConnectionToggleButton ConnectionToggleButton Déclenchez le déploiement de la DCR en fonction des informations de connexion fournies par le biais des paramètres d’espace réservé. Les paramètres suivants sont pris en charge :
  • name :Obligatoire
  • disabled
  • isPrimary
  • connectLabel
  • disconnectLabel
    		•
    CopyableLabel CopyableLabel Affiche un champ de texte avec un bouton Copier à la fin. Lorsque le bouton est sélectionné, la valeur du champ est copiée.
    Dropdown Dropdown Affiche une liste déroulante des options que l’utilisateur peut sélectionner.
    Markdown Markdown Affiche une section de texte mise en forme avec Markdown.
    DataConnectorsGrid DataConnectorsGrid Affiche une grille de connecteurs de données.
    ContextPane ContextPane Affiche un volet d’informations contextuelles.
    InfoMessage InfoMessage Définit un message d’informations inline.
    InstructionStepsGroup InstructionStepsGroup Affiche un groupe d’instructions, éventuellement développées ou réductibles, dans une section d’instructions distincte.
    InstallAgent InstallAgent Affiche un lien vers d’autres parties de Azure pour répondre à différentes exigences d’installation.
    OAuthForm

    Ce composant nécessite que le OAuth2 type soit présent dans la auth propriété du modèle de connecteur de données.

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

    Voici quelques exemples du Textbox type . Ces exemples correspondent aux paramètres utilisés dans la section exemple auth de référence des connecteurs de données pour l’infrastructure de connecteur sans code. Pour chacun des 4 types, chacun a label, placeholderet 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

    Exemple :

    Capture d’écran d’un bouton copier une valeur dans un champ.

    Exemple de code :

    {
    "parameters": {
        "fillWith": [
            "WorkspaceId",
            "PrimaryKey"
            ],
        "label": "Here are some values you'll need to proceed.",
        "value": "Workspace is {0} and PrimaryKey is {1}"
    },
    "type": "CopyableLabel"
}
    Valeur du tableau Obligatoire Type Description
    fillWith ENUM Tableau de variables d’environnement utilisées pour remplir un espace réservé. Séparez plusieurs espaces réservés par des virgules. Par exemple : {0},{1}

    Valeurs prises en charge : workspaceId, workspaceName, primaryKey, MicrosoftAwsAccount, subscriptionId
    Étiquette Vrai String Définit le texte de l’étiquette au-dessus d’une zone de texte.
    value Vrai String Définit la valeur à présenter dans la zone de texte, prend en charge les espaces réservés.
    rows Lignes Définit les lignes dans la zone d’interface utilisateur. Par défaut, définissez sur 1.
    wideLabel Booléen Détermine une étiquette large pour les chaînes longues. Par défaut, définissez sur false. 
    {
  "parameters": {
    "label": "Select an option",
    "name": "dropdown",
    "options": [
      {
        "key": "Option 1",
        "text": "option1"
      },
      {
        "key": "Option 2",
        "text": "option2"
      }
    ],
    "placeholder": "Select an option",
    "isMultiSelect": false,
    "required": true,
    "defaultAllSelected": false
  },
  "type": "Dropdown"
}
    Field Obligatoire Type Description
    Étiquette Vrai String Définit le texte de l’étiquette au-dessus de la liste déroulante.
    name Vrai String Définit le nom unique de la liste déroulante. Il est utilisé dans la configuration d’interrogation.
    options Vrai Tableau Définit la liste des options de la liste déroulante.
    Espace réservé String Définit le texte de l’espace réservé pour la liste déroulante.
    isMultiSelect Booléen Détermine si plusieurs options peuvent être sélectionnées. Par défaut, définissez sur false.
    required Booléen Si truela valeur est , la liste déroulante doit être remplie.
    defaultAllSelected Booléen Si la valeur est true, toutes les options sont sélectionnées par défaut.
    Markdown
    {
  "parameters": {
    "content": "## This is a Markdown section\n\nYou can use **bold** text, _italic_ text, and even [links](https://www.example.com)."
  },
  "type": "Markdown"
}
    DataConnectorsGrid
    {
  "type": "DataConnectorsGrid",
  "parameters": {
    "mapping": [
      {
        "columnName": "Column 1",
        "columnValue": "Value 1"
      },
      {
        "columnName": "Column 2",
        "columnValue": "Value 2"
      }
    ],
    "menuItems": [
      "MyConnector"
    ]
  }
}
    Field Obligatoire Type Description
    Cartographie Vrai Tableau Définit le mappage des colonnes dans la grille.
    menuItems Tableau Définit les éléments de menu de la grille.
    ContextPane
    {
  "type": "ContextPane",
  "parameters": {
    "isPrimary": true,
    "label": "Add Account",
    "title": "Add Account",
    "subtitle": "Add Account",
    "contextPaneType": "DataConnectorsContextPane",
    "instructionSteps": [
      {
        "instructions": [
          {
            "type": "Textbox",
            "parameters": {
              "label": "Snowflake Account Identifier",
              "placeholder": "Enter Snowflake Account Identifier",
              "type": "text",
              "name": "accountId",
              "validations": {
                "required": true
              }
            }
          },
          {
            "type": "Textbox",
            "parameters": {
              "label": "Snowflake PAT",
              "placeholder": "Enter Snowflake PAT",
              "type": "password",
              "name": "apikey",
              "validations": {
                "required": true
              }
            }
          }
        ]
      }
    ]
  }
}
    Field Obligatoire Type Description
    title Vrai String Titre du volet contextuel.
    sous-titre Vrai String Sous-titre du volet de contexte.
    contextPaneType Vrai String Type du volet de contexte.
    instructionSteps Vrai Tableau
    instructionSteps    		 Étapes d’instructions pour le volet contextuel.
    Étiquette String Étiquette du volet de contexte.
    isPrimary Booléen Indique s’il s’agit du volet de contexte principal.
    InfoMessage

    Voici un exemple de message d’informations inline :

    Capture d’écran d’un message d’informations inline.

    En revanche, l’image suivante montre un message d’information qui n’est pas inclus :

    Capture d’écran d’un message d’information qui n’est pas inclus.

    Valeur du tableau Type Description
    text String Définissez le texte à afficher dans le message.
    visible Booléen Détermine si le message est affiché.
    Inline Booléen Détermine la façon dont le message d’informations est affiché.

    - true: (Recommandé) Affiche le message d’informations incorporé dans les instructions.
    - false: ajoute un arrière-plan bleu.
    InstructionStepsGroup

    Voici un exemple de groupe d’instructions extensible :

    Capture d’écran d’un groupe d’instructions supplémentaire extensible.

    Valeur du tableau Obligatoire Type Description
    title Vrai String Définit le titre de l’étape d’instruction.
    description String Texte descriptif facultatif.
    canCollapseAllSections Booléen Détermine si la section est un accordéon réductible ou non.
    noFxPadding Booléen Si truela valeur est , réduit le remplissage en hauteur pour économiser de l’espace.
    Élargi Booléen Si true, s’affiche comme développé par défaut.

    Pour obtenir un exemple détaillé, consultez la configuration JSON pour le connecteur DNS Windows.

    InstallAgent

    Certains types InstallAgent apparaissent sous la forme d’un bouton, d’autres sous forme de lien. Voici des exemples des deux :

    Capture d’écran d’un lien ajouté en tant que bouton.

    Capture d’écran d’un lien ajouté en tant que texte inline.

    Valeurs de tableau Obligatoire Type Description
    linkType Vrai ENUM Détermine le type de lien, comme l’une des valeurs suivantes :

    InstallAgentOnWindowsVirtualMachine
    InstallAgentOnWindowsNonAzure
    InstallAgentOnLinuxVirtualMachine
    InstallAgentOnLinuxNonAzure
    OpenSyslogSettings
    OpenCustomLogsSettings
    OpenWaf
    OpenAzureFirewall OpenMicrosoftAzureMonitoring
    OpenFrontDoors
    OpenCdnProfile
    AutomaticDeploymentCEF
    OpenAzureInformationProtection
    OpenAzureActivityLog
    OpenIotPricingModel
    OpenPolicyAssignment
    OpenAllAssignmentsBlade
    OpenCreateDataCollectionRule
    policyDefinitionGuid True lors de l’utilisation de OpenPolicyAssignment linkType. String Pour les connecteurs basés sur des stratégies, définit le GUID de la définition de stratégie intégrée.
    assignMode ENUM Pour les connecteurs basés sur des stratégies, définit le mode d’attribution comme l’une des valeurs suivantes : Initiative, Policy
    dataCollectionRuleType ENUM Pour les connecteurs basés sur DCR, définit le type de règle de collecte de données comme SecurityEvent, ou ForwardEvent.

    Exemple de définition de connecteur de données

    L’exemple suivant rassemble certains des composants définis dans cet article en tant que format de corps JSON à utiliser avec l’API créer ou mettre à jour une définition de connecteur de données.

    Pour obtenir d’autres exemples de connecteurs connectorUiConfig de données CCF, consultez autres connecteurs de données CCF. Même les connecteurs utilisant le CCF hérité ont des exemples valides de création d’interface utilisateur.

    {
    "kind": "Customizable",
    "properties": {
        "connectorUiConfig": {
          "title": "Example CCF 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"
                  }
                }
              ]
            }
          ]
        }
    }
}
    • Last updated on