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

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

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

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

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

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

Метод 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 Идентификатор целевой подписки.
workspaceName Имя рабочей области, а не идентификатор.
Шаблон регулярных выражений: ^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$
версия api Версия API, используемая для этой операции.

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

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

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

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

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

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

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

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

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

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

Поле Обязательный Тип Описание Снимок экрана: видная область #
заголовок True string Заголовок, отображаемый на странице соединителя данных 1
id string Задает настраиваемый идентификатор соединителя для внутреннего использования
logo string Путь к файлу изображения в формате SVG. Если значение не настроено, используется логотип по умолчанию. 2
Издателя True string Поставщик соединителя 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
Доступности		 Объект , определяющий состояние доступности соединителя.
permissions Верно Вложенный JSON
permissions		 Сведения, отображаемые в разделе Предварительные требования пользовательского интерфейса, в котором перечислены разрешения, необходимые для включения или отключения соединителя. 8
instructionSteps Верно Вложенный JSON
Инструкции		 Массив частей мини-приложения, в котором объясняется, как установить соединитель, и интерактивные элементы управления, отображаемые на вкладке Инструкции . 9
isConnectivityCriteriasMatchSome Логический Логическое значение, указывающее, следует ли использовать "OR" (SOME) или "AND" между элементами ConnectivityCriteria.

connectivityCriteria

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

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

dataTypes

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

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

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

graphQueries

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

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

Значение массива Тип Описание
metricName String Понятное имя графа.

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

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

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

availability

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

permissions

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

Пример. Таможенная стоимость отображается в разделе Предварительные требования Microsoft Sentinel синим информационным значком. В примере GitHub это значение коррелирует с строкой GitHub API личный токен Ключ: Вам нужен доступ к личному маркеру GitHub...
Лицензии ПЕРЕЧИСЛЕНИЯ Определяет необходимые лицензии в виде одного из следующих значений: OfficeIRM,OfficeATP , Office365, AadP1P2, Mcas, AatpMdatp, , Mtp, .IoT

Пример. Значение лицензий отображается в 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 для клиента рабочей области

Важно!

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

resourceProvider

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

sampleQueries

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

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

Пример: {{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": {}
    }
]
Свойство Array Обязательный Тип Описание
заголовок String Определяет заголовок для инструкций.
description String Определяет понятное описание инструкций.
innerSteps Array Определяет массив внутренних шагов инструкций.
Инструкции Верно Массив инструкций Определяет массив инструкций определенного типа параметра.

Инструкции

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

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

    Пример:

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

    Пример кода:

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

    Поддерживаемые значения: workspaceId, workspaceName, primaryKey, MicrosoftAwsAccount, subscriptionId
    Метки Верно String Определяет текст для метки над текстовым полем.
    value Верно String Определяет значение, которое будет представлено в текстовом поле, поддерживает заполнители.
    строки Строки Определяет строки в области пользовательского интерфейса. По умолчанию задайте значение 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"
}
    Поле Обязательный Тип Описание
    Метки Верно String Определяет текст для метки над раскрывающимся списком.
    name Верно String Определяет уникальное имя раскрывающегося списка. Используется в конфигурации опроса.
    options Верно Array Определяет список параметров раскрывающегося списка.
    Заполнитель String Определяет замещающий текст для раскрывающегося списка.
    isMultiSelect Логический Определяет, можно ли выбрать несколько параметров. По умолчанию задайте значение false.
    required Логический Если 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"
    ]
  }
}
    Поле Обязательный Тип Описание
    Сопоставление Верно Array Определяет сопоставление столбцов в сетке.
    menuItems Array Определяет пункты меню для сетки.
    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
              }
            }
          }
        ]
      }
    ]
  }
}
    Поле Обязательный Тип Описание
    заголовок Верно String Заголовок области контекста.
    подзаголовок Верно String Подзаголовок для области контекста.
    contextPaneType Верно String Тип области контекста.
    instructionSteps Верно Array
    instructionSteps    		 Инструкции для области контекста.
    Метки String Метка для области контекста.
    isPrimary Логический Указывает, является ли это основной областью контекста.
    InfoMessage

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

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

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

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

    Значение массива Тип Описание
    text String Определите текст, отображаемый в сообщении.
    visible Логический Определяет, отображается ли сообщение.
    Встроенный Логический Определяет способ отображения информационного сообщения.

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

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

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

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

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

    InstallAgent

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

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

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

    Значения массива Обязательный Тип Описание
    linkType Верно ПЕРЕЧИСЛЕНИЯ Определяет тип ссылки в виде одного из следующих значений:

    InstallAgentOnWindowsVirtualMachine
    InstallAgentOnWindowsNonAzure
    InstallAgentOnLinuxVirtualMachine
    InstallAgentOnLinuxNonAzure
    OpenSyslogSettings
    OpenCustomLogsSettings
    OpenWaf
    OpenAzureFirewall OpenMicrosoftAzureMonitoring
    OpenFrontDoors
    OpenCdnProfile
    AutomaticDeploymentCEF
    OpenAzureInformationProtection
    OpenAzureActivityLog
    OpenIotPricingModel
    OpenPolicyAssignment
    OpenAllAssignmentsBlade
    OpenCreateDataCollectionRule
    policyDefinitionGuid Значение true при использовании OpenPolicyAssignment linkType. String Для соединителей на основе политик определяет GUID встроенного определения политики.
    assignMode ПЕРЕЧИСЛЕНИЯ Для соединителей на основе политик определяет режим назначения в виде одного из следующих значений: Initiative. Policy
    dataCollectionRuleType ПЕРЕЧИСЛЕНИЯ Для соединителей на основе DCR определяет тип правила сбора данных: SecurityEvent, или ForwardEvent.

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

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

    Дополнительные примеры см. в 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