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

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

Чтобы создать соединитель данных с помощью CCF, используйте этот документ в качестве дополнения к 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 Версия API, используемая для данной операции.

Основное содержание запроса

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

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

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

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

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

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

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

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

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

Поле Обязательно Тип Описание Снимок экрана: значимая область #
заголовок Верно струна Заголовок, отображаемый на странице соединителя данных 1
идентификатор струна Задает идентификатор пользовательского соединителя для внутреннего использования
лого струна Путь к файлу изображения в формате SVG. Если значение не настроено, используется логотип по умолчанию. 2
издатель Верно струна Поставщик соединителя 3
описаниеMarkdown Верно строка в markdown Описание соединителя с возможностью добавления языка Markdown для его улучшения. 4
sampleQueries Верно Вложенный массив JSON
sampleQueries		 Запросы клиента, чтобы понять, как найти данные в журнале событий.
graphQueries Верно Вложенный массив JSON
graphQueries		 Запросы, которые представляют прием данных за последние две недели.

Укажите один запрос для всех типов данных соединителя данных или другой запрос для каждого типа данных.		 5
graphQueriesTableName Задает имя таблицы, в который соединитель вставляет данные. Это имя можно использовать в других запросах, указав {{graphQueriesTableName}} заполнитель и graphQuerieslastDataReceivedQuery значения.
dataTypes Верно Вложенный массив JSON
dataTypes		 Список всех типов данных для соединителя и запрос для получения времени последнего события для каждого типа данных. 6
критерии подключения Верно Вложенный массив JSON
критерии подключения		 Объект, определяющий, как проверить, подключен ли соединитель. 7
наличие Вложенный массив JSON
наличие		 Объект, определяющий состояние доступности соединителя.
Разрешения Верно Вложенный массив JSON
Разрешения		 Сведения, отображаемые в разделе предварительных требований пользовательского интерфейса, в котором перечислены разрешения, необходимые для включения или отключения соединителя. 8
инструкцииSteps Верно Вложенный массив JSON
инструкции		 Массив частей мини-приложения, объясняющий установку соединителя и интерактивные элементы управления, отображаемые на вкладке "Инструкции ". 9
isConnectivityCriteriasMatchSome Булев Логическое значение, указывающее, следует ли использовать "OR"(SOME) или "AND" между элементами ConnectivityCriteria.

Критерии подключенияКритерии

Поле Обязательно Тип Описание
Тип Верно Струна Один из двух следующих вариантов: HasDataConnectors это значение лучше всего подходит для соединителей данных опроса API, таких как CCF. Соединитель считается подключенным по крайней мере с одним активным подключением.

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

типы данных

Значение массива Тип Описание
имя Струна Понятное описание,lastDataReceivedQuery включая поддержку переменной graphQueriesTableName .

Пример: {{graphQueriesTableName}}
последнийЗапросПолученияДанных Струна Запрос KQL, возвращающий одну строку и указывающий время последнего получения данных или нет данных, если результатов нет.

Пример: {{graphQueriesTableName}}\n | summarize Time = max(TimeGenerated)\n | where isnotempty(Time)

graphQueries

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

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

Значение массива Тип Описание
название метрики Струна Значимое имя для графа.

Пример: Total data received
легенда Струна Строка, которая отображается в условных обозначениях справа от диаграммы, включая ссылку на переменную.

Пример: {{graphQueriesTableName}}
baseQuery Струна Запрос, фильтрующий соответствующие события, включая ссылку на переменную.

Пример: TableName_CL | where ProviderName == "myprovider" или {{graphQueriesTableName}}.

availability

Поле Обязательно Тип Описание
статус Целое число Состояние доступности соединителя.
Доступно = 1
Флаг компонента = 2
Ближайший в ближайшее время = 3
Internal = 4
isPreview Булев Логическое значение, указывающее, находится ли соединитель в режиме предварительной версии.

Разрешения

