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

Artigo
10/16/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 de Conector de Dados . 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

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.
nome do espaço de trabalho	O nome do espaço de trabalho, não a ID. Padrão Regex: `^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$`
API-versão	A versão da API a utilizar para esta operação.

Corpo do pedido

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ório	Type	Descrição
Variante	True	String	`Customizable` para API polling data connector ou `Static` de outra forma
propriedades.conectorUiConfig	True	JSON aninhado conectorUiConfig	As propriedades de configuração da interface do usuário do conector de dados

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.

Captura de tela de uma página de conector de dados de exemplo com seções rotuladas de 1 a 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	Necessário	Type	Description	Área notável da captura de tela #
title	True	string	Título exibido na página do conector de dados	1
id		string	Define ID de conector personalizado para uso interno
Logótipo		string	Caminho para o arquivo de imagem no formato SVG. Se nenhum valor for configurado, um logotipo padrão será usado.	2
editora	True	string	O provedor do conector	3
descriçãoMarkdown	True	string em markdown	Uma descrição para o conector com a capacidade de adicionar linguagem de marcação para melhorá-lo.	4
exemploConsultas	True	JSON aninhado exemploConsultas	Consultas para o cliente entender como encontrar os dados no log de eventos.
graphQueries	True	JSON aninhado graphQueries	Consultas que apresentam 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.	5
graphQueriesTableName		Define o nome da tabela na qual o conector insere dados. Esse nome pode ser usado em outras consultas, especificando `{{graphQueriesTableName}}` espaço reservado em `graphQueries` e `lastDataReceivedQuery` valores.
Tipos de dados	True	JSON aninhado Tipos de dados	Uma lista de todos os tipos de dados para seu conector e uma consulta para buscar a hora do último evento para cada tipo de dados.	6
conectividadeCritérios	True	JSON aninhado conectividadeCritérios	Um objeto que define como verificar se o conector está conectado.	7
permissions (permissões)	True	JSON aninhado permissions (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
instruçãoPassos	True	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

conectividadeCritérios

Campo	Necessário	Type	Description
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.
Value	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)"`

Tipos de dados

Valor da matriz	Tipo	Description
Designação	Cadeia (de carateres)	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.

Forneça 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	Description
metricName	String	Um nome significativo para o seu gráfico. Exemplo: `Total data received`
lenda	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 variável. Exemplo: `TableName_CL \| where ProviderName == "myprovider"` ou `{{graphQueriesTableName}}`

permissões

Valor da matriz	Tipo	Description
Alfândegas	String	Descreve as permissões personalizadas necessárias para sua conexão de dados, na seguinte sintaxe: `{` `"name":`string`,` `"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 está correlacionado à linha GitHub API personal token Key: You need access to GitHub personal token...
Licenças	ENUM	Define as licenças necessárias, como um dos seguintes valores: ,, , , , , `MdatpAatp`, `Mtp`, `McasAadP1P2Office365OfficeATPOfficeIRMIoT` Exemplo: O valor das licenças é exibido no Microsoft Sentinel como: Licença: Necessário Azure AD Premium P2
resourceProvider	resourceProvider	Descreve todos os pré-requisitos para seu recurso do Azure. Exemplo: O valor resourceProvider é exibido na seção Pré-requisitos do Microsoft Sentinel como: Espaço de trabalho: é necessária permissão de leitura e gravação. Chaves: são necessárias permissões de leitura para chaves compartilhadas para o espaço de trabalho.
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 do locatário no Microsoft Sentinel como: Permissões de locatário: requer `Global Administrator` ou `Security Administrator` no locatário do espaço de trabalho

Importante

A Microsoft recomenda que você use funções com o menor número de permissões. Isso ajuda a melhorar a segurança da sua organização. Administrador Global é uma função altamente privilegiada que deve ser limitada a cenários de emergência quando você não pode usar uma função existente.

resourceProvider

valor da submatriz	Tipo	Description
fornecedor	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 permissões necessárias são validadas na página do conector. Exemplo, `"Workspace"`
permissõesDisplayText	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":`Booleano`,` `"delete":`Booleano`,` `"read":`Booleano`,` `"write":`Booleano `}`	Descreve as permissões mínimas necessárias para o conector.
Âmbito de aplicação	ENUM	Descreve o escopo do conector de dados, como um dos seguintes valores: `"Subscription"`, `"ResourceGroup"`, `"Workspace"`

