Referencia de definiciones del conector de datos para codeless Connector Platform

Artículo
07/03/2024

Para crear un conector de datos con codeless Connector Platform (CCP), 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 del identificador 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.

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	Nombre del área de trabajo, no el identificador. Patrón de expresión regular: `^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$`.
api-version	Versión de API que se usará para la operación.

Cuerpo de la solicitud

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

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

dataConnectorDefinition tiene las siguientes propiedades:

Nombre	Obligatorio	Type	Descripción
Variante	True	String	`Customizable` para el conector de datos de sondeo de API o `Static` en caso contrario
Propiedades.connectorUiConfig	True	JSON anidado connectorUiConfig	Las 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 importantes de la interfaz de usuario.

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

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.

Campo	Obligatorio	Type	Descripción	Captura de pantalla del área notable #
title	True	string	Título que se muestra en la página del conector de datos	1
id		string	Establece el identificador de conector personalizado para el uso interno.
logotipo		string	Ruta de acceso al archivo de imagen en formato SVG. Si no se configura ningún valor, se usa un logotipo predeterminado.	2
publisher	True	string	Proveedor del conector	3
descriptionMarkdown	True	string en Markdown	Descripción del conector con la capacidad de agregar lenguaje Markdown para mejorarlo.	4
sampleQueries	True	JSON anidado sampleQueries	Consulta al cliente para comprender cómo buscar los datos en el registro de eventos.
graphQueries	True	JSON anidado graphQueries	Consultas que presentan 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.	5
graphQueriesTableName		Establece el nombre de la tabla en la que el conector inserta datos. Este nombre se puede usar en otras consultas especificando `{{graphQueriesTableName}}` el marcador de posición en `graphQueries` los valores y `lastDataReceivedQuery` .
dataTypes	True	JSON anidado dataTypes	Una lista de todos los tipos de datos para el conector y una consulta para capturar la hora del último evento para cada tipo de datos.	6
connectivityCriteria	True	JSON anidado connectivityCriteria	Objeto que define cómo comprobar si el conector está conectado.	7
permissions	True	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	True	JSON anidado detalladas	Matriz de elementos de widget que explican cómo instalar el conector y controles accionables que se muestran en la pestaña Instrucciones .	9

connectivityCriteria

Campo	Obligatorio	Type	Descripción
Tipo	True	String	Una de las dos opciones siguientes: `HasDataConnectors` : este valor es mejor para los conectores de datos de sondeo de API, como la CCP. El conector se considera conectado con al menos una conexión activa. `isConnectedQuery` : este valor es el 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 dentro de 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 Array	Tipo	Descripción
name	Cadena	Descripción significativa de ,`lastDataReceivedQuery` incluida la 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 ningún resultado. 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 Array	Tipo	Descripción
metricName	String	Escriba un nombre significativo para el gráfico. Ejemplo: `Total data received`
legend	String	Cadena que aparece en la leyenda a la derecha del gráfico, incluida una referencia de variable. Ejemplo: `{{graphQueriesTableName}}`
baseQuery	String	Consulta que filtra los eventos relevantes, incluida una referencia de variable. Por ejemplo, `TableName_CL \| where ProviderName == "myprovider"` o `{{graphQueriesTableName}}`.

permisos

Valor Array	Tipo	Descripción
customs	String	Describe los permisos personalizados necesarios para la conexión de datos, en la sintaxis siguiente: `{` `"name":`string`,` `"description":`cadena `}` Ejemplo: el valor customs se muestra en la sección Requisitos previos de Microsoft Sentinel con un icono informativo azul. En el ejemplo de GitHub, este valor se correlaciona con la línea Clave de token personal de la API de GitHub: Necesita acceso al token personal de GitHub...
licencias	ENUM	Define las licencias necesarias, como uno de los valores siguientes: `OfficeIRM`,`OfficeATP`, `Office365`, `AadP1P2`, `Mcas`, `Aatp`, `Mdatp`, `Mtp`, `IoT` Ejemplo: el valor licenses (licencias) se muestra así en Microsoft Sentinel: Licencia: requiere Azure AD Premium P2
resourceProvider	resourceProvider	Describe los requisitos previos para el recurso de Azure. Ejemplo: el valor resourceProvider se muestra así en la sección Requisitos previos de Microsoft Sentinel: Área de trabajo: se requiere permiso de escritura y de escritura. Debe tener permisos de lectura para las claves compartidas del á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: el valor tenant se muestra así en Microsoft Sentinel: Permisos de inquilino: requiere `Global Administrator` o `Security Administrator` en el área de trabajo del inquilino.

