Справочник по определениям соединителя данных для платформы соединителя без кода

Статья
02/21/2024

Чтобы создать соединитель данных с помощью платформы соединителя без кода (CCP), используйте этот документ в качестве дополнения к REST API Microsoft Sentinel для ссылок по определениям соединителя данных. В частности, этот справочный документ расширяется в следующем разделе:

connectorUiConfig — определяет визуальные элементы и текст, отображаемые на странице соединителя данных в Microsoft Sentinel.

Дополнительные сведения см. в статье "Создание соединителя без кода".

Определения соединителя данных — создание или обновление

Найдите последнюю стабильную или предварительную версию API в документации по REST API. update Для операции требуется etag только значение.

Метод PUT

https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.OperationalInsights/workspaces/{{workspaceName}}/providers/Microsoft.SecurityInsights/dataConnectorDefinitions/{{dataConnectorDefinitionName}}?api-version={{apiVersion}}

Параметры универсального кода ресурса (URI)

Дополнительные сведения о последней версии API см. в разделе "Определения соединителя данных" — создание или обновление ПАРАМЕТРОВ URI

Имя	Описание
dataConnectorDefinitionName	Определение соединителя данных должно быть уникальным именем и совпадает с `name` параметром в тексте запроса.
resourceGroupName	Имя группы ресурсов, а не регистр.
subscriptionId	Идентификатор целевой подписки.
имя рабочей области	Имя рабочей области, а не идентификатор. Шаблон регулярного выражения: `^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$`
api-version	Версия API, используемая для данной операции.

Текст запроса

Текст запроса для создания определения соединителя данных CCP с API имеет следующую структуру:

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

dataConnectorDefinition имеет следующие свойства:

имени	Обязательно	Type	Описание
Вид	Истина	Строка	`Customizable` для соединителя данных опроса API или в `Static` противном случае
свойства.connectorUiConfig	Истина	Вложенный массив JSON connectorUiConfig	Свойства конфигурации пользовательского интерфейса соединителя данных

Настройка пользовательского интерфейса соединителя

В этом разделе описываются параметры конфигурации, доступные для настройки пользовательского интерфейса страницы соединителя данных.

На следующем снимке экрана показана страница соединителя данных, выделенная с цифрами, соответствующими заметным областям пользовательского интерфейса.

Снимок экрана: страница примера соединителя данных с разделами, помеченными как 1–9.

Каждый из следующих элементов раздела, необходимый для настройки пользовательского connectorUiConfig интерфейса, соответствует части API ConfigureableConnectorUiConfig.

Поле	Обязательное поле	Type	Описание	Снимок экрана: значимая область #
title	Истина	строка	Заголовок, отображаемый на странице соединителя данных	1
id		строка	Задает идентификатор пользовательского соединителя для внутреннего использования
лого		строка	Путь к файлу изображения в формате SVG. Если значение не настроено, используется логотип по умолчанию.	2
publisher	Истина	строка	Поставщик соединителя	3
descriptionMarkdown	Истина	строка в markdown	Описание соединителя с возможностью добавления языка Markdown для его улучшения.	4
sampleQueries	Истина	Вложенный массив JSON sampleQueries	Запросы клиента, чтобы понять, как найти данные в журнале событий.
graphQueries	Истина	Вложенный массив JSON graphQueries	Запросы, которые представляют прием данных за последние две недели. Укажите либо один запрос для всех типов данных соединителя данных, либо отдельный запрос для каждого типа данных.	5
graphQueriesTableName		Задает имя таблицы, в который соединитель вставляет данные. Это имя можно использовать в других запросах, указав `{{graphQueriesTableName}}` заполнитель и `graphQueries` `lastDataReceivedQuery` значения.
dataTypes	Истина	Вложенный массив JSON dataTypes	Список всех типов данных для вашего соединителя и запрос для получения сведений о времени последнего события для каждого типа данных.	6
connectivityCriteria	Истина	Вложенный массив JSON connectivityCriteria	Объект, определяющий, как проверить, подключен ли соединитель.	7
разрешения	Истина	Вложенный массив JSON разрешения	Сведения, отображаемые в разделе предварительных требований пользовательского интерфейса, в котором перечислены разрешения, необходимые для включения или отключения соединителя.	8
instructionSteps	Истина	Вложенный массив JSON instructions	Массив частей мини-приложения, объясняющий установку соединителя и интерактивные элементы управления, отображаемые на вкладке "Инструкции ".	9

