Referência de definições de conector de dados para a plataforma Codeless Connector

Artigo
02/23/2024

Para criar um conector de dados com a CCP (Codeless Connector Platform), 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 expande a seguinte seção:

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 de conector de dados - Criar ou atualizar

Consulte a operação Criar ou atualizar nos documentos da API REST para localizar a versão estável ou de visualização mais recente da API. 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 do 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

Nome	Descrição
dataConnectorDefinitionName	A definição do conector de dados deve ser um nome exclusivo e é igual ao `name` parâmetro no corpo da solicitação.
resourceGroupName	O nome do grupo de recursos, não diferencia maiúsculas de minúsculas.
subscriptionId	A ID da assinatura de destino.
workspaceName	O nome do espaço de trabalho, não o ID. Padrão Regex: `^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$`
api-version	A versão da API a ser usada para esta operação.

Corpo da solicitação

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

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

dataConnectorDefinition tem as seguintes propriedades:

Nome	Obrigatória	Type	Descrição
Kind	True	String	`Customizable` para conector de dados de sondagem de API ou `Static` de outra forma
Propriedades.connectorUiConfig	Verdadeiro	JSON aninhado connectorUiConfig	As propriedades de configuração da interface do usuário do conector de dados

Configurar a interface do usuário do seu 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.

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

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

Campo	Obrigatório	Type	Descrição	Captura de tela área notável #
title	True	string	Título exibido na página do conector de dados	1
id		string	Define a ID do conector personalizada para uso interno
logotipo		string	Caminho para o arquivo de imagem no formato SVG. Se nenhum valor for configurado, um logotipo padrão será usado.	2
Publicador	True	string	O provedor do conector	3
descriptionMarkdown	Verdadeiro	cadeia de caracteres na marcação	Uma descrição para o conector com a capacidade de adicionar a linguagem markdown para aprimorá-la.	4
sampleQueries	Verdadeiro	JSON aninhado sampleQueries	Consultas para que o cliente entenda como localizar os dados no log de eventos.
graphQueries	Verdadeiro	JSON aninhado graphQueries	Consultas que apresentam ingestão de dados nas últimas duas semanas. Fornece uma consulta para todos os tipos de dados do conector de dados ou uma consulta diferente para cada tipo de dados.	5
graphQueriesTableName		Define o nome da tabela na qual o conector insere dados. Esse nome pode ser usado em outras consultas especificando `{{graphQueriesTableName}}` espaços reservados em `graphQueries` e `lastDataReceivedQuery` valores.
dataTypes	Verdadeiro	JSON aninhado dataTypes	Uma lista de todos os tipos de dados para o conector e uma consulta para buscar a hora do último evento para cada tipo de dados.	6
connectivityCriteria	Verdadeiro	JSON aninhado connectivityCriteria	Um objeto que define como verificar se o conector está conectado.	7
permissões	Verdadeiro	JSON aninhado permissões	As informações exibidas na seção Pré-requisitos da interface do usuário, que lista as permissões necessárias para habilitar ou desabilitar o conector.	8
instructionSteps	Verdadeiro	JSON aninhado instruções	Uma matriz de partes do widget que explicam como instalar o conector e controles acionáveis exibidos na guia Instruções .	9

connectivityCriteria

Campo	Obrigatório	Type	Descrição
Type	True	String	Uma das duas opções a seguir: `HasDataConnectors` – esse valor é melhor para conectores de dados de sondagem de API, como o CCP. O conector é considerado conectado com pelo menos uma conexão ativa. `isConnectedQuery` – este valor é melhor para outros tipos de conectores de dados. O conector é considerado conectado quando a consulta fornecida retorna dados.
Valor	True quando o tipo é `isConnectedQuery`	String	Uma consulta para determinar se os dados são recebidos dentro de um determinado período de tempo. Por exemplo: `CommonSecurityLog \| where DeviceVendor == \"Vectra Networks\"\n\| where DeviceProduct == \"X Series\"\n \| summarize LastLogReceived = max(TimeGenerated)\n \| project IsConnected = LastLogReceived > ago(7d)"`

dataTypes

Valor da matriz	Tipo	Descrição
name	String	Uma descrição significativa para o`lastDataReceivedQuery`, incluindo suporte para a `graphQueriesTableName` variável. Exemplo: `{{graphQueriesTableName}}`
lastDataReceivedQuery	String	Uma consulta KQL que retorna uma linha e indica a última vez que os dados foram recebidos, ou nenhum dado se não houver resultados. Exemplo: `{{graphQueriesTableName}}\n \| summarize Time = max(TimeGenerated)\n \| where isnotempty(Time)`

