Referencia de definiciones de 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 Microsoft Sentinel API REST para definiciones de conector de datos. En concreto, este documento de referencia se expande en la sección siguiente:

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

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

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

Haga referencia a 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 en versión 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 del conector de datos: creación o actualización de parámetros de URI.

Nombre Descripción
dataConnectorDefinitionName La definición del conector de datos debe ser un nombre único y es el mismo que el name parámetro en el cuerpo de la solicitud.
resourceGroupName Nombre del grupo de recursos, no distingue mayúsculas de minúsculas.
subscriptionId Identificador de la suscripción de destino.
workspaceName El nombre del área de trabajo, no el identificador.
Patrón Regex: ^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$
api-version Versión de API que se va a usar para esta operación.

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:

Nombre Obligatorio Tipo Description
Kind Verdadero Cadena Customizable para el conector de datos de sondeo de API o Static de otro modo
propiedades. connectorUiConfig Verdadero JSON anidado
connectorUiConfig		 Propiedades de configuración de la interfaz de usuario del conector de datos

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 notables de la interfaz de usuario.

Captura de pantalla de una página de conector de datos de ejemplo con secciones etiquetadas del 1 al 9.

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

Campo Obligatorio Tipo Description Captura de pantalla del área notable #
title True string Título mostrado en la página del conector de datos 1
id string Establece el identificador de conector personalizado para el uso interno
logo string Ruta de acceso al archivo de imagen en formato SVG. Si no se configura ningún valor, se usa un logotipo predeterminado. 2
publicador True string Proveedor del conector 3
descriptionMarkdown Verdadero cadena en Markdown Descripción del conector con la capacidad de agregar el lenguaje Markdown para mejorarlo. 4
sampleQueries Verdadero JSON anidado
sampleQueries		 Consultas para que el cliente comprenda cómo buscar los datos en el registro de eventos.
graphQueries Verdadero JSON anidado
graphQueries		 Consultas que presentan 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.		 5
graphQueriesTableName Establece el nombre de la tabla en la que el conector inserta datos. Este nombre se puede usar en otras consultas especificando el marcador de {{graphQueriesTableName}} posición en graphQueries y lastDataReceivedQuery los valores.
dataTypes Verdadero JSON anidado
dataTypes		 Una lista de todos los tipos de datos del conector y una consulta para capturar la hora del último evento para cada tipo de datos. 6
connectivityCriteria Verdadero JSON anidado
connectivityCriteria		 Objeto que define cómo comprobar si el conector está conectado. 7
disponibilidad JSON anidado
disponibilidad		 Objeto que define el estado de disponibilidad del conector.
permissions Verdadero JSON anidado
permissions		 La información que se muestra en la sección Requisitos previos de la interfaz de usuario, que enumera los permisos necesarios para habilitar o deshabilitar el conector. 8
instructionSteps Verdadero JSON anidado
instrucciones		 Matriz de elementos de widget que explican cómo instalar el conector y controles accionables que se muestran en la pestaña Instrucciones . 9
isConnectivityCriteriasMatchSome Booleano Boolean que indica si se va a usar 'OR' (SOME) o 'AND' entre elementos ConnectivityCriteria.

connectivityCriteria

Campo Obligatorio Tipo Descripción
Tipo Verdadero Cadena Una de las dos opciones siguientes: HasDataConnectors este valor es mejor para los conectores de datos de sondeo de API, como el CCF. El conector se considera conectado con al menos una conexión activa.

isConnectedQuery : este valor es mejor para otros tipos de conectores de datos. El conector se considera conectado cuando la consulta proporcionada devuelve datos.
Valor True cuando el tipo es isConnectedQuery Cadena Consulta para determinar si los datos se reciben en un período de tiempo determinado. Por ejemplo: CommonSecurityLog | where DeviceVendor == \"Vectra Networks\"\n| where DeviceProduct == \"X Series\"\n | summarize LastLogReceived = max(TimeGenerated)\n | project IsConnected = LastLogReceived > ago(7d)"

