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

2025-06-01

Pour créer un connecteur de données avec codeless Connector Framework (CCF), utilisez ce document comme supplément à l’API REST Microsoft Sentinel pour les définitions de connecteur de données . Plus précisément, ce document de référence se développe dans 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 du connecteur de données - Créer ou mettre à jour

Référencez 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 du connecteur de données - Créer ou mettre à jour des paramètres d’URI

Nom	Descriptif
dataConnectorDefinitionName	La définition du connecteur de données doit être un nom unique et est identique au paramètre dans le `name` corps de la requête.
resourceGroupName	Nom du groupe de ressources, pas sensible à la casse.
subscriptionId	ID de l’abonnement cible.
workspaceName	Nom de l’espace de travail, et non de 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 requête

Le corps de la requête 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	Catégorie	Descriptif
Type	Vrai	Chaîne	`Customizable` pour le connecteur de données d’interrogation d’API ou `Static` dans le cas contraire
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 connecteur de données.

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

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

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

Terrain	Obligatoire	Catégorie	Descriptif	Capture d’écran de la zone notable #
titre	Vrai	ficelle	Titre affiché dans la page connecteur de données	1
id		ficelle	Définit l’ID de connecteur personnalisé pour l’utilisation interne
logo		ficelle	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	Vrai	ficelle	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 des données. Ce nom peut être utilisé dans d’autres requêtes en spécifiant l’espace `{{graphQueriesTableName}}` réservé et `graphQuerieslastDataReceivedQuery` les valeurs.
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
CritèresDeConnectivité	Vrai	JSON imbriqué CritèresDeConnectivité	Objet qui définit comment vérifier si le connecteur est connecté.	7
autorisations	Vrai	JSON imbriqué autorisations	Les informations affichées dans la section Conditions préalables de l’interface utilisateur, qui répertorient 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

connectivitéCritères

Terrain	Obligatoire	Catégorie	Descriptif
Catégorie	Vrai	Chaîne	L’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 optimale 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`	Chaîne	Requête permettant de déterminer si les données sont reçues dans un certain délai. Par exemple : `CommonSecurityLog \| where DeviceVendor == \"Vectra Networks\"\n\| where DeviceProduct == \"X Series\"\n \| summarize LastLogReceived = max(TimeGenerated)\n \| project IsConnected = LastLogReceived > ago(7d)"`

types de données

Valeur de tableau	Catégorie	Descriptif
nom	Chaîne	Description explicite de la`lastDataReceivedQuery` variable, y compris la prise en charge de la `graphQueriesTableName` variable. Exemple : `{{graphQueriesTableName}}`
requêteDernièresDonnéesReçues	Chaîne	Requête KQL qui retourne une ligne et indique la dernière fois que les données ont été reçues ou aucune donnée s’il n’y a pas 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 de tableau	Catégorie	Descriptif
metricName	Chaîne	Nom significatif pour votre graphe. Exemple : `Total data received`
légende	Chaîne	Chaîne qui apparaît dans la légende à droite du graphique, y compris une référence de variable. Exemple : `{{graphQueriesTableName}}`
baseQuery	Chaîne	Requête qui filtre les événements pertinents, y compris une référence de variable. Par exemple : `TableName_CL \| where ProviderName == "myprovider"` ou `{{graphQueriesTableName}}`

autorisations

Valeur de tableau	Catégorie	Descriptif
douane	Chaîne	Décrit les autorisations personnalisées requises pour votre connexion de données, dans la syntaxe suivante : `{` `"name":`chaîne`,` `"description":`chaîne `}` Exemple : La valeur douanière s’affiche dans la section Conditions préalables de Microsoft Sentinel avec une icône d’information bleue. Dans l’exemple GitHub, cette valeur est corrélée à la clé de jeton personnel de l’API GitHub de ligne : vous devez accéder au jeton personnel GitHub...
Licences	ÉNUMÉRATION 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 : Azure AD Premium P2 requis
resourceProvider	resourceProvider	Décrit les conditions préalables pour votre ressource Azure. Exemple : La valeur resourceProvider s’affiche dans la section Conditions préalables de Microsoft Sentinel comme suit : Espace de travail : l’autorisation de lecture et d’écriture est requise. Clés : les autorisations de lecture pour les clés partagées pour l’espace de travail sont requises.
locataire	tableau de valeurs ENUM Exemple: `"tenant": [` `"GlobalADmin",` `"SecurityAdmin"` `]`	Définit les autorisations requises, comme une ou plusieurs des valeurs suivantes : `"GlobalAdmin"`, `"SecurityAdmin"`, `"SecurityReader"`, `"InformationProtection"` Exemple : affiche la valeur du locataire dans Microsoft Sentinel en tant que : Autorisations de locataire : Nécessite `Global Administrator` ou `Security Administrator` sur le locataire de l’espace de travail

Important

Microsoft vous recommande d’utiliser des rôles avec le moins d’autorisations. Cela permet d’améliorer 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.

fournisseur de ressources

valeur de sous-tableau	Catégorie	Descriptif
fournisseur	ÉNUMÉRATION 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	Chaîne	Élément de liste sous Conditions préalables qui affiche une coche rouge « x » ou verte lorsque les éléments requisPermissions sont validés dans la page du connecteur. Exemple `"Workspace"`
Texte d'affichage des autorisations	Chaîne	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	ÉNUMÉRATION ENUM	Décrit l’étendue du connecteur de données, comme l’une des valeurs suivantes : `"Subscription"`, `"ResourceGroup"`, `"Workspace"`

exemplesDeRequêtes

valeur du tableau	Catégorie	Descriptif
description	Chaîne	Description explicite de l’exemple de requête. Exemple : `Top 10 vulnerabilities detected`
requête	Chaîne	Exemple de requête utilisé pour extraire les données du type de données. Exemple : `{{graphQueriesTableName}}\n \| sort by TimeGenerated\n \| take 10`

Configurer d’autres options de lien

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 votre page de connecteur de données dans Microsoft Sentinel et qui ont la structure suivante :

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

Propriété de tableau	Obligatoire	Catégorie	Descriptif
titre		Chaîne	Définit un titre pour vos instructions.
description		Chaîne	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

Catégorie	Array, propriété	Descriptif
OAuthForm	OAuthForm	Se connecter avec OAuth
Zone de texte	Zone de texte	Cette paire avec `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 de 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 de copie à la fin. Lorsque le bouton est sélectionné, la valeur du champ est copiée.
Message d'information	Message d'information	Définit un message d’informations inline.
InstructionStepsGroup	InstructionStepsGroup	Affiche un groupe d’instructions, pouvant être développé ou rétractable, dans une section d’instructions distincte.
InstallAgent	InstallAgent	Affiche un lien vers d’autres parties d’Azure pour répondre à diverses 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 l’exemple auth de section dans la référence des connecteurs de données pour l’infrastructure du 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"
  }          
}
]

