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

Para criar um conector de dados com o CCF (Codeless Connector Framework), use este documento como um suplemento para os documentos de referência da API REST do Microsoft Sentinel para Definições do Conector de Dados . Especificamente, este documento de referência se expande na seção a seguir:

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

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

Definições do conector de dados – Criar ou atualizar

Faça referência à operação Criar ou Atualizar nos documentos da API REST para localizar a versão mais recente da API estável ou de versão prévia. Somente 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 da 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 do 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.

critérios de conectividade

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.

availability

permissões

fornecedor de recursos

sampleQueries

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 do ARM, use o seguinte exemplo como um 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})"
}

instructionSteps

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 definidos aqui correspondem

OAuthForm

Esse componente requer que o OAuth2 tipo esteja presente na auth propriedade do modelo do 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. Esses exemplos correspondem aos parâmetros usados na seção de exemplo auth na referência de conectores de dados para o Codeless Connector Framework. Para cada um dos quatro 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"
}

Lista suspensa

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

Aqui está um exemplo de uma mensagem de informação integrada:

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

InstructionStepsGroup

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

Para um exemplo detalhado, consulte o JSON de configuração do conector DNS do Windows .

Agente de Instalação

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

Definição do conector de dados de exemplo

O exemplo a seguir reúne alguns dos componentes definidos neste artigo como um formato de corpo JSON a ser usado com a API de definição do conector de dados Create Or Update.

Para obter mais exemplos da revisão de connectorUiConfigoutros conectores de dados CCF. Até 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"
                  }
                }
              ]
            }
          ]
        }
    }
}