無程式代碼連接器平臺的數據連接器定義參考

文章
10/16/2024

若要使用無程式代碼連接器平臺（CCP）建立數據連接器，請使用本檔作為數據連接器定義參考檔的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 參數

名稱	描述
dataConnectorDefinitionName	數據連接器定義必須是唯一的名稱，而且與`name`要求主體中的參數相同。
resourceGroupName	資源群組的名稱，不區分大小寫。
subscriptionId	目標訂用帳戶的標識碼。
workspaceName	工作區的名稱，而非標識符。 Regex 模式： `^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$`
api-version	用於此作業的 API 版本。

要求本文

使用 API 建立 CCP 資料連接器定義的要求本文具有下列結構：

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

dataConnectorDefinition 具有下列屬性：

名稱	必要	類型	描述
種類	True	String	`Customizable` 若為 API 輪詢資料連接器，則 `Static` 為，否則為
性能。connectorUiConfig	True	巢狀 JSON connectorUiConfig	數據連接器的UI組態屬性

設定連接器的使用者介面

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

下列螢幕快照顯示範例數據連接器頁面，其中已醒目提示與使用者介面顯著區域對應的數位。

範例數據連接器頁面的螢幕快照，其中區段標示為 1 到 9。

設定使用者介面時所需區段的每個元素 connectorUiConfig ，都會對應至 API 的 CustomizableConnectorUiConfig 部分。

欄位	必要	類型	描述	值得注意的區域螢幕快照#
title	True	字串	顯示在數據連接器頁面中的標題	1
id		字串	設定內部使用量的自定義連接器標識碼
商標		字串	SVG 格式的影像檔路徑。如果未設定任何值，則會使用預設標誌。	2
publisher	True	字串	連接器的提供者	3
descriptionMarkdown	True	Markdown 中的字串	連接器的描述，能夠新增 Markdown 語言加以強化。	4
sampleQueries	True	巢狀 JSON sampleQueries	查詢客戶，以瞭解如何在事件記錄檔中尋找數據。
graphQueries	True	巢狀 JSON graphQueries	過去兩周內呈現數據擷取的查詢。針對所有資料連線器的資料類型提供一個查詢，或針對每個資料類型提供不同的查詢。	5
graphQueriesTableName		設定連接器插入數據的數據表名稱。這個名稱可以藉由在 `{{graphQueriesTableName}}` 和 `lastDataReceivedQuery` 值中`graphQueries`指定佔位元，在其他查詢中使用。
dataTypes	True	巢狀 JSON dataTypes	連接器的所有資料類型清單，以及擷取每個資料類型最後一個事件時間的查詢。	6
connectivityCriteria	True	巢狀 JSON connectivityCriteria	對象，定義如何確認連接器是否已連接。	7
permissions	True	巢狀 JSON permissions	UI 的必要條件區段底下顯示的資訊，其中列出啟用或停用連接器所需的許可權。	8
instructionSteps	True	巢狀 JSON 指示	小工具元件的數位，說明如何安裝連接器，以及顯示在 [指示] 索引標籤上的可操作控制件。	9

connectivityCriteria