dataTypes

Valor de matriz Tipo Descripción
name Cadena Una descripción significativa de , incluida lalastDataReceivedQuery compatibilidad con la graphQueriesTableName variable .

Ejemplo: {{graphQueriesTableName}}
lastDataReceivedQuery Cadena Una consulta KQL que devuelve una fila e indica la última vez que se recibieron datos o ningún dato si no hay resultados.

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

graphQueries

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.

Valor de matriz Tipo Description
metricName Cadena Un nombre significativo para el gráfico.

Ejemplo: Total data received
leyenda Cadena Cadena que aparece en la leyenda a la derecha del gráfico, incluida una referencia de variable.

Ejemplo: {{graphQueriesTableName}}
baseQuery Cadena Consulta que filtra los eventos pertinentes, incluida una referencia de variable.

Por ejemplo, TableName_CL | where ProviderName == "myprovider" o {{graphQueriesTableName}}

disponibilidad

Campo Obligatorio Tipo Description
status Entero Estado de disponibilidad del conector.
Disponible = 1
Marca de característica = 2
Próximamente = 3
Interno = 4
isPreview Booleano Un valor booleano que indica si el conector está en modo de vista previa.

permissions

Valor de matriz Tipo Description
aduana Cadena Describe los permisos personalizados necesarios para la conexión de datos, en la sintaxis siguiente:
{
"name":cadena,
"description":cadena
}

Ejemplo: el valor de aduana se muestra en Microsoft Sentinel sección Requisitos previos con un icono informativo azul. En el ejemplo de GitHub, este valor se correlaciona con la clave de token personal de la API de GitHub de línea: Necesita acceso al token personal de GitHub...
licencias ENUM Define las licencias necesarias, como uno de los valores siguientes: OfficeIRM,OfficeATP , , AadP1P2Office365, McasAatp, , Mdatp, , MtpIoT

Ejemplo: El valor de licencias se muestra en Microsoft Sentinel como: Licencia: Azure AD Premium P2 necesaria
resourceProvider resourceProvider Describe los requisitos previos del recurso de Azure.

Ejemplo: El valor resourceProvider se muestra en Microsoft Sentinel sección Requisitos previos como:
Área de trabajo: se requiere el permiso de lectura y escritura.
Claves: se requieren permisos de lectura para las claves compartidas para el área de trabajo.
tenant matriz de valores ENUM
Ejemplo:

"tenant": [
"GlobalADmin",
"SecurityAdmin"
]
 Define los permisos necesarios, como uno o varios de los valores siguientes: "GlobalAdmin", "SecurityAdmin", "SecurityReader", . "InformationProtection"

Ejemplo: muestra el valor del inquilino en Microsoft Sentinel como: Permisos de inquilino: Requiere Global Administrator o Security Administrator en el inquilino del área de trabajo.

Importante

Microsoft recomienda utilizar roles con la menor cantidad de permisos. Esto ayuda a mejorar la seguridad de la organización. Administrador global es un rol con muchos privilegios que debe limitarse a escenarios de emergencia cuando no se puede usar un rol existente.

resourceProvider

valor de sub matriz Tipo Description
proveedor ENUM Describe el proveedor de recursos, con uno de los valores siguientes:
- Microsoft.OperationalInsights/workspaces
- Microsoft.OperationalInsights/solutions
- Microsoft.OperationalInsights/workspaces/datasources
- microsoft.aadiam/diagnosticSettings
- Microsoft.OperationalInsights/workspaces/sharedKeys
- Microsoft.Authorization/policyAssignments
providerDisplayName Cadena Elemento de lista en Requisitos previos que muestra una marca de verificación roja "x" o verde cuando se validan los requiredPermissions en la página del conector. Por ejemplo, "Workspace"
permissionsDisplayText Cadena Mostrar texto para permisos de lectura, escritura o lectura y escritura que deben corresponder a los valores configurados en requiredPermissions
requiredPermissions {
"action":Booleano,
"delete":Booleano,
"read":Booleano,
"write":Booleano
}		 Describe los permisos mínimos necesarios para el conector.
scope ENUM Describe el ámbito del conector de datos, como uno de los valores siguientes: "Subscription", , "ResourceGroup""Workspace"

