Referência de definições de conector de dados para o Codeless Connector Framework

Para criar um conector de dados com o Codeless Connector Framework (CCF), use este documento como um suplemento para os documentos de referência Microsoft Sentinel REST API for Data Connector Definitions . Especificamente, este documento de referência desenvolve a seguinte secção:

• connectorUiConfig - define os elementos visuais e o texto exibido na página do conector de dados no Microsoft Sentinel.

Para obter mais informações, consulte Criar um conector sem código.

Definições de conector de dados - Criar ou atualizar

Consulte a operação Criar ou atualizar nos documentos da API REST para encontrar a versão estável ou de visualização mais recente da API. Apenas a update operação requer o 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 obter mais informações sobre a versão mais recente da API, consulte Definições do conector de dados - Criar ou atualizar parâmetros de URI

Corpo de solicitação

O corpo da solicitação para criar uma definição de conector de dados CCF com a API tem a seguinte estrutura:

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

dataConnectorDefinition tem as seguintes propriedades:

Configurar a interface do usuário do conector

Esta seção descreve as opções de configuração disponíveis para personalizar a interface do usuário da página do conector de dados.

A captura de tela a seguir mostra uma página de conector de dados de exemplo, realçada com números que correspondem a áreas notáveis da interface do usuário.

Cada um dos seguintes elementos da connectorUiConfig seção necessários para configurar a interface do usuário corresponde à parte CustomizableConnectorUiConfig da API.

conectividadeCritérios

Tipos de dados

graphQueries

Define uma consulta que apresenta a ingestão de dados nas últimas duas semanas.

Forneça uma consulta para todos os tipos de dados do conector de dados ou uma consulta diferente para cada tipo de dados.

disponibilidade

permissões

fornecedor de recursos

exemploConsultas

Configurar outras opções de link

Para definir um link embutido usando markdown, use o exemplo a seguir.

{
   "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 um link como um modelo ARM, use o seguinte exemplo como guia:

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

instruçãoPassos

Esta seção fornece parâmetros que definem o conjunto de instruções que aparecem na página do conector de dados no Microsoft Sentinel e tem a seguinte estrutura:

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

Instruções

Exibe um grupo de instruções, com vários parâmetros e a capacidade de aninhar mais instructionSteps em grupos. Os parâmetros aqui definidos correspondem

OAuthForm

Este componente requer que o OAuth2 tipo esteja presente na auth propriedade do modelo de conector de dados.

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

Caixa de texto

Aqui estão alguns exemplos do Textbox tipo. Estes exemplos correspondem aos parâmetros usados na seção de exemplo auth em Referência de conectores de dados para o Codeless Connector Framework. Para cada um dos 4 tipos, cada um tem label, placeholdere 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"
  }          
}
]

RótuloCopiável

Exemplo:

Código de exemplo:

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

Menu Suspenso

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

Painel de Contexto

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

Mensagem de Informação

Eis um exemplo de uma mensagem informativa embutida:

Por outro lado, a imagem a seguir mostra uma mensagem informativa que não está embutida:

Grupo de Passos de Instrução

Aqui está um exemplo de um grupo de instruções expansível:

Para obter um exemplo detalhado, consulte a configuração JSON para o conector Windows DNS.

InstallAgent

Alguns tipos de InstallAgent aparecem como um botão, outros aparecem como um link. Aqui estão exemplos de ambos:

Exemplo de definição de conector de dados

O exemplo a seguir reúne alguns dos componentes definidos neste artigo como um formato de corpo JSON para usar com a API de definição de conector de dados Criar ou Atualizar.

Para obter mais exemplos da revisão connectorUiConfig de dados CCF. Mesmo conectores que usam o CCF herdado têm exemplos válidos da criação da interface do usuário.

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