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

若要使用无代码连接器框架（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 参数

请求主体

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

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

dataConnectorDefinition 具有以下属性：

配置连接器的用户界面

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

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

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

connectivityCriteria

数据类型

graphQueries 查询

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

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

可用性

权限

资源提供者

sampleQueries 查询

配置其他链接选项

若要使用 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": {}
    }
]

指示

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

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

下拉列表

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

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

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

InfoMessage

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

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

InstructionStepsGroup

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

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

InstallAgent

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

示例数据连接器定义

以下示例将本文中定义的一些组件组合为 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"
                  }
                }
              ]
            }
          ]
        }
    }
}