sampleQueries

valor de matriz Tipo Descripción
description Cadena Descripción significativa de la consulta de ejemplo.

Ejemplo: Top 10 vulnerabilities detected
query Cadena Consulta de ejemplo usada para capturar los datos del tipo de datos.

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

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 una 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 tienen la siguiente estructura:

"instructionSteps": [
    {
        "title": "",
        "description": "",
        "instructions": [
        {
            "type": "",
            "parameters": {}
        }
        ],
        "innerSteps": {}
    }
]
Array (propiedad) Obligatorio Tipo Descripción
title Cadena Define un título para las instrucciones.
description Cadena Define una descripción significativa para las instrucciones.
innerSteps Matriz Define una matriz de pasos de instrucción internos.
instrucciones Verdadero Matriz de instrucciones Define una matriz de instrucciones de un tipo de parámetro específico.

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

Tipo Array (propiedad) Description
OAuthForm OAuthForm Conexión con OAuth
Cuadro de texto Cuadro de texto Esto se empareja con ConnectionToggleButton. Hay 4 tipos disponibles:
  • password
  • text
  • number
  • email
    		•
    ConnectionToggleButton ConnectionToggleButton Desencadene la implementación de DCR en función de la información de conexión proporcionada a través de parámetros de marcador de posición. Se admiten los parámetros siguientes:
  • name : obligatorio
  • disabled
  • isPrimary
  • connectLabel
  • disconnectLabel
    		•
    CopyableLabel CopyableLabel Muestra un campo de texto con un botón de copia al final. Cuando se selecciona el botón, se copia el valor del campo.
    Dropdown Dropdown Muestra una lista desplegable de opciones entre las que el usuario puede seleccionar.
    Markdown Markdown Muestra una sección de texto con formato Markdown.
    DataConnectorsGrid DataConnectorsGrid Muestra una cuadrícula de conectores de datos.
    ContextPane ContextPane Muestra un panel de información contextual.
    InfoMessage InfoMessage Define un mensaje de información insertada.
    InstructionStepsGroup InstructionStepsGroup Muestra un grupo de instrucciones, opcionalmente expandidas o contraíbles, en una sección de instrucciones independiente.
    InstallAgent InstallAgent Muestra un vínculo a otras partes de Azure para cumplir varios requisitos de instalación.
    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 se corresponden con 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 cuatro 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"
  }          
}
]
    CopyableLabel

    Ejemplo:

    Captura de pantalla de un botón copiar valor en un campo.

    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"
}
    Valor de matriz Obligatorio Tipo Description
    fillWith ENUM Matriz de variables de entorno usadas para rellenar un marcador de posición. Separe varios marcadores de posición con comas. Por ejemplo: {0},{1}

    Valores admitidos: workspaceId, workspaceName, primaryKey, , MicrosoftAwsAccountsubscriptionId
    etiqueta Verdadero Cadena Define el texto de la etiqueta encima de un cuadro de texto.
    value Verdadero Cadena Define el valor que se va a presentar en el cuadro de texto, admite marcadores de posición.
    rows Rows Define las filas del área de la interfaz de usuario. De forma predeterminada, establezca en 1.
    wideLabel Booleano Determina una etiqueta ancha para cadenas largas. De forma predeterminada, establezca en 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"
}
    Campo Obligatorio Tipo Description
    etiqueta Verdadero Cadena Define el texto de la etiqueta situada encima de la lista desplegable.
    name Verdadero Cadena Define el nombre único de la lista desplegable. Esto se usa en la configuración de sondeo.
    options Verdadero Matriz Define la lista de opciones de la lista desplegable.
    marcador de posición Cadena Define el texto del marcador de posición de la lista desplegable.
    isMultiSelect Booleano Determina si se pueden seleccionar varias opciones. De forma predeterminada, establezca en false.
    required Booleano Si truees , es necesario rellenar la lista desplegable.
    defaultAllSelected Booleano Si truees , todas las opciones están seleccionadas de forma predeterminada.
    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"
    ]
  }
}
    Campo Obligatorio Tipo Description
    asignación Verdadero Matriz Define la asignación de columnas en la cuadrícula.
    menuItems Matriz Define los elementos de menú de la cuadrícula.
    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
              }
            }
          }
        ]
      }
    ]
  }
}
    Campo Obligatorio Tipo Descripción
    title Verdadero Cadena Título del panel de contexto.
    subtítulo Verdadero Cadena Subtítulo del panel contextual.
    contextPaneType Verdadero Cadena Tipo del panel de contexto.
    instructionSteps Verdadero Matriz
    instructionSteps    		 Pasos de instrucciones para el panel de contexto.
    etiqueta Cadena Etiqueta del panel de contexto.
    isPrimary Booleano Indica si este es el panel de contexto principal.
    InfoMessage

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

    Captura de pantalla de un mensaje de información insertada.

    Por el contrario, la siguiente imagen muestra un mensaje de información que no está alineado:

    Captura de pantalla de un mensaje de información que no está alineado.

    Valor de matriz Tipo Description
    text Cadena Defina el texto que se va a mostrar en el mensaje.
    visible Booleano Determina si se muestra el mensaje.
    insertada Booleano Determina cómo se muestra el mensaje de información.

    - true: (Recomendado) Muestra el mensaje de información insertado en las instrucciones.
    - false: agrega un fondo azul.
    InstructionStepsGroup

    Este es un ejemplo de un grupo de instrucciones ampliable:

    Captura de pantalla de un grupo de instrucciones adicional que se puede expandir.

    Valor de matriz Obligatorio Tipo Descripción
    title Verdadero Cadena Define el título del paso de instrucción.
    description Cadena Texto descriptivo opcional.
    canCollapseAllSections Booleano Determina si la sección es un acordeón contraíble o no.
    noFxPadding Booleano Si truees , reduce el relleno de altura para ahorrar espacio.
    expandido Booleano Si truees , se muestra como expandido de forma predeterminada.

    Para obtener un ejemplo detallado, consulte el json de configuración para el conector DNS de Windows.

    InstallAgent

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

    Captura de pantalla de un vínculo agregado como botón.

    Captura de pantalla de un vínculo agregado como texto insertado.

    Valores de matriz Obligatorio Tipo Descripción
    linkType Verdadero ENUM Determina el tipo de vínculo, como uno de los siguientes valores:

    InstallAgentOnWindowsVirtualMachine
    InstallAgentOnWindowsNonAzure
    InstallAgentOnLinuxVirtualMachine
    InstallAgentOnLinuxNonAzure
    OpenSyslogSettings
    OpenCustomLogsSettings
    OpenWaf
    OpenAzureFirewall OpenMicrosoftAzureMonitoring
    OpenFrontDoors
    OpenCdnProfile
    AutomaticDeploymentCEF
    OpenAzureInformationProtection
    OpenAzureActivityLog
    OpenIotPricingModel
    OpenPolicyAssignment
    OpenAllAssignmentsBlade
    OpenCreateDataCollectionRule
    policyDefinitionGuid True cuando se usa OpenPolicyAssignment linkType. Cadena En el caso de los conectores basados en directivas, define el GUID de la definición de directiva integrada.
    assignMode ENUM En el caso de los conectores basados en directivas, define el modo de asignación, como uno de los siguientes valores: Initiative, Policy
    dataCollectionRuleType ENUM En el caso de los conectores basados en DCR, define el tipo de regla de recopilación de datos como SecurityEvent, o ForwardEvent.

    Definición de 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 del 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 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"
                  }
                }
              ]
            }
          ]
        }
    }
}
    • Last updated on