Informations de référence sur les définitions de connecteur de données pour la plateforme de connecteurs sans code

Article
10/16/2024

Pour créer un connecteur de données avec la plateforme de connecteurs sans code (CCP), 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	Description
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 demande

Le corps de la requête pour la création d’une définition de connecteur de données CCP avec l’API a la structure suivante :

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

dataConnectorDefinition a les propriétés suivantes :

Nom	Requise	Type	Description
Genre	True	Chaîne	`Customizable` pour le connecteur de données d’interrogation d’API ou `Static` dans le cas contraire
Propriétés.connectorUiConfig	True	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, 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.

Champ	Requis	Type	Description	Capture d’écran de la zone notable #
title	True	string	Titre affiché dans la page connecteur de données	1
id		string	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
publisher	True	string	Fournisseur du connecteur	3
descriptionMarkdown	True	chaîne dans Markdown	Description du connecteur avec la possibilité d’ajouter le langage Markdown pour l’améliorer.	4
sampleQueries	True	JSON imbriqué sampleQueries	Interroge le client pour comprendre comment trouver les données dans le journal des événements.
graphQueries	True	JSON imbriqué graphQueries	Requêtes qui présentent l’ingestion des données au cours des deux dernières semaines. Fournissez soit une requête pour tous les types de données du connecteur de données, soit 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 `graphQueries` `lastDataReceivedQuery` les valeurs.
dataTypes	True	JSON imbriqué dataTypes	Liste de tous les types de données pour votre connecteur et requête pour récupérer l’heure du dernier événement pour chaque type de données.	6
connectivityCriteria	True	JSON imbriqué connectivityCriteria	Objet qui définit comment vérifier si le connecteur est connecté.	7
autorisations	True	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	True	JSON imbriqué détaillées	Tableau de composants de widget qui expliquent comment installer le connecteur et les contrôles actionnables affichés sous l’onglet Instructions .	9

connectivityCriteria

Champ	Requis	Type	Description
Type	True	Chaîne	L’une des deux options suivantes : `HasDataConnectors` cette valeur est optimale pour les connecteurs de données d’interrogation d’API tels que le CCP. 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)"`

dataTypes

Valeur de tableau	Type	Description
name	Chaîne	Description explicite de la`lastDataReceivedQuery` variable, y compris la prise en charge de la `graphQueriesTableName` variable. Exemple : `{{graphQueriesTableName}}`
lastDataReceivedQuery	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 soit une requête pour tous les types de données du connecteur de données, soit une requête différente pour chaque type de données.

Valeur de tableau	Type	Description
metricName	String	Nom explicite de votre graphique. Exemple : `Total data received`
legend	String	Chaîne qui apparaît dans la légende à droite du graphique, y compris une référence à une variable. Exemple : `{{graphQueriesTableName}}`
baseQuery	String	Requête qui filtre les événements pertinents, y compris une référence à une variable. Par exemple : `TableName_CL \| where ProviderName == "myprovider"` ou `{{graphQueriesTableName}}`

autorisations

Valeur de tableau	Type	Description
customs	String	Décrit toutes les autorisations personnalisées requises pour votre connexion de données, dans la syntaxe suivante : `{` `"name":`string`,` `"description":`chaîne `}` Exemple : La valeur de customs s’affiche dans la section Prérequis 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	ENUM	Définit les licences requises, avec l’une des valeurs suivantes : `OfficeIRM`, `OfficeATP`, `Office365`, `AadP1P2`, `Mcas`, `Aatp`, `Mdatp`, `Mtp`, `IoT` Exemple : La valeur de licenses s’affiche dans Microsoft Sentinel comme suit : Licence : Azure AD Premium P2 obligatoire.
resourceProvider	resourceProvider	Décrit les conditions préalables pour votre ressource Azure. Exemple : La valeur de resourceProvider s’affiche dans la section Prérequis de Microsoft Sentinel comme suit : Espace de travail : L’autorisation d’accès en lecture et écriture est nécessaire. Clés : Des autorisations d’accès en lecture sur les clés partagées pour l’espace de travail sont requises.
client	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 de tenant dans Microsoft Sentinel comme suit : Autorisations du 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. Administrateur général est un rôle hautement privilégié à ne limiter qu’aux scénarios d’urgence lorsque vous ne pouvez pas utiliser un rôle existant.

resourceProvider

valeur de sous-tableau	Type	Description
provider	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. Par exemple, `"Workspace"`
permissionsDisplayText	String	Affiche 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":`Boolean `}`	Décrit les autorisations minimales nécessaires pour le connecteur.
scope	ENUM	Décrit l’étendue du connecteur de données avec 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`

Configurer d’autres options de lien

Pour définir un lien inclus en utilisant Markdown, servez-vous de 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 comme 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	Requis	Type	Description
title		Chaîne	Définit un titre pour vos instructions.
description		Chaîne	Définit une description explicite de vos instructions.
innerSteps		Tableau	Définit un tableau d’étapes d’instructions internes.
détaillées	True	Tableau d’instructions	Définit un tableau d’instructions d’un type de paramètre spécifique.

détaillées

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	Propriété de tableau	Description
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 copier à l’extrémité. Lorsque le bouton est sélectionné, la valeur du champ est copiée.
InfoMessage	InfoMessage	Définit un message d’information inlined.
InstructionStepsGroup	InstructionStepsGroup	Affiche un groupe d’instructions, éventuellement développé ou réductible, 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 la plateforme de connecteurs 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 de copie de 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	Requis	Type	Description
fillWith		ENUM	Tableau de variables d’environnement utilisé 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`
label	True	Chaîne	Définit le texte de l’étiquette au-dessus d’une zone de texte.
valeur	True	Chaîne	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 de l’interface utilisateur. Par défaut, définissez sur 1.
wideLabel		Boolean	Détermine une étiquette large pour les chaînes longues. Par défaut, définissez sur `false`.

InfoMessage

Voici un exemple de message d’information inclus :

Capture d’un message d’information inlined.

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	Type	Description
text	String	Définit le texte à afficher dans le message.
visible	Boolean	Détermine si le message s’affiche.
inline	Boolean	Détermine le mode d’affichage du message d’information. - `true` : (Recommandé) Affiche le message d’information incorporé dans les instructions. - `false` : Ajoute un arrière-plan bleu.

InstructionStepsGroup

Voici un exemple de groupe d’instructions pouvant être développé :

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

Valeur de tableau	Requis	Type	Description
title	True	Chaîne	Définit le titre de l’étape d’instruction.
description		Chaîne	Texte descriptif facultatif.
canCollapseAllSections		Boolean	Détermine si la section est un accordéon réductible ou non.
noFxPadding		Boolean	Si `true`, réduit le remplissage en hauteur pour gagner de l’espace.
expanded		Boolean	Si `true`, développé par défaut.

Pour obtenir un exemple détaillé, consultez le JSON de configuration du 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é comme texte inlined

Valeurs de tableau	Requis	Type	Description
linkType	True	ENUM	Détermine le type de lien avec 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		ENUM	Pour les connecteurs basés sur des stratégies, définit le mode d’attribution avec 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 é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 obtenir d’autres exemples de révision d’autres connecteurs de connectorUiConfig données CCP. Même les connecteurs utilisant le CCP hérité ont des exemples valides de la création de l’interface utilisateur.

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

Partager via