Compartir a través de

Referencia de definiciones del conector de datos para codeless Conectar or Platform

  • Artículo

Para crear un conector de datos con codeless Conectar or Platform (CCP), use este documento como complemento de la API REST de Microsoft Sentinel para los documentos de referencia de definiciones de Conectar or 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 Conectar or de datos: creación o actualización de parámetros de URI.

Nombre Descripción
data Conectar orDefinitionName 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": {}
    }
}

data Conectar orDefinition 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.

Screenshot of a sample data connector page with sections labeled 1 through 9.

Cada uno de los siguientes elementos de la connectorUiConfig sección necesarios para configurar la interfaz de usuario corresponde a la parte Personalizable Conectar orUiConfig 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.
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
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.
Value 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...
licenses 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.

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

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
    		•
    Conectar ionToggleButton Conectar ionToggleButton 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 usados en la sección de ejemplo auth de referencia de conectores de datos para codeless Conectar or 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"
  }
}
]

    Conectar ionToggleButton

    "instructions": [
{
  "type": "ConnectionToggleButton",
  "parameters": {
    "connectLabel": "toggle",
    "name": "toggle"
  }          
}
]

    CopyableLabel

    Ejemplo:

    Screenshot of a copy value button in a field.

    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:

    Screenshot of an inline information message.

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

    Screenshot of an information message that's not inline.

    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:

    Screenshot of an expandable, extra instruction group.

    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:

    Screenshot of a link added as a button.

    Screenshot of a link added as inline text.

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