connectivityCriteria

Поле	Обязательное поле	Type	Описание
Тип	Истина	Строка	Один из двух следующих вариантов: `HasDataConnectors` это значение лучше всего подходит для соединителей данных опроса API, таких как CCP. Соединитель считается подключенным по крайней мере с одним активным подключением. `isConnectedQuery` — это значение лучше всего подходит для других типов соединителей данных. Соединитель считается подключенным, когда предоставленный запрос возвращает данные.
Значение	Значение True, если тип имеет значение `isConnectedQuery`	Строка	Запрос, определяющий, получены ли данные в течение определенного периода времени. Например: `CommonSecurityLog \| where DeviceVendor == \"Vectra Networks\"\n\| where DeviceProduct == \"X Series\"\n \| summarize LastLogReceived = max(TimeGenerated)\n \| project IsConnected = LastLogReceived > ago(7d)"`

dataTypes

Значение массива	Тип	Description
name	Строка	Понятное описание,`lastDataReceivedQuery` включая поддержку переменной `graphQueriesTableName` . Пример: `{{graphQueriesTableName}}`
lastDataReceivedQuery	Строка	Запрос KQL, возвращающий одну строку и указывающий время последнего получения данных или нет данных, если результатов нет. Пример: `{{graphQueriesTableName}}\n \| summarize Time = max(TimeGenerated)\n \| where isnotempty(Time)`

graphQueries

Определяет запрос, который представляет прием данных за последние две недели.

Укажите либо один запрос для всех типов данных соединителя данных, либо отдельный запрос для каждого типа данных.

Значение массива	Тип	Описание
metricName	Строка	Понятное имя графа. Пример: `Total data received`
legend	Строка	Строка, которая отображается в условных обозначениях справа от диаграммы, в том числе ссылка на переменную. Пример: `{{graphQueriesTableName}}`
baseQuery	Строка	Запрос, который фильтрует соответствующие события, включая ссылку на переменную. Пример: `TableName_CL \| where ProviderName == "myprovider"` или `{{graphQueriesTableName}}`.

разрешения

Значение массива	Тип	Описание
customs	Строка	Описывает все пользовательские разрешения, необходимые для подключения к данным, в следующем синтаксисе: `{` `"name":`string`,` `"description":`струна `}` Пример. Таможенные значения отображаются в разделе "Предварительные требования Microsoft Sentinel" с синим информационным значком. В примере GitHub это значение сопоставляется с ключом личного маркера API GitHub: вам нужен доступ к личному токену GitHub...
Лицензии	ENUM	Определяет необходимые лицензии как одно из следующих значений: `OfficeIRMOfficeATPOffice365AadP1P2McasAatpMdatpMtpIoT` Пример: значение licenses отображается в Microsoft Sentinel как "Лицензия". необходимое значение: Azure AD Premium P2
resourceProvider	resourceProvider	Описывает необходимые компоненты для вашего ресурса Azure. Пример: значение resourceProvider отображается в разделе предварительных требований Microsoft Sentinel следующим образом: Рабочая область: требуется разрешение на чтение и запись. "Ключи": необходимы разрешения на чтение общих ключей для рабочей области.
tenant	массив значений ENUM Пример: `"tenant": [` `"GlobalADmin",` `"SecurityAdmin"` `]`	Определяет необходимые разрешения в виде одного или нескольких следующих значений: `"GlobalAdmin"`, `"SecurityAdmin"`, `"SecurityReader"`, `"InformationProtection"` Пример: отображает значение клиента в Microsoft Sentinel следующим образом: разрешения клиента : требуется `Global Administrator` или `Security Administrator` в клиенте рабочей области

Внимание