欄位	必要	類型	描述
類型	True	String	下列兩個選項之一： `HasDataConnectors` 這個值最適合 API 輪詢數據連接器，例如 CCP。連接器會被視為至少與一個作用中連線。 `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

陣列值	類型	Description
name	String	有意義的`lastDataReceivedQuery`描述，包括對變數的支援 `graphQueriesTableName` 。範例: `{{graphQueriesTableName}}`
lastDataReceivedQuery	String	傳回一個數據列的 KQL 查詢，指出上次收到數據的時間，如果沒有結果，則不會有任何數據。範例: `{{graphQueriesTableName}}\n \| summarize Time = max(TimeGenerated)\n \| where isnotempty(Time)`

graphQueries

定義過去兩周內呈現數據擷取的查詢。

針對所有資料連線器的資料類型提供一個查詢，或針對每個資料類型提供不同的查詢。

陣列值	類型	描述
metricName	String	有意義的圖表名稱。範例: `Total data received`
legend	String	出現在圖表右邊圖例中的字串，包括變數參考。範例: `{{graphQueriesTableName}}`
baseQuery	String	篩選相關事件的查詢，包括變數參考。範例： `TableName_CL \| where ProviderName == "myprovider"` 或 `{{graphQueriesTableName}}`

權限

陣列值	類型	描述
customs	String	以下列語法描述資料連線所需的任何自訂權限： `{` `"name":`string`,` `"description":`string `}` 範例：customs 值會顯示在 Microsoft Sentinel 的 [必要條件] 區段中，附有藍色資訊圖示。在 GitHub 範例中，此值與 GitHub API 個人令牌密鑰行相互關聯：您需要存取 GitHub 個人令牌...
授權	ENUM	將必要授權定義為下列其中一個值：`OfficeIRMOfficeATPOffice365AadP1P2McasAatpMdatpMtpIoT` 範例：licenses 值會在 Microsoft Sentinel 中顯示為：授權：必要的 Azure AD Premium P2
resourceProvider	resourceProvider	描述 Azure 資源的任何必要條件。範例：resourceProvider 值會在 Microsoft Sentinel 的 [必要條件] 區段中顯示為：工作區：需要讀取和寫入權限。金鑰：需要工作區共用金鑰的讀取權限。
tenant	ENUM 值的陣列範例： `"tenant": [` `"GlobalADmin",` `"SecurityAdmin"` `]`	將必要權限定義為下列一或多個值：`"GlobalAdmin"`、`"SecurityAdmin""SecurityReader""InformationProtection"` 範例：Microsoft Sentinel 中的 tenant 值會顯示為：租用戶權限：需要工作區租用戶上的 `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	String	必要條件下的清單專案，會在連接器頁面中驗證 requiredPermissions 時顯示紅色的「x」或綠色複選標記。例 `"Workspace"`
permissionsDisplayText	String	應與 requiredPermissions 中設定的值相對應的讀取、寫入或讀取和寫入權限的顯示文字
requiredPermissions	`{` `"action":`布林值`,` `"delete":`布林值`,` `"read":`布林值`,` `"write":`Boolean `}`	說明連接器所需的最低權限。
範圍 (scope)	ENUM	將資料連線器的範圍描述為下列其中一個值：`"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": {}
    }
]

陣列屬性	必要	類型	描述
title		String	定義指示的標題。
description		String	為您的指示定義有意義的描述。
innerSteps		陣列	定義內部指示步驟的陣列。
指示	True	指令的陣列	定義特定參數類型的指令陣列。

指示

顯示一組指令，其中包含各種參數，以及在群組中巢狀更多 instructionSteps 的能力。這裡定義的參數對應

類型	陣列屬性	描述
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"
}

陣列值	必要	類型	描述
fillWith		ENUM	用來填入預留位置的環境變數陣列。以逗號分隔多個預留位置。例如：`{0},{1}` 支援的值：`workspaceIdworkspaceNameprimaryKeyMicrosoftAwsAccountsubscriptionId`
label	True	String	定義文字方塊上方標籤的文字。
value	True	String	定義文字方塊中要呈現的值，支援預留位置。
rows		資料列	定義使用者介面區域中的資料列。根據預設，設定為 1。
wideLabel		布林值	決定長字串的寬標籤。根據預設，設定為 `false`。

InfoMessage

以下是內嵌資訊訊息的範例：

內嵌資訊訊息的螢幕擷取畫面。

相反地，下圖顯示非內嵌的資訊訊息：

非內嵌資訊訊息的螢幕快照。

陣列值	類型	描述
text	String	定義要顯示在訊息中的文字。
visible	布林值	決定是否顯示訊息。
inline	布林值	決定如何顯示資訊訊息。 - `true`：(建議) 顯示內嵌在指令中的資訊訊息。 - `false`：新增藍色背景。

InstructionStepsGroup

以下是可展開指令群組的範例：

可展開的額外指令群組的螢幕擷取畫面。

陣列值	必要	類型	描述
title	True	String	定義指示步驟的標題。
description		String	選擇性的描述性文字。
canCollapseAllSections		布林值	判斷區段是否為可展開的摺疊式功能表。
noFxPadding		布林值	若 `true`，則會減少高度填補以節省空間。
expanded		布林值	若 `true`，則預設會顯示為展開。

如需詳細範例，請參閱 Windows DNS 連接器的設定 JSON。

InstallAgent

某些 InstallAgent 類型會顯示為按鈕，其他類型則會顯示為連結。以下是兩者的範例：

連結新增為內嵌文字的螢幕擷取畫面。

陣列值	必要	類型	描述
linkType	True	ENUM	決定連結類型，作為下列其中一個值： `InstallAgentOnWindowsVirtualMachine` `InstallAgentOnWindowsNonAzure` `InstallAgentOnLinuxVirtualMachine` `InstallAgentOnLinuxNonAzure` `OpenSyslogSettings` `OpenCustomLogsSettings` `OpenWaf` `OpenAzureFirewall` `OpenMicrosoftAzureMonitoring` `OpenFrontDoors` `OpenCdnProfile` `AutomaticDeploymentCEF` `OpenAzureInformationProtection` `OpenAzureActivityLog` `OpenIotPricingModel` `OpenPolicyAssignment` `OpenAllAssignmentsBlade` `OpenCreateDataCollectionRule`
policyDefinitionGuid	如果使用 `OpenPolicyAssignment` linkType，則為T.True。	String	針對原則型連接器，定義內建原則定義的 GUID。
assignMode		ENUM	針對原則型連接器，將指派模式定義為下列其中一個值：`Initiative`、`Policy`
dataCollectionRuleType		ENUM	針對 DCR 型連接器，將資料收集規則類型的 `SecurityEvent`類型定義為或 `ForwardEvent`。

範例數據連接器定義

下列範例將本文中定義的一些元件結合為 JSON 主體格式，以搭配建立或更新數據連接器定義 API 使用。

如需檢閱其他 CCP 數據連接器的connectorUiConfig更多範例。即使是使用舊版 CCP 的連接器也有有效的 UI 建立範例。

{
    "kind": "Customizable",
    "properties": {
        "connectorUiConfig": {
          "title": "Example CCP 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"
                  }
                }
              ]
            }
          ]
        }
    }
}

分享方式：