Значение массива Тип Описание
таможня Струна Описывает все пользовательские разрешения, необходимые для подключения к данным, в следующем синтаксисе:
{
"name":строка,
строка "description":
}

Пример: значение таможенной стоимости отображается в разделе "Предварительные требования" Microsoft Sentinel с синим информационным значком. В примере GitHub это значение сопоставляется с ключом личного маркера API GitHub: вам нужен доступ к личному токену GitHub...
лицензии ENUM Определяет необходимые лицензии как одно из следующих значений: OfficeIRM,OfficeATP, Office365, AadP1P2, Mcas, Aatp, Mdatp, Mtp, IoT

Пример: значения лицензии отображаются в Microsoft Sentinel следующим образом: Лицензия: обязательная Azure AD Premium P2.
resourceProvider resourceProvider Описывает все необходимые условия для ресурса Azure.

Пример: Значение resourceProvider отображается в разделе "Предварительные требования" Microsoft Sentinel как:
Рабочее пространство: требуется разрешение на чтение и запись.
Ключи: требуются разрешения на доступ к чтению общих ключей для рабочей области.
арендатор массив значений ENUM
Пример:

"tenant": [
"GlobalADmin",
"SecurityAdmin"
]
 Определяет необходимые разрешения, как одно или несколько следующих значений: "GlobalAdmin", "SecurityAdmin", "SecurityReader", "InformationProtection"

Пример: Отображает значение арендатора в Microsoft Sentinel следующим образом: Разрешения арендатора: требует Global Administrator или Security Administrator в арендаторе рабочей области

Это важно

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

поставщик ресурсов

Значение вложенного массива Тип Описание
провайдер 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"
текстОтображенияРазрешений Струна Текст отображения для разрешений Чтение, Записьили Чтение и Запись, которые должны соответствовать значениям, настроенным в требуемых разрешениях
необходимыеРазрешения {
"action":булевский,
"delete":булевский,
"read":булевский,
"write":булев тип
}		 Описывает минимальные разрешения, необходимые для соединителя.
область ENUM Описывает область соединителя данных, как одно из следующих значений: "Subscription", "ResourceGroup", "Workspace"

примерЗапросов

Значение массива Тип Описание
описание Струна Понятное описание примера запроса.

Пример: Top 10 vulnerabilities detected
запрос Струна Пример запроса, используемый для получения данных типа данных.

Пример: {{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})"
}

шаги инструкций

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

"instructionSteps": [
    {
        "title": "",
        "description": "",
        "instructions": [
        {
            "type": "",
            "parameters": {}
        }
        ],
        "innerSteps": {}
    }
]
Свойство Массива Обязательно Тип Описание
заголовок Струна Определяет заголовок для инструкций.
описание Струна Определяет значимое описание ваших инструкций.
внутренние шаги Массив Определяет массив внутренних шагов инструкций.
инструкции Верно Массив инструкций Определяет массив инструкций определенного типа параметра.

инструкции

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