graphQueries

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

Fornece uma consulta para todos os tipos de dados do conector de dados ou uma consulta diferente para cada tipo de dados.

Valor da matriz	Tipo	Descrição
metricName	String	Um nome significativo para o gráfico. Exemplo: `Total data received`
legend	String	A cadeia de caracteres que aparece na legenda à direita do gráfico, incluindo uma referência de variável. Exemplo: `{{graphQueriesTableName}}`
baseQuery	String	A consulta que filtra eventos relevantes, incluindo uma referência de variável. Por exemplo: `TableName_CL \| where ProviderName == "myprovider"` ou `{{graphQueriesTableName}}`

permissões

Valor da matriz	Tipo	Descrição
customs	String	Descreve todas as permissões personalizadas necessárias para sua conexão de dados, conforme a seguinte sintaxe: `{` `"name":`cadeia de caracteres`,` `"description":`string `}` Exemplo: O valor aduaneiro é exibido na seção Pré-requisitos do Microsoft Sentinel com um ícone informativo azul. No exemplo do GitHub, esse valor se correlaciona com a linha Chave de token pessoal da API do GitHub: Você precisa acessar o token pessoal do GitHub...
licenças	ENUM	Define as licenças necessárias, como um dos seguintes valores: `OfficeIRM`, `OfficeATP`, `Office365`, `AadP1P2`, `Mcas`, `Aatp`, `Mdatp`, `Mtp`, `IoT` Exemplo: o valor licenses é exibido no Microsoft Sentinel como: Licença: requer Azure AD Premium P2
resourceProvider	resourceProvider	Descreve os pré-requisitos para o seu recurso do Azure. Exemplo: O valor resourceProvider é exibido na seção Pré-requisitos do Microsoft Sentinel como: Workspace: a permissão de leitura e gravação é necessária. Keys: são necessárias permissões de leitura nas chaves compartilhadas do workspace.
tenant	matriz de valores ENUM Exemplo: `"tenant": [` `"GlobalADmin",` `"SecurityAdmin"` `]`	Define as permissões necessárias, como um ou mais dos seguintes valores: `"GlobalAdmin"`, `"SecurityAdmin"`, `"SecurityReader"`, `"InformationProtection"` Exemplo: Exibe o valor locatário no Microsoft Sentinel como: Permissões de locatário: Requer `Global Administrator` ou `Security Administrator` no locatário do workspace

ResourceProvider

valor da sub matriz	Tipo	Descrição
provedor	ENUM	Descreve o provedor de recursos, com um dos seguintes valores: - `Microsoft.OperationalInsights/workspaces` - `Microsoft.OperationalInsights/solutions` - `Microsoft.OperationalInsights/workspaces/datasources` - `microsoft.aadiam/diagnosticSettings` - `Microsoft.OperationalInsights/workspaces/sharedKeys` - `Microsoft.Authorization/policyAssignments`
providerDisplayName	String	Um item de lista em Pré-requisitos que exibe uma marca de seleção vermelha "x" ou verde quando as requiredPermissions são validadas na página do conector. Exemplo, `"Workspace"`
permissionsDisplayText	String	Exibir texto para permissões de Leitura, Gravação ou Leitura e Gravação que devem corresponder aos valores configurados em requiredPermissions
requiredPermissions	`{` `"action":`Booliano`,` `"delete":`Booliano`,` `"read":`Booliano`,` `"write":`Booliano `}`	Descreve as permissões mínimas necessárias para o conector.
escopo	ENUM	Descreve o escopo do conector de dados, como um dos seguintes valores: `"Subscription"`, `"ResourceGroup"`, `"Workspace"`

sampleQueries

valor da matriz	Tipo	Descrição
descrição	String	Uma descrição significativa para a consulta de exemplo. Exemplo: `Top 10 vulnerabilities detected`
consulta	String	Consulta de exemplo usada para buscar os dados do tipo de dados. Exemplo: `{{graphQueriesTableName}}\n \| sort by TimeGenerated\n \| take 10`

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

Propriedade de matriz	Obrigatório	Type	Descrição
title		String	Define um título para as suas instruções.
descrição		String	Define uma descrição significativa para as suas instruções.
innerSteps		Array	Define uma matriz de etapas de instrução interna.
instruções	Verdadeiro	Matriz de instruções	Define uma matriz de instruções de um tipo de parâmetro específico.

instruções

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

