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

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 :

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.

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

connectivityCriteria

dataTypes

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.

availability

autorisations

resourceProvider

sampleQueries

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

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

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

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 :

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

Liste déroulante

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

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

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

InfoMessage

Voici un exemple de message d’informations inline :

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

InstructionStepsGroup

Voici un exemple de groupe d’instructions extensible :

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 :

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