无代码连接器框架的数据连接器定义参考

若要使用无代码连接器框架（CCF）创建数据连接器，请使用本文档作为数据 连接器定义参考文档的 Microsoft Sentinel REST API 的补充。具体来说，此参考文档将展开以下部分：

• connectorUiConfig - 定义Microsoft Sentinel 中数据连接器页上显示的视觉元素和文本。

有关详细信息，请参阅 创建无代码连接器。

数据连接器定义 - 创建或更新

参考 REST API 文档中的“创建或更新”作，查找最新的稳定或预览版 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 参数

名称	DESCRIPTION
dataConnectorDefinitionName	数据连接器定义必须是唯一的名称，并且与name请求正文中的参数相同。
resourceGroupName	资源组的名称，不区分大小写。
subscriptionId	目标订阅的 ID。
workspaceName	工作区的名称，而不是 ID。 正则表达式模式：^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$
api-version	要用于此操作的 API 版本。

请求主体

使用 API 创建 CCF 数据连接器定义的请求正文具有以下结构：

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

dataConnectorDefinition 具有以下属性：

名称	必选	类型	DESCRIPTION
种类	真 实	字符串	Customizable用于 API 轮询数据连接器或其他Static
性能。connectorUiConfig	真 实	嵌套的 JSON connectorUiConfig	数据连接器的 UI 配置属性

配置连接器的用户界面

本部分介绍可用于自定义数据连接器页用户界面的配置选项。

以下屏幕截图显示了一个示例数据连接器页，其中突出显示了与用户界面的显著区域相对应的数字。

配置用户界面所需的以下每个元素 connectorUiConfig 对应于 API 的 CustomizableConnectorUiConfig 部分。

领域	必选	类型	DESCRIPTION	值得注意的屏幕截图区域#
标题	真 实	字符串	数据连接器页中显示的标题	1
id		字符串	为内部使用情况设置自定义连接器 ID
商标		字符串	采用 SVG 格式的图像文件的路径。 如果未配置任何值，则使用默认徽标。	2
发行人	真 实	字符串	连接器的提供程序	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 权限	UI 的 “先决条件 ”部分下显示的信息，其中列出了启用或禁用连接器所需的权限。	8
instructionSteps	真 实	嵌套的 JSON 指示	介绍如何安装连接器的小组件部件数组，以及“ 说明 ”选项卡上显示的可作控件。	9

connectivityCriteria

领域	必选	类型	DESCRIPTION
类型	真 实	字符串	以下两个选项之一： 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)"

数据类型

数组值	类型	DESCRIPTION
名字	字符串	一lastDataReceivedQuery个有意义的说明，包括对变量的支持 graphQueriesTableName 。 示例：{{graphQueriesTableName}}
lastDataReceivedQuery	字符串	返回一行的 KQL 查询，指示上次收到数据的时间，如果没有结果，则不显示任何数据。 示例：{{graphQueriesTableName}}\n | summarize Time = max(TimeGenerated)\n | where isnotempty(Time)

graphQueries 查询

定义一个查询，该查询显示过去两周的数据引入。

为所有数据连接器的数据类型提供一个查询，或者为每个数据类型提供不同的查询。

数组值	类型	DESCRIPTION
metricName	字符串	图形的有意义的名称。 示例：Total data received
传说	字符串	显示在图表右侧图例中的字符串，包括变量引用。 示例：{{graphQueriesTableName}}
baseQuery	字符串	筛选相关事件的查询，包括变量引用。 示例： TableName_CL | where ProviderName == "myprovider" 或 {{graphQueriesTableName}}

权限

数组值	类型	DESCRIPTION
海关	字符串	使用以下语法描述数据连接所需的任何自定义权限： { "name":字符串, "description":字符串 } 示例： 海关 值以蓝色信息图标显示在Microsoft Sentinel 先决条件 部分。 在 GitHub 示例中，此值与 行 GitHub API 个人令牌密钥相关联：需要访问 GitHub 个人令牌...
许可证	ENUM	将所需的许可证定义为以下值之一：OfficeIRM、、OfficeATP、、Office365AadP1P2Mcas、Aatp、Mdatp、、 MtpIoT 示例： 许可证 值以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 建议使用权限最少的角色。 这有助于提高组织的安全性。 全局管理员是一个高度特权的角色，应仅限于无法使用现有角色的紧急情况。

资源提供者

子数组值	类型	DESCRIPTION
供应商	ENUM	描述资源提供程序，具有以下值之一： - Microsoft.OperationalInsights/workspaces - Microsoft.OperationalInsights/solutions - Microsoft.OperationalInsights/workspaces/datasources - microsoft.aadiam/diagnosticSettings - Microsoft.OperationalInsights/workspaces/sharedKeys - Microsoft.Authorization/policyAssignments
providerDisplayName	字符串	先决条件下的列表项，在连接器页中验证 requiredPermissions 时显示红色的“x”或绿色复选标记。 例 "Workspace"
permissionsDisplayText	字符串	显示应与 requiredPermissions 中配置的值对应的读取、写入或读取和写入权限的文本
requiredPermissions	{ "action":布尔, "delete":布尔, "read":布尔, "write":布尔 }	描述连接器所需的最低权限。
作用域	ENUM	将数据连接器的范围描述为以下值之一： "Subscription""ResourceGroup""Workspace"