Корпорация Майкрософт рекомендует использовать роли с наименьшими разрешениями. Это помогает повысить безопасность вашей организации. Глобальный администратор — это высоко привилегированная роль, которая должна быть ограничена сценариями чрезвычайных ситуаций, когда вы не можете использовать существующую роль.

resourceProvider

Значение вложенного массива	Тип	Описание
provider	ENUM	Описывает поставщик ресурсов с одним из следующих значений: - `Microsoft.OperationalInsights/workspaces` - `Microsoft.OperationalInsights/solutions` - `Microsoft.OperationalInsights/workspaces/datasources` - `microsoft.aadiam/diagnosticSettings` - `Microsoft.OperationalInsights/workspaces/sharedKeys` - `Microsoft.Authorization/policyAssignments`
providerDisplayName	Строка	Элемент списка в разделе "Предварительные требования" , отображающий красный флажок "x" или зеленый, когда необходимыеpermissions проверяются на странице соединителя. Пример `"Workspace"`
permissionsDisplayText	Строка	Отображение текста для разрешений на чтение, запись или запись , которые должны соответствовать значениям, настроенным в обязательныхpermissions
requiredPermissions	`{` `"action":`Boolean`,` `"delete":`Boolean`,` `"read":`Boolean`,` `"write":`Булев `}`	Описывает минимальные разрешения, необходимые для соединителя.
область	ENUM	Описывает область действия соединителя данных как одно из следующих значений: `"Subscription"`, `"ResourceGroup"`, `"Workspace"`

sampleQueries

Значение массива	Тип	Описание
описание	Строка	Понятное описание примера запроса. Пример: `Top 10 vulnerabilities detected`
query	Строка	Пример запроса, используемого для получения данных типа данных. Пример: `{{graphQueriesTableName}}\n \| sort by TimeGenerated\n \| take 10`

Настройка других параметров ссылки

Чтобы определить встроенную ссылку с помощью markdown, используйте следующий пример.

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

Чтобы определить ссылку как шаблон ARM, используйте в качестве инструкции следующий пример:

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

В этом разделе приведены параметры, определяющие набор инструкций, которые отображаются на странице соединителя данных в Microsoft Sentinel и имеют следующую структуру:

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

Свойство Массива	Обязательное поле	Type	Описание
title		Строка	Определяет заголовок для инструкций.
описание		Строка	Определяет понятное описание инструкций.
innerSteps		Массив	Определяет массив шагов внутренних инструкций.
instructions	Истина	Массив инструкций	Определяет массив инструкций определенного типа параметра.

инструкции

Отображает группу инструкций с различными параметрами и возможностью вложить дополнительные инструкции В группы. Параметры, определенные здесь, соответствуют

Тип	Свойство Array	Description
OAuthForm	OAuthForm	Подключение с помощью OAuth
текстовое поле;	текстовое поле;	Эти пары с `ConnectionToggleButton`. Существует 4 доступных типа: `password` `text` `number` `email`
ConnectionToggleButton	ConnectionToggleButton	Активируйте развертывание DCR на основе сведений о подключении, предоставленных с помощью параметров заполнителя. Поддерживаются следующие параметры: `name` :обязательный `disabled` `isPrimary` `connectLabel` `disconnectLabel`
CopyableLabel	CopyableLabel	Отображает текстовое поле с кнопкой копирования в конце. При выборе кнопки копируется значение поля.
InfoMessage	InfoMessage	Определяет встроенное информационное сообщение.
ИнструкцияStepsGroup	ИнструкцияStepsGroup	Отображает группу инструкций, дополнительно развернутую или свертываемую, в отдельном разделе инструкций.
InstallAgent	InstallAgent	Отображает ссылку на другие части Azure для выполнения различных требований к установке.

OAuthForm

Этот компонент требует, чтобы OAuth2 тип присутствовал в auth свойстве шаблона соединителя данных.

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

текстовое поле;

Ниже приведены некоторые примеры Textbox типа. Эти примеры соответствуют параметрам, используемым в разделе примера auth в справочнике по соединителям данных для платформы соединителей без кода. Для каждого из 4 типов каждый из них имеет labelи placeholdername.

