コードレスコネクタプラットフォームのデータコネクタ定義リファレンス

[アーティクル]
07/03/2024

コードレスコネクタプラットフォーム (CCP) を使用してデータコネクタを作成するには、このドキュメントをデータコネクタ定義用の Microsoft Sentinel REST API の補足として使用しますリファレンスドキュメント。具体的には、このリファレンスドキュメントは次のセクションで展開されています。

connectorUiConfig - Microsoft Sentinel のデータコネクタページに表示されるビジュアル要素とテキストを定義します。

詳細については、「コードレスコネクタの作成」を参照してください。

データコネクタの定義 - 作成または更新

REST API ドキュメントの作成または更新操作を参照して、最新の安定した API バージョンまたはプレビュー API バージョンを見つけます。 etag値が必要なのは、update操作だけです。

PUT メソッド

https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.OperationalInsights/workspaces/{{workspaceName}}/providers/Microsoft.SecurityInsights/dataConnectorDefinitions/{{dataConnectorDefinitionName}}?api-version={{apiVersion}}

URI パラメーター

最新の API バージョンの詳細については、「 Data コネクタ定義 - URI パラメーターの作成または更新」を参照してください。

名前	説明
dataConnectorDefinitionName	データコネクタ定義は一意の名前である必要があり、要求本文の`name` パラメーターと同じです。
resourceGroupName	リソースグループの名前。大文字と小文字は区別されません。
subscriptionId	ターゲットサブスクリプションの ID。
workspaceName	ID ではなく、ワークスペースの名。正規表現パターン: `^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$`
api-version	この操作に使用する API バージョン。

要求本文

API を使用して CCP データコネクタ定義を作成するための要求本文には、次の構造があります。

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

dataConnectorDefinition には次のプロパティがあります。

名前	Required	タイプ	説明設定
Kind	True	String	`Customizable`API ポーリングデータコネクタの場合は、それ以外の場合は `Static`
properties.connectorUiConfig	True	入れ子の JSON connectorUiConfig	データコネクタの UI 構成プロパティ

コネクタのユーザーインターフェイスを構成する

このセクションでは、データコネクタページのユーザーインターフェイスをカスタマイズするために使用できる構成オプションについて説明します。

次のスクリーンショットは、ユーザーインターフェイスの注目すべき領域に対応する数値で強調表示されたサンプルデータコネクタページを示しています。

セクションが 1 から 9 のサンプルデータコネクタページのスクリーンショット。

ユーザーインターフェイスを構成するために必要な connectorUiConfig セクションの次の各要素は、API の CustomizableConnectorUiConfig 部分に対応します。

フィールド	必須	タイプ	説明	注目すべき領域のスクリーンショット#
title	True	string	データコネクタページに表示されるタイトル	1
id		string	内部使用のカスタムコネクタ ID を設定します
ロゴ		string	SVG 形式のイメージファイルへのパス。値が構成されていない場合は、既定のロゴが使用されます。	2
publisher	True	string	コネクタのプロバイダー	3
descriptionMarkdown	True	markdown の文字列	マークダウン言語を追加して強化する機能があるコネクタの説明。	4
sampleQueries	True	入れ子の JSON sampleQueries	顧客がイベントログ内のデータを検索する方法を理解するためのクエリ。
graphQueries	True	入れ子の JSON graphQueries	過去 2 週間のデータインジェストを示すクエリ。すべてのデータコネクタのデータ型に対して 1 つのクエリを指定するか、データ型ごとに異なるクエリを指定します。	5
graphQueriesTableName		コネクタがデータを挿入するテーブルの名前を設定します。この名前は、`graphQueries`値と`lastDataReceivedQuery`値`{{graphQueriesTableName}}`プレースホルダーを指定することで、他のクエリで使用できます。
dataTypes	True	入れ子の JSON dataTypes	コネクタのすべてのデータ型のリストと、各データ型の最後のイベントの時刻を取り込むためのクエリ。	6
connectivityCriteria	True	入れ子の JSON connectivityCriteria	コネクタが接続されているかどうかを確認する方法を定義するオブジェクト。	7
アクセス許可	True	入れ子の JSON アクセス許可	UI の Prerequisites セクションに表示される情報。コネクタを有効または無効にするために必要なアクセス許可が一覧表示されます。	8
instructionSteps	True	入れ子の JSON instructions	コネクタのインストール方法を説明するウィジェットパーツの配列と、 Instructions タブに表示されるアクション可能なコントロール。	9