Importante

Microsoft recomienda usar roles con el menor número de permisos. Esto ayuda a mejorar la seguridad de su organización. El administrador global es un rol con privilegios elevados que debe limitarse a escenarios de emergencia cuando no se puede usar un rol existente.

resourceProvider

valor de submatriz	Tipo	Descripción
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	Un elemento de lista en Requisitos previos que muestra una marca de verificación roja "x" o verde cuando los requiredPermissions se validan en la página del conector. Ejemplo, `"Workspace"`
permissionsDisplayText	String	Muestra texto para permisos de lectura, escritura o lectura y escritura que deben corresponder a los valores configurados en requiredPermissions.
requiredPermissions	`{` `"action":`Boolean`,` `"delete":`Boolean`,` `"read":`Boolean`,` `"write":`Boolean `}`	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 array	Tipo	Descripción
description	String	Descripción significativa de la consulta de ejemplo. Ejemplo: `Top 10 vulnerabilities detected`
consulta	String	Consulta de ejemplo usada para capturar los datos del tipo de datos. Ejemplo: `{{graphQueriesTableName}}\n \| sort by TimeGenerated\n \| take 10`

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

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

Propiedad Array	Obligatorio	Type	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 instrucciones internas.
detalladas	True	Matriz de instrucciones	Define una matriz de instrucciones de un tipo de parámetro específico.

detalladas

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	Propiedad Array	Descripción
OAuthForm	OAuthForm	Conectar con OAuth
Cuadro de texto	Cuadro de texto	Esto 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 siguientes parámetros: `name` :obligatorio `disabled` `isPrimary` `connectLabel` `disconnectLabel`
CopyableLabel	CopyableLabel	Muestra un campo de texto con el botón Copiar al final. Cuando se pulsa el botón, se copia el valor del campo.
InfoMessage	InfoMessage	Define un mensaje de información insertado.
InstructionStepsGroup	InstructionStepsGroup	Muestra un grupo de instrucciones, opcionalmente expandidas o contraídas, 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 corresponden a los parámetros que se usan en la sección de ejemplo auth de referencia de conectores de datos para codeless Connector Platform. 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"
  }          
}
]

CopyableLabel

Ejemplo:

Captura de pantalla de un botón de 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 Array	Obligatorio	Type	Descripción
fillWith		ENUM	Matriz de variables de entorno utilizadas para rellenar un marcador de posición. Separe varios marcadores de posición con comas. Por ejemplo: `{0},{1}` Valores admitidos: `workspaceId`, `workspaceName`, `primaryKey`, `MicrosoftAwsAccount`, `subscriptionId`
label	True	String	Define el texto de la etiqueta encima de un cuadro de texto.
value	True	String	Define el valor que se debe presentar en el cuadro de texto y admite marcadores de posición.
rows		Filas	Define las filas del área de interfaz de usuario. De manera predeterminada, se establece en 1.
wideLabel		Booleano	Determina una etiqueta ancha para cadenas largas. De manera predeterminada, se establece en `false`.

InfoMessage

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

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

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

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

Valor Array	Tipo	Descripción
text	String	Texto que se va a mostrar en el mensaje.
visible	Boolean	Determina si se muestra el mensaje.
inline	Boolean	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 expandible:

Captura de pantalla de un grupo de instrucción extra y expansible.

Valor Array	Obligatorio	Type	Descripción
title	True	String	Define el título del paso de instrucción.
descripción		Cadena	Texto descriptivo opcional.
canCollapseAllSections		Booleano	Determina si la sección es una instancia de Accordion contraíble o no contraíble.
noFxPadding		Booleano	Si se produce `true`, reduce el relleno de altura para ahorrar espacio.
expanded		Booleano	Si se produce `true`, se muestra como expandido de manera predeterminada.

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

InstallAgent

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

Captura de pantalla de un enlace agregado en forma de texto insertado.

Valores Array	Obligatorio	Type	Descripción
linkType	True	ENUM	Determina el tipo de vínculo, como uno de los valores siguientes: `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	Para 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	Para los conectores basados en DCR, define el tipo de regla de recopilación de datos como `SecurityEvent`, o `ForwardEvent`.

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 de CCP. Incluso los conectores que usan la CCP heredada tienen ejemplos válidos de la creación de la interfaz de usuario.

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

Compartir vía