sampleQueries 查询

数组值	类型	DESCRIPTION
说明	字符串	示例查询的有意义说明。 示例：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})"
}

instruction步骤

本部分提供的参数用于定义Microsoft Sentinel 中数据连接器页上显示的指令集，并具有以下结构：

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

Array 属性	必选	类型	DESCRIPTION
标题		字符串	为说明定义标题。
说明		字符串	为说明定义有意义的说明。
innerSteps		数组	定义内部指令步骤的数组。
指示	真 实	指令数组	定义特定参数类型的指令数组。

指示

显示一组指令，其中包含各种参数，并能够在组中嵌套更多 instructionSteps。 此处定义的参数对应

类型	Array 属性	DESCRIPTION
OAuthForm	OAuthForm	使用 OAuth 连接
文本框	文本框	此对与 ConnectionToggleButton. 有 4 种可用类型： password text number email
ConnectionToggleButton	ConnectionToggleButton	根据通过占位符参数提供的连接信息触发 DCR 的部署。 支持以下参数： name ：命令的 disabled isPrimary connectLabel disconnectLabel
CopyableLabel	CopyableLabel	显示末尾带有复制按钮的文本字段。 选择按钮后，将复制字段的值。
InfoMessage	InfoMessage	定义内联信息消息。
InstructionStepsGroup	InstructionStepsGroup	在单独的说明部分中显示一组指令（可选展开或可折叠）。
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"
}

数组值	必选	类型	DESCRIPTION
fillWith		ENUM	用于填充占位符的环境变量数组。 用逗号分隔多个占位符。 例如：{0},{1} 支持的值：workspaceId、、workspaceName、primaryKeyMicrosoftAwsAccount、subscriptionId
标签	真 实	字符串	定义文本框上方标签的文本。
价值	真 实	字符串	定义要在文本框中显示的值，支持占位符。
行		行	定义用户界面区域中的行。 默认情况下，设置为 1。
wideLabel		布尔型	确定长字符串的宽标签。 默认情况下，设置为 false.

InfoMessage

下面是内联信息消息的示例：

相比之下，下图显示了非内联信息消息：

数组值	类型	DESCRIPTION
文本	字符串	定义要在消息中显示的文本。
可见	布尔型	确定是否显示消息。
内嵌	布尔型	确定信息消息的显示方式。 - true：（建议） 显示指令中嵌入的信息消息。 - false：添加蓝色背景。

InstructionStepsGroup

下面是可扩展指令组的示例：

数组值	必选	类型	DESCRIPTION
标题	真 实	字符串	定义说明步骤的标题。
说明		字符串	可选描述性文本。
canCollapseAllSections		布尔型	确定该节是否为可折叠可折叠的可折叠手风琴。
noFxPadding		布尔型	如果 true减少高度填充以节省空间。
扩大		布尔型	如果 true显示，则默认显示为展开。

有关详细示例，请参阅 Windows DNS 连接器的配置 JSON。

InstallAgent

某些 InstallAgent 类型显示为按钮，其他类型显示为链接。 下面是两者的示例：

数组值	必选	类型	DESCRIPTION
linkType	真 实	ENUM	确定链接类型，作为以下值之一： InstallAgentOnWindowsVirtualMachine InstallAgentOnWindowsNonAzure InstallAgentOnLinuxVirtualMachine InstallAgentOnLinuxNonAzure OpenSyslogSettings OpenCustomLogsSettings OpenWaf OpenAzureFirewall OpenMicrosoftAzureMonitoring OpenFrontDoors OpenCdnProfile AutomaticDeploymentCEF OpenAzureInformationProtection OpenAzureActivityLog OpenIotPricingModel OpenPolicyAssignment OpenAllAssignmentsBlade OpenCreateDataCollectionRule
policyDefinitionGuid	使用 OpenPolicyAssignment linkType 时为 True。	字符串	对于基于策略的连接器，定义内置策略定义的 GUID。
assignMode		ENUM	对于基于策略的连接器，将分配模式定义为以下值之一： InitiativePolicy
dataCollectionRuleType		ENUM	对于基于 DCR 的连接器，请将数据收集规则类型的类型定义为 SecurityEvent或 ForwardEvent。

示例数据连接器定义

以下示例将本文中定义的一些组件组合为 JSON 正文格式，以用于创建或更新数据连接器定义 API。

有关查看connectorUiConfig的更多示例。 即使是使用旧 CCF 的连接器也有有效的 UI 创建示例。

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