Тип Свойство Array Описание
OAuthForm OAuthForm Подключение с помощью OAuth
Текстовое поле Текстовое поле Эти пары с ConnectionToggleButton. Существует 4 доступных типа:
  • password
  • text
  • number
  • email
    		•
    ConnectionToggleButton ConnectionToggleButton Активируйте развертывание DCR на основе сведений о подключении, предоставленных с помощью параметров заполнителя. Поддерживаются следующие параметры:
  • name :обязательный
  • disabled
  • isPrimary
  • connectLabel
  • disconnectLabel
    		•
    Копируемая метка Копируемая метка Отображает текстовое поле с кнопкой копирования в конце. При выборе кнопки копируется значение поля.
    Раскрывающийся список Раскрывающийся список Отображает раскрывающийся список параметров для выбора пользователя.
    Markdown Markdown Отображает раздел текста, отформатированный с помощью Markdown.
    DataConnectorsGrid DataConnectorsGrid Отображает сетку соединителей данных.
    ContextPane ContextPane Отображает контекстную область сведений.
    ИнформационноеСообщение ИнформационноеСообщение Определяет встроенное информационное сообщение.
    ГруппаЭтаповИнструкции ГруппаЭтаповИнструкции Отображает группу инструкций, дополнительно развернутую или свертываемую, в отдельном разделе инструкций.
    УстановитьАгент УстановитьАгент Отображает ссылку на другие части 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"
  }          
}
]
    Копируемая метка

    Пример:

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

    Пример кода:

    {
    "parameters": {
        "fillWith": [
            "WorkspaceId",
            "PrimaryKey"
            ],
        "label": "Here are some values you'll need to proceed.",
        "value": "Workspace is {0} and PrimaryKey is {1}"
    },
    "type": "CopyableLabel"
}
    Значение массива Обязательно Тип Описание
    заполнить ENUM Массив переменных среды, используемых для заполнения шаблона. Разделяйте несколько заполнителей запятыми. Например: {0},{1}

    Поддерживаемые значения: workspaceId, workspaceName, primaryKey, MicrosoftAwsAccount, subscriptionId
    метка Верно Струна Определяет текст для метки над текстовым полем.
    значение Верно Струна Определяет значение, которое будет представлено в текстовом поле, поддерживает заполнители.
    строк Строки Определяет строки в области пользовательского интерфейса. По умолчанию установите значение 1.
    wideLabel Булев Определяет широкую надпись для длинных строк. По умолчанию установите значение false. 
    {
  "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"
}
    Поле Обязательно Тип Описание
    метка Верно Струна Определяет текст для метки над раскрывающимся списком.
    имя Верно Струна Определяет уникальное имя раскрывающегося списка. Это используется в конфигурации опроса.
    параметры Верно Массив Определяет список параметров раскрывающегося списка.
    заполнитель Струна Определяет текст заполнителя для раскрывающегося списка.
    isMultiSelect Булев Определяет, можно ли выбрать несколько параметров. По умолчанию установите значение false.
    обязательный параметр Булев Если trueнужно заполнить раскрывающийся список.
    defaultAllSelected Булев Если trueпо умолчанию выбраны все параметры.
    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"
    ]
  }
}
    Поле Обязательно Тип Описание
    сопоставление Верно Массив Определяет сопоставление столбцов в сетке.
    menuItems Массив Определяет элементы меню для сетки.
    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
              }
            }
          }
        ]
      }
    ]
  }
}
    Поле Обязательно Тип Описание
    заголовок Верно Струна Заголовок области контекста.
    подзаголовок Верно Струна Подзаголовок области контекста.
    contextPaneType Верно Струна Тип области контекста.
    инструкцииSteps Верно Массив
    инструкцииSteps    		 Инструкции для области контекста.
    метка Струна Метка для области контекста.
    isPrimary Булев Указывает, является ли это основной областью контекста.
    InfoMessage

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

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

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

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

    Значение массива Тип Описание
    текст Струна Определите текст, отображаемый в сообщении.
    видимый Булев Определяет, отображается ли сообщение.
    встроенный Булев Определяет, как отображается информационное сообщение.

    - true: (рекомендуется) Отображает информационное сообщение, внедренное в инструкции.
    - false: добавляет синий фон.
    ГруппаЭтаповИнструкции

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

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

    Значение массива Обязательно Тип Описание
    заголовок Верно Струна Определяет заголовок шага инструкции.
    описание Струна Необязательный текст.
    может свернуть все разделы Булев Определяет, является ли раздел сворачиваемым аккордеоном или нет.
    noFxPadding Булев Если true, уменьшает отступ по высоте, чтобы сэкономить место.
    расширенный Булев Если true, отображается в состоянии развернуто по умолчанию.

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

    Агент установки

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

    снимок экрана: ссылка, добавленная в виде кнопки.

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

    Значения массива Обязательно Тип Описание
    тип_ссылки Верно ENUM Определяет тип ссылки в качестве одного из следующих значений:

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

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

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

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

    {
    "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"
                  }
                }
              ]
            }
          ]
        }
    }
}
    • Last updated on