次の方法で共有


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

コードレス コネクタ プラットフォーム (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 CustomizableAPI ポーリング データ コネクタの場合は、それ以外の場合は 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 次のいずれかの値で必要なライセンスを定義します。OfficeIRMOfficeATPOffice365AadP1P2McasAatpMdatpMtpIoT

例: ライセンスの値は、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 種類ごとに、それぞれ labelplaceholder、および 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 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 ポリシー ベースのコネクタの場合は、割り当てモードを次のいずれかの値で定義します。InitiativePolicy
    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"
                      }
                    }
                  ]
                }
              ]
            }
        }
    }