connectivityCriteria

フィールド	必須	タイプ	説明
Type	True	String	次の 2 つのオプションのいずれか: `HasDataConnectors` – この値は、CCP などの API ポーリングデータコネクタに最適です。コネクタは、少なくとも 1 つのアクティブな接続で接続されていると見なされます。 `isConnectedQuery` – この値は、他の種類のデータコネクタに最適です。指定されたクエリがデータを返すと、コネクタは接続されていると見なされます。
Value	型が次の場合は 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

配列の値	種類	説明
name	String	`graphQueriesTableName`変数のサポートを含む、`lastDataReceivedQuery`のわかりやすい説明。例: `{{graphQueriesTableName}}`
lastDataReceivedQuery	String	1 つの行を返し、最後にデータを受信したことを示す KQL クエリ。結果がない場合はデータがありません。例: `{{graphQueriesTableName}}\n \| summarize Time = max(TimeGenerated)\n \| where isnotempty(Time)`

graphQueries

過去 2 週間のデータインジェストを示すクエリを定義します。

すべてのデータコネクタのデータ型に対して 1 つのクエリを指定するか、データ型ごとに異なるクエリを指定します。

配列の値	種類	説明
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	次のいずれかの値で必要なライセンスを定義します。`OfficeIRM`、`OfficeATP`、`Office365`、`AadP1P2`、`Mcas`、`Aatp`、`Mdatp`、`Mtp`、`IoT`。例: ライセンスの値は、Microsoft Sentinel で次のように表示されます:ライセンス: Azure AD Premium P2 が必要です
resourceProvider	resourceProvider	Azure リソースの前提条件について説明します。例: resourceProvider の値は、Microsoft Sentinel の [前提条件] セクションに次のように表示されます。ワークスペース: 読み取りおよび書き込みのアクセス許可が必要です。キー: ワークスペースの共有キーに対する読み取りアクセス許可が必要です。
tenant	ENUM 値の配列例: `"tenant": [` `"GlobalADmin",` `"SecurityAdmin"` `]`	次の 1 つ以上の値で必要なアクセス許可を定義します。`"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" または緑のチェックマークを表示する Prerequisites の下のリストアイテム。たとえば、`"Workspace"` です。
permissionsDisplayText	String	requiredPermissions で構成されている値に対応する "読み取り"、"書き込み"、または "読み取りと書き込み" アクセス許可のテキストを表示します
requiredPermissions	`{` `"action":`Boolean`,` `"delete":`Boolean`,` `"read":`Boolean`,` `"write":`Boolean `}`	コネクタに必要な最小限のアクセス許可を記述します。
スコープ (scope)	ENUM	次のいずれかの値でデータコネクタのスコープについて説明します。`"Subscription"`、`"ResourceGroup"`、`"Workspace"`

sampleQueries

配列の値	種類	説明
description	String	サンプルクエリのわかりやすい説明。例: `Top 10 vulnerabilities detected`
query	String	データ型のデータをフェッチするために使用されるサンプルクエリ。例: `{{graphQueriesTableName}}\n \| sort by TimeGenerated\n \| take 10`

その他のリンクオプションを構成する

マークダウンを使用してインラインリンクを定義するには、次の例を使用してください。

{
   "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		Array	内部手順の配列を定義します。
instructions	True	手順の配列	特定のパラメーター型の手順の配列を定義します。

instructions

さまざまなパラメーターと、より多くの命令ステップをグループに入れ子にする機能を持つ命令のグループを表示します。ここで定義されているパラメーターは対応します

Type	配列のプロパティ	説明
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

このコンポーネントでは、データコネクタテンプレートのauth プロパティにOAuth2型が存在する必要があります。

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

テキストボックス

Textbox型の例をいくつか次に示します。これらの例は、コードレスコネクタプラットフォームの Data コネクタリファレンス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}` サポートされる値: `workspaceId`、`workspaceName`、`primaryKey`、`MicrosoftAwsAccount`、`subscriptionId`
label	True	String	テキストボックスの上にあるラベルのテキストを定義します。
value	True	String	テキストボックスに表示する値を定義します。プレースホルダーをサポートします。
rows		行	ユーザーインターフェイス領域内の行を定義します。既定では、1 に設定されます。
wideLabel		Boolean	長い文字列のワイドなラベルを決定します。既定では、`false` に設定されます。