Étiquette Copiable

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 de tableau	Obligatoire	Catégorie	Descriptif
fillWith		ÉNUMÉRATION 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`, , `workspaceNameprimaryKey`, `MicrosoftAwsAccountsubscriptionId`
étiquette	Vrai	Chaîne	Définit le texte de l’étiquette au-dessus d’une zone de texte.
valeur	Vrai	Chaîne	Définit la valeur à présenter dans la zone de texte, prend en charge les espaces réservés.
Lignes		Lignes	Définit les lignes de 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 la `false`valeur .

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 de tableau	Catégorie	Descriptif
texte	Chaîne	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 de tableau	Obligatoire	Catégorie	Descriptif
titre	Vrai	Chaîne	Définit le titre de l’étape d’instruction.
description		Chaîne	Texte descriptif facultatif.
canCollapseAllSections		Booléen	Détermine si la section est un accordéon pliable ou non.
noFxPadding		Booléen	Si `true`, réduit le remplissage de hauteur pour économiser de l’espace.
expansé		Booléen	Si `true`, s’affiche comme développé par défaut.

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

InstallAgent

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

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

Valeurs de tableau	Obligatoire	Catégorie	Descriptif
linkType	Vrai	ÉNUMÉRATION 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.	Chaîne	Pour les connecteurs basés sur des stratégies, définit le GUID de la définition de stratégie intégrée.
assignMode		ÉNUMÉRATION ENUM	Pour les connecteurs basés sur des stratégies, définit le mode d’affectation, comme l’une des valeurs suivantes : `Initiative`, `Policy`
dataCollectionRuleType		ÉNUMÉRATION ENUM	Pour les connecteurs basés sur DCR, définit le type de règle de collecte de données comme étant `SecurityEvent`, ou `ForwardEvent`.

Exemple de définition du connecteur de données

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

Pour plus d’exemples de révision connectorUiConfigd’autres connecteurs de données CCF. Même les connecteurs utilisant le CCF hérité ont des exemples valides de la création de l’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"
                  }
                }
              ]
            }
          ]
        }
    }
}