Tipo	Propriedade de matriz	Descrição
OAuthForm	OAuthForm	Conectar-se ao OAuth
Caixa de texto	Caixa de texto	Isso combina com `ConnectionToggleButton`o . Existem 4 tipos disponíveis: `password` `text` `number` `email`
ConnectionToggleButton	ConnectionToggleButton	Acione a implantação do DCR com base nas informações de conexão fornecidas por meio de parâmetros de espaço reservado. Os seguintes parâmetros são compatíveis: `name` :obrigatório `disabled` `isPrimary` `connectLabel` `disconnectLabel`
CopyableLabel	CopyableLabel	Mostra um campo de texto com um botão de cópia no final. Quando o botão é selecionado, o valor do campo é copiado.
InfoMessage	InfoMessage	Define uma mensagem de informações embutida.
InstructionStepsGroup	InstructionStepsGroup	Exibe um grupo de instruções, opcionalmente expandidas ou recolhidas, em uma seção de instruções separada.
InstallAgent	InstallAgent	Exibe um link para outras partes do Azure para atender a vários requisitos de instalação.

OAuthForm

Esse 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. Esses exemplos correspondem aos parâmetros usados na seção de exemplo auth em Referência de conectores de dados para a plataforma Codeless Connector. 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"
  }          
}
]

CopyableLabel

Exemplo:

Screenshot of a copy value button in a field.

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

Valor da matriz	Obrigatório	Type	Descrição
fillWith		ENUM	Matriz de variáveis de ambiente usadas para preencher um espaço reservado. Separa vários espaço reservados com vírgulas. Por exemplo: `{0},{1}` Valores com suporte: `workspaceId`, `workspaceName`, `primaryKey`, `MicrosoftAwsAccount`, `subscriptionId`
label	True	String	Define o texto do rótulo acima de uma caixa de texto.
value	True	String	Define o valor a ser apresentado na caixa de texto e dá suporte a espaço reservados.
rows		Linhas	Define as linhas na área de interface do usuário. Por padrão, definido como 1.
wideLabel		Booliano	Determina um rótulo largo para cadeias de caracteres longas. Por padrão, definido como `false`.

InfoMessage

Aqui está um exemplo de uma mensagem de informações embutida:

Screenshot of an inline information message.

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

Screenshot of an information message that's not inline.

Valor da matriz	Tipo	Descrição
text	String	Define texto a ser exibido na mensagem.
visible	Boolean	Determina se a mensagem é exibida.
inline	Boolean	Determina como a mensagem de informações é exibida. - `true`: (Recomendado) Mostra a mensagem de informações inserida nas instruções. - `false`: adiciona uma tela de fundo azul.

InstructionStepsGroup

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

Screenshot of an expandable, extra instruction group.

Valor da matriz	Obrigatório	Type	Descrição
title	True	String	Define o título para a etapa de instrução.
descrição		String	Texto descritivo opcional.
canCollapseAllSections		Booliano	Determina se a seção é uma sanfona que pode ser colapsada ou não.
noFxPadding		Booliano	Se `true`, reduzirá o preenchimento de altura para economizar espaço.
expanded		Booliano	Se `true`, mostrará como expandido por padrão.

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

InstallAgent

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

Screenshot of a link added as inline text.

Valores de matriz	Obrigatório	Type	Descrição
linkType	Verdadeiro	ENUM	Determina o tipo de link, como um dos seguintes valores: `InstallAgentOnWindowsVirtualMachine` `InstallAgentOnWindowsNonAzure` `InstallAgentOnLinuxVirtualMachine` `InstallAgentOnLinuxNonAzure` `OpenSyslogSettings` `OpenCustomLogsSettings` `OpenWaf` `OpenAzureFirewall` `OpenMicrosoftAzureMonitoring` `OpenFrontDoors` `OpenCdnProfile` `AutomaticDeploymentCEF` `OpenAzureInformationProtection` `OpenAzureActivityLog` `OpenIotPricingModel` `OpenPolicyAssignment` `OpenAllAssignmentsBlade` `OpenCreateDataCollectionRule`
policyDefinitionGuid	True ao usar `OpenPolicyAssignment` linkType.	String	Para conectores baseados em políticas, define o GUID da definição de política interna.
assignMode		ENUM	Para conectores baseados em política, define o modo de atribuição, como um dos seguintes valores: `Initiative`, `Policy`
dataCollectionRuleType		ENUM	Para conectores baseados em DCR, define o tipo de regra de coleta de dados como `SecurityEvent`, ou `ForwardEvent`.

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 a ser usado com a API de definição do conector de dados Criar ou Atualizar.

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

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

Share via