exemploConsultas

Valor da matriz	Tipo	Description
descrição	String	Uma descrição significativa para a consulta de exemplo. Exemplo: `Top 10 vulnerabilities detected`
query	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 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": {}
    }
]

Propriedade Array	Necessário	Type	Description
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		Matriz	Define uma matriz de etapas de instrução internas.
Instruções	True	Conjunto 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 instructionSteps em grupos. Os parâmetros aqui definidos correspondem

Type	Propriedade Array	Description
OAuthForm	OAuthForm	Conecte-se com OAuth
Caixa de texto	Caixa de texto	Isto emparelha com `ConnectionToggleButton`. 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 suportados: `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.
Mensagem de Informação	Mensagem de Informação	Define uma mensagem informativa embutida.
InstruçãoPassosGrupo	InstruçãoPassosGrupo	Exibe um grupo de instruções, opcionalmente expandidas ou dobráveis, em uma seção de instruções separada.
InstallAgent	InstallAgent	Exibe um link para outras partes do Azure para cumprir vários requisitos de instalação.

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 detexto

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 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:

Captura de ecrã de um botão de valor de cópia num campo.

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	Necessário	Type	Description
preenchimentoCom		ENUM	Matriz de variáveis de ambiente usadas para preencher um espaço reservado. Separe vários espaços reservados com vírgulas. Por exemplo: `{0},{1}` Valores suportados: `workspaceId`, `workspaceName`, `primaryKey`, `MicrosoftAwsAccount`, , `subscriptionId`
etiqueta	True	String	Define o texto para o rótulo acima de uma caixa de texto.
valor	True	String	Define o valor a ser apresentado na caixa de texto, suporta espaços reservados.
linhas		Linhas	Define as linhas na área de interface do usuário. Por padrão, defina como 1.
wideLabel		Boolean	Determina um rótulo largo para cadeias de caracteres longas. Por padrão, defina como `false`.

Mensagem de Informação

Eis um exemplo de uma mensagem informativa embutida:

Captura de ecrã de uma mensagem informativa embutida.

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

Captura de ecrã de uma mensagem informativa que não está incorporada.

Valor da matriz	Tipo	Descrição
texto	String	Defina o texto a ser exibido na mensagem.
visível	Boolean	Determina se a mensagem é exibida.
em linha	Boolean	Determina como a mensagem informativa é exibida. - `true`: (Recomendado) Mostra a mensagem informativa incorporada nas instruções. - `false`: Adiciona um fundo azul.

InstruçãoPassosGrupo

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

Captura de ecrã de um grupo de instruções extra expansível.

Valor da matriz	Necessário	Type	Description
title	True	String	Define o título da etapa de instrução.
descrição		String	Texto descritivo opcional.
canCollapseAllSections		Boolean	Determina se a seção é um acordeão dobrável ou não.
noFxPadding		Boolean	Se `true`, reduz o preenchimento de altura para economizar espaço.
expandida		Boolean	Se `true`, é exibido como expandido por padrão.

Para obter um exemplo detalhado, consulte a configuração JSON 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:

Captura de tela de um link adicionado como texto embutido.

Valores de matriz	Necessário	Type	Description
tipo de ligação	True	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`
policyDefiniçãoGuid	True ao usar `OpenPolicyAssignment` linkType.	String	Para conectores baseados em política, 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 para usar com a API de definição de conector de dados Criar ou Atualizar.

Para obter mais exemplos da revisão de outros conectores de connectorUiConfig dados CCP. Mesmo conectores que usam a CCP herdada 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"
                  }
                }
              ]
            }
          ]
        }
    }
}

Partilhar via