"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

Пример:

Снимок экрана: кнопка копирования значения в поле.

Пример кода:

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

Значение массива	Обязательное поле	Type	Описание
fillWith		ENUM	Массив переменных среды, используемых для заполнения прототипа. Несколько прототипов разделяются запятыми. Например: `{0},{1}` Поддерживаемые значения: `workspaceIdworkspaceNameprimaryKeyMicrosoftAwsAccountsubscriptionId`
label	Истина	Строка	Определяет текст метки над текстовым полем.
значение	Истина	Строка	Определяет значение, которое будет представлено в текстовом поле, поддерживает заполнители.
rows		Строки	Определяет строки в области пользовательского интерфейса. По умолчанию значение равно 1.
wideLabel		Логический	Определяет широкую метку для длинных строк. По умолчанию значение равно `false`.

InfoMessage

Ниже приведен пример встроенного информационного сообщения:

Снимок экрана: встроенное информационное сообщение.

В отличие от этого, на следующем рисунке показана информация, которая не является встроенной:

Снимок экрана: информационное сообщение, которое не является встроенным.

Значение массива	Тип	Описание
text	Строка	Определение текста, отображаемого в окне сообщения.
visible	Логический	Определяет, отображается ли сообщение.
inline	Логический	Определяет, как отображается сообщение. - `true`: (рекомендуется) отображает информационное сообщение, внедренное в инструкции. - `false`: добавляет синий фон.

ИнструкцияStepsGroup

Ниже приведен пример расширенной группы инструкций:

Снимок экрана: расширяемая отдельная группа инструкций.

Значение массива	Обязательное поле	Type	Описание
title	Истина	Строка	Определяет заголовок для шага инструкции.
описание		Строка	Необязательный текст.
canCollapseAllSections		Логический	Определяет, является ли раздел свертываемым меню "Гармошка".
noFxPadding		Логический	Если значение — `true`, уменьшает заполнение высоты для экономии пространства.
expanded		Логический	Если значение — `true`, по умолчанию будет отображатся в развернутом состоянии.

Подробный пример см. в формате JSON конфигурации для соединителя Windows DNS.

InstallAgent

Некоторые типы InstallAgent отображаются как кнопка, другие отображаются как ссылка. Ниже приведены примеры обоих:

Снимок экрана: ссылка, добавленная в качестве встроенного текста.

Значения массива	Обязательное поле	Type	Описание
linkType	Истина	ENUM	Определяет тип ссылки в качестве одного из следующих значений: `InstallAgentOnWindowsVirtualMachine` `InstallAgentOnWindowsNonAzure` `InstallAgentOnLinuxVirtualMachine` `InstallAgentOnLinuxNonAzure` `OpenSyslogSettings` `OpenCustomLogsSettings` `OpenWaf` `OpenAzureFirewall` `OpenMicrosoftAzureMonitoring` `OpenFrontDoors` `OpenCdnProfile` `AutomaticDeploymentCEF` `OpenAzureInformationProtection` `OpenAzureActivityLog` `OpenIotPricingModel` `OpenPolicyAssignment` `OpenAllAssignmentsBlade` `OpenCreateDataCollectionRule`
policyDefinitionGuid	True при использовании `OpenPolicyAssignment` linkType.	Строка	Для соединителей на основе политик определяет GUID встроенного определения политики.
assignMode		ENUM	Определяет режим назначения соединителей на основе политик как одно из следующих значений: `Initiative`, `Policy`
dataCollectionRuleType		ENUM	Для соединителей на основе DCR определяет тип правила сбора данных как `SecurityEventForwardEvent`или .

Пример определения соединителя данных

Следующий пример объединяет некоторые компоненты, определенные в этой статье, как формат текста JSON для использования с API определения соединителя данных Create Or Update.

Дополнительные примеры connectorUiConfig проверки других соединителей данных CCP. Даже соединители, использующие устаревший CCP, имеют допустимые примеры создания пользовательского интерфейса.

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

Поделиться через