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

若要使用无代码连接器框架 (CCF) 创建数据连接器，请使用本文档作为Microsoft Sentinel REST API for Data Connector 定义参考文档的补充。具体而言，此参考文档扩展了以下部分：

• 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

dataTypes

graphQueries

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

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

availability

permissions

resourceProvider

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

instructionSteps

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

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

指示

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

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。

有关其他 CCF 数据连接器的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"
                  }
                }
              ]
            }
          ]
        }
    }
}