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

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

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

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

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

REST API ドキュメントの作成または更新操作を参照して、最新の安定した 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 バージョンの詳細については、「Data Connector の定義 - URI パラメーターの作成または更新」を参照してください。

リクエストの本文

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

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

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

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

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

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

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

connectivityCriteria (接続性基準)

データ型

graphQueries

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

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

権限

リソースプロバイダー

サンプルクエリ

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

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

このコンポーネントでは、データ コネクタ テンプレートの 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"
  }          
}
]

コピー可能なラベル

例：

サンプル コード:

{
    "parameters": {
        "fillWith": [
            "WorkspaceId",
            "PrimaryKey"
            ],
        "label": "Here are some values you'll need to proceed.",
        "value": "Workspace is {0} and PrimaryKey is {1}"
    },
    "type": "CopyableLabel"
}

InfoMessage

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

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

InstructionStepsGroup

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

詳細な例については、 Windows DNS コネクタの構成 JSON を参照してください。

インストールエージェント

一部の InstallAgent の種類はボタンとして表示され、他の種類はリンクとして表示されます。 両方の例を次に示します。

データ コネクタ定義の例

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

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