コードレス コネクタ フレームワークのデータ コネクタ定義リファレンス

コードレス コネクタ フレームワーク (CCF) を使用してデータ コネクタを作成するには、このドキュメントを、Microsoft Sentinel REST API for Data Connector Definitions リファレンス ドキュメントの補足資料として使用します。具体的には、このリファレンス ドキュメントは次のセクションで展開されます。

• 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 Connector の定義 - URI パラメーターの作成または更新」を参照してください。

要求本文

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

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

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

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

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

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

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

connectivityCriteria

dataTypes

graphQueries

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

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

availability

アクセス許可

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": {}
    }
]

指示

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

OAuthForm

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

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

テキスト ボックス

Textbox型の例を次に示します。 これらの例は、「Codeless Connector Framework のデータ コネクタ リファレンス」の「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"
}

Dropdown

{
  "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 の作成または更新で使用します。

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