InfoMessage

インライン情報メッセージの例を次に示します。

インライン情報メッセージのスクリーンショット。

これに対し、次の図はインラインではない情報メッセージを示しています。

インラインではない情報メッセージのスクリーンショット。

配列の値	種類	説明
text	String	メッセージに表示するテキストを定義します。
visible	ブール値	メッセージを表示するかどうかを決定します。
inline	ブール値	情報メッセージの表示方法を決定します。 - `true`: (推奨) 手順に埋め込まれた情報メッセージを表示します。 - `false`:青い背景を追加します。

InstructionStepsGroup

展開可能な手順グループの例を次に示します。

拡張可能な追加の命令グループのスクリーンショット。

配列の値	必須	タイプ	説明
title	True	String	手順のタイトルを定義します。
説明		String	省略可能な説明テキスト。
canCollapseAllSections		Boolean	セクションが折りたたみ可能なアコーディオンかどうかを判断します。
noFxPadding		Boolean	`true` の場合、縦方向のパディングを減らしてスペースを節約します。
expanded		Boolean	`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	true `OpenPolicyAssignment` linkType を使用する場合。	String	ポリシーベースのコネクタの場合は、組み込みのポリシー定義の GUID を定義します。
assignMode		ENUM	ポリシーベースのコネクタの場合は、割り当てモードを次のいずれかの値で定義します。`Initiative`、`Policy`
dataCollectionRuleType		ENUM	DCR ベースのコネクタの場合、データ収集規則の種類を `SecurityEvent`または `ForwardEvent`として定義します。

データコネクタ定義の例

次の例では、この記事で定義されているコンポーネントの一部を、Create or Update データコネクタ定義 API で使用する JSON 本文形式としてまとめます。

connectorUiConfigのその他の例については、他 CCP データコネクタを確認してください。レガシ 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"
                  }
                }
              ]
            }
          ]
        }
    }
}

次の方法で共有

コードレスコネクタプラットフォームのデータコネクタ定義リファレンス

データコネクタの定義 - 作成または更新

URI パラメーター

要求本文

コネクタのユーザーインターフェイスを構成する

connectivityCriteria

dataTypes

graphQueries

アクセス許可

resourceProvider

sampleQueries

その他のリンクオプションを構成する

instructionSteps

instructions

OAuthForm

テキストボックス

ConnectionToggleButton

CopyableLabel

InfoMessage

InstructionStepsGroup

InstallAgent

データコネクタ定義の例

フィードバック

その他のリソース

次の方法で共有

コードレス コネクタ プラットフォームのデータ コネクタ定義リファレンス

データ コネクタの定義 - 作成または更新

URI パラメーター

要求本文

コネクタのユーザー インターフェイスを構成する

connectivityCriteria

dataTypes

graphQueries

アクセス許可

resourceProvider

sampleQueries

その他のリンク オプションを構成する

instructionSteps

instructions

OAuthForm

テキストボックス

ConnectionToggleButton

CopyableLabel

InfoMessage

InstructionStepsGroup

InstallAgent

データ コネクタ定義の例

フィードバック

その他のリソース

コードレスコネクタプラットフォームのデータコネクタ定義リファレンス

データコネクタの定義 - 作成または更新

コネクタのユーザーインターフェイスを構成する

その他のリンクオプションを構成する

データコネクタ定義の例