無碼連接器框架的資料連接器定義參考

若要使用 CCF) (Codeless Connector Framework 建立資料連接器，請將本文件作為 Microsoft Sentinel REST API for Data Connector Definitions 參考文件的補充。本參考文件具體擴充了以下章節：

  • 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 參數

名稱 描述
dataConnectorDefinitionName 資料連接器的定義必須是唯一的名稱，且與name請求主體中的參數相同。
resourceGroupName 資源群組名稱，不區分大小寫。
訂閱ID 目標訂閱的 ID。
工作區名稱 工作區 名稱 ，不是 ID。
正則表達式模式： ^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$
API 版本 用於此操作的 API 版本。

要求內文

使用 API 建立 CCF 資料連接器定義的請求體結構如下：

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

dataConnectorDefinition 具有以下屬性：

名稱 必要項目 類型 描述
類型 True 字串 Customizable 無論是 API 輪詢資料連接器或其他 Static 方式
屬性。connectorUiConfig True 巢狀 JSON
connectorUiConfig		 資料連接器的使用者介面設定屬性

設定你的連接器使用者介面

本節說明可用來自訂資料連接器頁面使用者介面的設定選項。

以下截圖展示了一個範例資料連接器頁面，並以對應使用者介面重要區域的數字標示。

範例資料連接器頁面截圖，標示為 1 到 9 的區塊。

以下每個用於設定使用者介面所需的元素 connectorUiConfig ，對應於 API 的 CustomizableConnectorUiConfig 部分。

欄位 必要項目 類型 描述 截圖 顯著區域 #
title 對 string 標題顯示於資料連接器頁面 1
id 字串 設定自訂連接器 ID 供內部使用
標誌 字串 圖片檔案的路徑（SVG 格式）。 若未設定值，則使用預設標誌。 2
出版人 對 string 連接器的提供者 3
描述Markdown True Markdown 中的字串 這是連結器的描述，並具備加入 markdown 語言以增強的功能。 4
範例查詢 True 巢狀 JSON
範例查詢		 讓客戶查詢如何找到事件日誌中的資料。
graphQueries True 巢狀 JSON
graphQueries		 查詢顯示過去兩週的資料擷取。

對所有資料連接器的資料型態提供一個查詢，或為每個資料型態提供不同的查詢。		 5
graphQueriesTableName 設定連接器插入資料的表格名稱。 此名稱可透過在 和 lastDataReceivedQuery 值中指定{{graphQueriesTableName}}佔位符graphQueries來使用。
資料類型 True 巢狀 JSON
資料類型		 列出所有連接器的資料型態，以及查詢每個資料型態最後一次事件的時間。 6
連接性標準 True 巢狀 JSON
連接性標準		 一個定義如何驗證連接器是否連接的物件。 7
可取得性 巢狀 JSON
可取得性		 一個定義連接器可用性狀態的物件。
權限 True 巢狀 JSON
權限		 介面中「 前置條件 」區塊顯示的資訊，列出啟用或停用連接器所需的權限。 8
instructionSteps（指令步驟） True 巢狀 JSON
指令		 說明如何安裝連接器的小工具，以及在 「說明」 標籤上顯示的可操作控制項。 9
isConnectivityCriteriasMatchSome 布林值 一個布林值，表示在 ConnectivityCriteria 項目之間是否使用 'OR' (SOME) 或 'AND'。

連接性標準

欄位 必要項目 類型 描述
類型 True 字串 以下兩種選項之一： HasDataConnectors – 此值最適合用於 API 輪詢資料連接器，如 CCF。 接頭被視為至少有一個主動連接點。

isConnectedQuery – 此值適用於其他類型的資料連接器。 當所提供的查詢回傳資料時，連接器即視為已連接。
值 當型別為 時為真 isConnectedQuery 字串 查詢資料是否在特定時間內被接收。 例如：CommonSecurityLog | where DeviceVendor == \"Vectra Networks\"\n| where DeviceProduct == \"X Series\"\n | summarize LastLogReceived = max(TimeGenerated)\n | project IsConnected = LastLogReceived > ago(7d)"

資料類型

陣列值 類型 描述
name 字串 對 的lastDataReceivedQuery有意義描述，包括對變 graphQueriesTableName 數的支持。

範例：{{graphQueriesTableName}}
最後資料接收查詢 字串 KQL 查詢會回傳一列，並表示最後一次接收資料的時間，若沒有結果則表示無資料。

範例：{{graphQueriesTableName}}\n | summarize Time = max(TimeGenerated)\n | where isnotempty(Time)

graphQueries

定義一個查詢，呈現過去兩週的資料攝取情況。

對所有資料連接器的資料型態提供一個查詢，或為每個資料型態提供不同的查詢。

陣列值 類型 描述
metricName 字串 為你的圖表取一個有意義的名稱。

範例：Total data received
傳說 字串 圖例右側的字串，包含變數參考。

範例：{{graphQueriesTableName}}
baseQuery 字串 查詢會篩選相關事件，包括變數參考。

範例： TableName_CL | where ProviderName == "myprovider" 或 {{graphQueriesTableName}}

可取得性

欄位 必要項目 類型 描述
status 整數 連接器的可用性狀態。
可用 = 1
特色旗 = 2
即將推出 = 3
內部 = 4
is預覽 布林值 一個布林值表示連接器是否處於預覽模式。

權限

陣列值 類型 描述
習俗 字串 描述資料連線所需的任何自訂權限，語法如下：
{
"name":字串,
"description":字串
}

範例：自訂值會在 Microsoft Sentinel Prerequisites 區塊以藍色資訊圖示顯示。 在 GitHub 範例中，這個值對應於 GitHub API 個人代幣金鑰這行：你需要存取 GitHub 個人代幣...
執照 ENUM 定義所需授權，為以下值之一：OfficeIRM，OfficeATP，Office365， MtpAadP1P2AatpMcasMdatp，IoT

範例：授權值在 Microsoft Sentinel 中顯示為：授權：Required Azure AD Premium P2
resourceProvider resourceProvider 說明你 Azure 資源的任何前置條件。

範例：resourceProvider 值在 Microsoft Sentinel Prerequisites 區塊中顯示為：
工作空間：需讀取與寫入權限。
鍵：工作空間需要對共享鍵的讀取權限。
房客 ENUM 值陣列
例如:

"tenant": [
"GlobalADmin",
"SecurityAdmin"
]
 定義所需的權限，為以下一個或多個值： "GlobalAdmin"， "SecurityAdmin"， "SecurityReader"， "InformationProtection"

範例：在 Microsoft Sentinel 中顯示租戶值為：租戶權限：需要Global Administrator或Security Administrator在工作空間的租戶上

重要事項

Microsoft 建議您使用權限最少的角色。 這有助於改善貴組織的安全性。 全域系統管理員是高度特殊權限角色，應僅在無法使用現有角色的緊急案例下使用。

resourceProvider

子陣列值 類型 描述
提供者 ENUM 描述資源提供者，值如下之一：
- Microsoft.OperationalInsights/workspaces
- Microsoft.OperationalInsights/solutions
- Microsoft.OperationalInsights/workspaces/datasources
- microsoft.aadiam/diagnosticSettings
- Microsoft.OperationalInsights/workspaces/sharedKeys
- Microsoft.Authorization/policyAssignments
providerDisplayName 字串 在 Prerequisites 下，當 RequiredPermissions 在連接器頁面驗證時，會顯示紅色「x」或綠色勾選標記。 舉例來說， "Workspace"
權限顯示文字 字串 顯示閱讀、寫入或讀寫權限的文字，這些權限應對應於 requiredPermissions 中設定的值
必要權限 {
"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})"
}

instructionSteps（指令步驟）

本節提供參數，定義 Microsoft Sentinel 資料連接器頁面上出現的指令集合，結構如下：

"instructionSteps": [
    {
        "title": "",
        "description": "",
        "instructions": [
        {
            "type": "",
            "parameters": {}
        }
        ],
        "innerSteps": {}
    }
]
陣列性質 必要項目 類型 描述
title 字串 為你的指示定義了一個標題。
描述 字串 定義了對你指示有意義的描述。
內層階梯 陣列 定義一個內部指令步驟陣列。
指令 True 指令陣列 定義特定參數類型的指令陣列。

指令

顯示一組指令，包含各種參數，並能將更多指令步驟組成群組。 這裡定義的參數對應

類型 陣列特性 描述
OAuthForm OAuthForm 與 OAuth 連結
文字框 文字框 這與 ConnectionToggleButton配對。 有四種可用類型：
  • password
  • text
  • number
  • email
    		•
    連接切換按鈕 連接切換按鈕 根據透過佔位參數提供的連線資訊，觸發 DCR 的部署。 支援以下參數：
  • name ：強制
  • disabled
  • isPrimary
  • connectLabel
  • disconnectLabel
    		•
    可複製標籤 可複製標籤 顯示一個文字欄位，末尾有個複製按鈕。 當按鈕被選中時，欄位的數值會被複製。
    Dropdown Dropdown 顯示一個下拉選單，供使用者選擇。
    折扣 折扣 顯示一段以 Markdown 格式化的文字。
    DataConnectorsGrid DataConnectorsGrid 顯示一個資料連接器的網格。
    情境面板 情境面板 顯示一個情境資訊窗格。
    資訊訊息 資訊訊息 定義內嵌資訊訊息。
    InstructionStepsGroup 指令步驟小組 InstructionStepsGroup 指令步驟小組 在獨立的指令區塊顯示一組指令，可選擇展開或摺疊。
    安裝代理 安裝代理 顯示 Azure 其他部分的連結，以完成各種安裝需求。
    OAuthForm

    此元件要求資料連接器範本的屬性中必須存在auth該OAuth2型別。

    "instructions": [
{
  "type": "OAuthForm",
  "parameters": {
    "clientIdLabel": "Client ID",
    "clientSecretLabel": "Client Secret",
    "connectButtonLabel": "Connect",
    "disconnectButtonLabel": "Disconnect"
  }          
}
]
    文字框

    以下是此類 Textbox 類型的一些範例。 這些範例對應於無碼連接器框架資料連接器參考中範例章節所用auth參數。 對於這四種類型，各自有 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"
  }
}
]
    連接切換按鈕
    "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"
}
    陣列值 必要項目 類型 描述
    fillWith ENUM 用來填充佔位符的環境變數陣列。 用逗號分隔多個佔位符。 例如：{0},{1}

    支援值： workspaceId， workspaceName， primaryKey， MicrosoftAwsAccount， subscriptionId
    唱片公司 True 字串 定義文字框上方標籤的文字。
    value True 字串 定義文字框中要呈現的值，支援佔位符。
    rows Rows 定義使用者介面區域的列數。 預設設定為 1。
    寬標籤 布林值 決定長弦的寬廣標籤。 預設情況下，設為 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"
}
    欄位 必要項目 類型 描述
    唱片公司 True 字串 定義下拉選單上方標籤的文字。
    name True 字串 定義了下拉選單的獨特名稱。 這會用於輪詢設定。
    options True 陣列 定義下拉選單的選項清單。
    佔位符 字串 定義下拉選單的佔位文字。
    isMultiSelect 布林值 決定是否能選擇多個選項。 預設情況下，設為 false。
    必修 布林值 若 true，則下拉選單必須被填滿。
    defaultAllSelected 布林值 若 true，則預設所有選項皆被選中。
    折扣
    {
  "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"
    ]
  }
}
    欄位 必要項目 類型 描述
    製圖 True 陣列 定義了格子中欄位的映射。
    菜單項目 陣列 定義格子的選單項目。
    情境面板
    {
  "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
              }
            }
          }
        ]
      }
    ]
  }
}
    欄位 必要項目 類型 描述
    title True 字串 上下文面板的標題。
    字幕 True 字串 上下文面板的副標題。
    contextPaneType True 字串 上下文面板的類型。
    instructionSteps（指令步驟） True 陣列
    instructionSteps（指令步驟）    		 上下文面板的指示步驟。
    唱片公司 字串 上下文面板的標籤。
    是初級 布林值 顯示這是否為主要上下文窗格。
    資訊訊息

    這裡有一個內嵌資訊訊息的範例：

    內嵌資訊訊息的截圖。

    相較之下，以下圖片顯示的資訊訊息並非內嵌：

    一張資訊訊息的截圖，但不是內嵌的。

    陣列值 類型 描述
    text 字串 定義訊息中要顯示的文字。
    可見 布林值 判斷訊息是否會顯示。
    直列式 布林值 決定資訊訊息的顯示方式。

    - true： (推薦) 顯示說明書中嵌入的資訊訊息。
    - false：會加上藍色背景。
    InstructionStepsGroup 指令步驟小組

    這裡有一個可展開指令組的範例：

    一個可擴充的額外指令群組截圖。

    陣列值 必要項目 類型 描述
    title True 字串 定義了指令步驟的標題。
    描述 字串 可選的描述文字。
    可以崩潰所有區段 布林值 判斷該段落是否為可折疊手風琴。
    noFxPadding 布林值 若 true，則減少高度填充以節省空間。
    擴充版 布林值 如果 true，預設顯示為擴展。

    詳細範例請參見 Windows DNS 連接器的設定 JSON。

    安裝代理

    有些 InstallAgent 類型會以按鈕形式出現，有些則以連結形式出現。 以下是兩者的範例：

    連結的截圖作為按鈕加入。

    新增的連結截圖為內嵌文字。

    陣列值 必要項目 類型 描述
    連結類型 True ENUM 決定連結類型，以下值之一：

    InstallAgentOnWindowsVirtualMachine
    InstallAgentOnWindowsNonAzure
    InstallAgentOnLinuxVirtualMachine
    InstallAgentOnLinuxNonAzure
    OpenSyslogSettings
    OpenCustomLogsSettings
    OpenWaf
    OpenAzureFirewall OpenMicrosoftAzureMonitoring
    OpenFrontDoors
    OpenCdnProfile
    AutomaticDeploymentCEF
    OpenAzureInformationProtection
    OpenAzureActivityLog
    OpenIotPricingModel
    OpenPolicyAssignment
    OpenAllAssignmentsBlade
    OpenCreateDataCollectionRule
    policyDefinitionGuid 使用 OpenPolicyAssignment linkType 時是真的。 字串 對於基於政策的連接器，定義了內建政策定義的 GUID。
    assignMode ENUM 對於基於策略的連接器，定義指派模式為以下其中一個值： Initiative， Policy
    dataCollectionRuleType ENUM 對於基於 DCR 的連接器，定義了資料收集規則類型 SecurityEvent為 、 或 ForwardEvent。

    資料連接器定義範例

    以下範例整合了本文中定義的一些元件，作為 JSON 主體格式，供 Create 或 Update 資料連接器定義 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