Referencia de definiciones del conector de datos para Codeless Connector Framework

Para crear un conector de datos con Codeless Connector Framework (CCF), use este documento como complemento a los documentos de referencia de la API REST de Microsoft Sentinel para definiciones de conectores de datos. En concreto, este documento de referencia se expande en la sección siguiente:

• connectorUiConfig : define los elementos visuales y el texto que se muestran en la página del conector de datos de Microsoft Sentinel.

Para más información, consulte Creación de un conector sin código.

Definiciones del conector de datos: creación o actualización

Consulte la operación Crear o actualizar en los documentos de la API REST para encontrar la versión más reciente de la API estable o preliminar. Solo la update operación requiere el etag valor .

Método PUT

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

Parámetros de URI

Para obtener más información sobre la versión más reciente de la API, consulte Definiciones de conectores de datos: creación o actualización de parámetros de URI.

Cuerpo de la solicitud

El cuerpo de la solicitud para crear una definición de conector de datos CCF con la API tiene la siguiente estructura:

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

dataConnectorDefinition tiene las siguientes propiedades:

Configuración de la interfaz de usuario del conector

En esta sección se describen las opciones de configuración disponibles para personalizar la interfaz de usuario de la página del conector de datos.

En la captura de pantalla siguiente se muestra una página de conector de datos de ejemplo, resaltada con números que corresponden a áreas importantes de la interfaz de usuario.

Cada uno de los siguientes elementos de la connectorUiConfig sección necesarios para configurar la interfaz de usuario corresponde a la parte PersonalizableConnectorUiConfig de la API.

connectivityCriteria

tipos de datos

graphConsultas

Define una consulta que presenta la ingesta de datos en las últimas dos semanas.

Proporcione una consulta para todos los tipos de datos del conector de datos o una consulta diferente para cada tipo de datos.

availability

permisos

proveedor de recursos

sampleQueries

Configuración de otras opciones de vínculo

Para definir un vínculo insertado mediante Markdown, use el ejemplo siguiente.

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

Para definir un vínculo como plantilla de ARM, use el ejemplo siguiente como guía:

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

En esta sección se proporcionan parámetros que definen el conjunto de instrucciones que aparecen en la página del conector de datos de Microsoft Sentinel y que tiene la estructura siguiente:

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

instrucciones

Muestra un grupo de instrucciones, con varios parámetros y la capacidad de anidar más instruccionesPasos en grupos. Los parámetros definidos aquí corresponden

OAuthForm

Este componente requiere que el OAuth2 tipo esté presente en la auth propiedad de la plantilla del conector de datos.

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

Cuadro de texto

Estos son algunos ejemplos del Textbox tipo . Estos ejemplos corresponden a los parámetros usados en la sección de ejemplo auth de referencia de conectores de datos para Codeless Connector Framework. Para cada uno de los 4 tipos, cada uno tiene label, placeholdery 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"
  }          
}
]

EtiquetaCopiable

Ejemplo:

Código de ejemplo:

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

Desplegable

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

Este es un ejemplo de un mensaje de información insertado:

En cambio, en la imagen siguiente se muestra un mensaje de información que no está insertado:

InstructionStepsGroup

Este es un ejemplo de un grupo de instrucciones expandible:

Para obtener un ejemplo detallado, consulte el código JSON de configuración para el conector dns de Windows.

Agente de Instalación

Algunos tipos InstallAgent aparecen como un botón; otros aparecen como un vínculo. Estos son ejemplos de ambos:

Definición del conector de datos de ejemplo

En el ejemplo siguiente se reúnen algunos de los componentes definidos en este artículo como formato de cuerpo JSON para usarlos con la API de definición de conector de datos Create Or Update.

Para obtener más ejemplos de la connectorUiConfig revisión de otros conectores de datos CCF. Incluso los conectores que usan el CCF heredado tienen ejemplos válidos de la creación de la interfaz de usuario.

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