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

コードレス コネクタ フレームワーク (CCF) を使用して RestApiPoller データ コネクタを作成するには、Microsoft Sentinel REST API for Data Connectors ドキュメントの補足としてこのリファレンスを使用します。

各 dataConnector は、Microsoft Sentinel データ コネクタの特定の connection を表します。 1 つのデータ コネクタに複数の接続があり、異なるエンドポイントからデータをフェッチする場合があります。 この参照ドキュメントを使用して構築された JSON 構成は、CCF データ コネクタのデプロイ テンプレートを完成させるために使用されます。

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

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

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

PUT メソッド

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

URI パラメーター

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

要求本文

RestApiPoller CCF データ コネクタの要求本文には、次の構造があります。

{
   "name": "{{dataConnectorId}}",
   "kind": "RestApiPoller",
   "etag": "",
   "properties": {
        "connectorDefinitionName": "",
        "auth": {},
        "request": {},
        "response": {},
        "paging": "",
        "dcrConfig": ""
   }
}

RestApiPoller

RestApiPoller は、データ ソースのページング、承認、要求/応答のペイロードをカスタマイズする API Poller CCF データ コネクタを表します。

認証の構成

CCF では、次の認証の種類がサポートされています。

• 基本
• APIKey
• OAuth2 を する
• JWT

ベスト プラクティスとして、資格情報をハードコーディングする代わりに、認証セクションのパラメーターを使用します。 詳細については、「 安全な機密入力」を参照してください。

パラメーターも使用するデプロイ テンプレートを作成するには、追加の開始 [を使用して、このセクションのパラメーターをエスケープする必要があります。 これによりパラメータは、コネクタとのユーザー操作に基づいて値を割り当てることができます。 詳細については、テンプレート式のエスケープ文字に関するページを参照してください。

UI から資格情報を入力できるようにするには、 connectorUIConfig セクションで目的のパラメーターを instructions する必要があります。 詳細については、 コードレス コネクタ フレームワークのデータ コネクタ定義リファレンスを参照してください。

基本認証

connectorUIconfigで定義されているパラメーターを使用した基本認証の例:

"auth": {
    "type": "Basic",
    "UserName": "[[parameters('username')]",
    "Password": "[[parameters('password')]"
}

APIKey

APIKey 認証の例:

"auth": {
    "type": "APIKey",
    "ApiKey": "[[parameters('apikey')]",
    "ApiKeyName": "X-MyApp-Auth-Header",
    "ApiKeyIdentifier": "Bearer"
}

この例では、次のヘッダーで送信されたユーザー入力から定義されたシークレットになります: X-MyApp-Auth-Header: Bearer apikey

"auth": { 
    "type": "APIKey",
    "ApiKey": "123123123",
}

この例では既定値を使用し、 Authorization: token 123123123

"auth": { 
    "type": "APIKey",
    "ApiKey": "123123123",
    "ApiKeyName": ""
}

ApiKeyNameは明示的に "" に設定されているため、結果は次のヘッダーになります:Authorization: 123123123

OAuth2の

Codeless Connector Framework では、OAuth 2.0 承認コードの付与とクライアント資格情報がサポートされます。 認証コード付与の種類は、認証コードをアクセストークンと交換するために、機密クライアントおよびパブリッククライアントによって使用されます。 ユーザーがリダイレクト URL 経由でクライアントに戻った後、アプリケーションは URL から認証コードを取得し、それを使用してアクセス トークンを要求します。

認証コード フローは、ユーザーのアクセス許可に代わってデータをフェッチするためのものであり、クライアント資格情報はアプリケーションのアクセス許可を使用してデータをフェッチするためのフローです。 データ サーバーは、アプリケーションへのアクセスを許可します。 クライアント資格情報フローにはユーザーがないため、承認エンドポイントは必要なく、トークン エンドポイントのみが必要です。

例: OAuth2 authorization_code 許可の種類

"auth": {
    "type": "OAuth2",
    "ClientId": "[[parameters('appId')]",
    "ClientSecret": "[[parameters('appSecret')]",
    "tokenEndpoint": "https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token",
    "authorizationEndpoint": "https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/authorize",
    "authorizationEndpointHeaders": {},
    "authorizationEndpointQueryParameters": {
        "prompt": "consent"
    },
    "redirectUri": "https://portal.azure.com/TokenAuthorize/ExtensionName/Microsoft_Azure_Security_Insights",
    "tokenEndpointHeaders": {
        "Accept": "application/json",
        "Content-Type": "application/x-www-form-urlencoded"
    },
    "TokenEndpointQueryParameters": {},
    "scope": "openid offline_access some_scope",
    "grantType": "authorization_code"
}

例: OAuth2 client_credentials 許可の種類

"auth": {
    "type": "OAuth2",
    "ClientId": "[[parameters('appId')]",
    "ClientSecret": "[[parameters('appSecret')]",
    "tokenEndpoint": "https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token",
    "tokenEndpointHeaders": {
        "Accept": "application/json",
        "Content-Type": "application/x-www-form-urlencoded"
    },
    "TokenEndpointQueryParameters": {},
    "scope": "openid offline_access some_scope",
    "grantType": "client_credentials"
}

JWT

例: JSON Web トークン (JWT)

"auth": {
    "type": "JwtToken",
    "userName": {
        "key":"username",
        "value":"[[parameters('UserName')]"
    },
    "password": {
        "key":"password",
        "value":"[[parameters('Password')]"
    },
    "TokenEndpoint": "https://token_endpoint.contoso.com",
    "IsJsonRequest": true
}

要求の構成

要求セクションでは、CCF データ コネクタがデータ ソースに要求を送信する方法 (API エンドポイントなど) と、そのエンドポイントをポーリングする頻度を定義します。

API に複雑なパラメーターが必要な場合は、組み込みの変数を含む queryParameters または queryParametersTemplate を使用します。

StartTimeAttributeName の例

以下に例を示します。

• StartTimeAttributeName = from
• EndTimeAttributeName = until
• ApiEndpoint = https://www.example.com

リモート サーバーに送信されるクエリは次のとおりです。 https://www.example.com?from={QueryTimeFormat}&until={QueryTimeFormat + QueryWindowInMin}

QueryTimeIntervalAttributeName の例

以下に例を示します。

• QueryTimeIntervalAttributeName = interval
• QueryTimeIntervalPrepend = time:
• QueryTimeIntervalDelimiter = ..
• ApiEndpoint = https://www.example.com

リモート サーバーに送信されるクエリは次のとおりです。 https://www.example.com?interval=time:{QueryTimeFormat}..{QueryTimeFormat + QueryWindowInMin}

Microsoft Graph をデータ ソース API として使用する要求の例

この例では、フィルター クエリ パラメーターを使用してメッセージを照会します。 詳細については、「 Microsoft Graph API クエリ パラメーターを参照してください。

"request": {
  "apiEndpoint": "https://graph.microsoft.com/v1.0/me/messages",
  "httpMethod": "Get",
  "queryTimeFormat": "yyyy-MM-ddTHH:mm:ssZ",
  "queryWindowInMin": 10,
  "retryCount": 3,
  "rateLimitQPS": 20,
  "headers": {
    "Accept": "application/json",
    "User-Agent": "Example-app-agent"
  },
  "QueryTimeIntervalAttributeName": "filter",
  "QueryTimeIntervalPrepend": "receivedDateTime gt ",
  "QueryTimeIntervalDelimiter": " and receivedDateTime lt "
}

前の例では、 GET 要求を https://graph.microsoft.com/v1.0/me/messages?filter=receivedDateTime gt {time of request} and receivedDateTime lt 2019-09-01T17:00:00.0000000に送信します。 各 queryWindowInMin 時刻のタイムスタンプが更新されます。

この例では、同じ結果が得られます。

"request": {
  "apiEndpoint": "https://graph.microsoft.com/v1.0/me/messages",
  "httpMethod": "Get",
  "queryTimeFormat": "yyyy-MM-ddTHH:mm:ssZ",
  "queryWindowInMin": 10,
  "retryCount": 3,
  "rateLimitQPS": 20,
  "headers": {
    "Accept": "application/json",
  },
  "queryParameters": {
    "filter": "receivedDateTime gt {_QueryWindowStartTime} and receivedDateTime lt {_QueryWindowEndTime}"
  }
}

もう 1 つのオプションは、データ ソースで 2 つのクエリ パラメーター (開始時刻に 1 つ、終了時刻に 1 つ) が必要な場合です。

例:

"request": {
  "apiEndpoint": "https://graph.microsoft.com/v1.0/me/calendarView",
  "httpMethod": "Get",
  "queryTimeFormat": "yyyy-MM-ddTHH:mm:ssZ",
  "queryWindowInMin": 10,
  "retryCount": 3,
  "rateLimitQPS": 20,
  "headers": {
    "Accept": "application/json",
  },
  "StartTimeAttributeName": "startDateTime",
  "EndTimeAttributeName": "endDateTime",
}

これにより、 GET 要求が https://graph.microsoft.com/me/calendarView?startDateTime=2019-09-01T09:00:00.0000000&endDateTime=2019-09-01T17:00:00.0000000

複雑なクエリの場合は、 QueryParametersTemplateを使用します。 次の例では、本文にパラメーターを含む POST 要求を送信します。

例:

request: {
  "apiEndpoint": "https://graph.microsoft.com/v1.0/me/messages",
  "httpMethod": "POST",
  "queryTimeFormat": "yyyy-MM-ddTHH:mm:ssZ",
  "queryWindowInMin": 10,
  "retryCount": 3,
  "rateLimitQPS": 20,
  "headers": {
    "Accept": "application/json",
  },
  "isPostPayloadJson": true,
  "queryParametersTemplate": "{\"query":"TableName | where createdTimestamp between (datetime({_QueryWindowStartTime}) .. datetime({_QueryWindowEndTime}))\"}"
}

応答の構成

次のパラメーターを使用して、データ コネクタの応答処理を定義します。

応答構成の例

要求されたデータがプロパティ valueに含まれる、JSON 形式のサーバー応答が必要です。 response プロパティ status は、値が successされている場合にのみ、データを取り込むよう示します。

"response": {
  "EventsJsonPaths ": ["$.value"],
  "format": "json",
  "SuccessStatusJsonPath": "$.status",
  "SuccessStatusValue": "success",
  "IsGzipCompressed: true
 }

この例で想定される応答は、ヘッダーのない CSV を準備します。

"response": {
  "EventsJsonPaths ": ["$"],
  "format": "csv",
  "HasCsvHeader": false
 }

ページングの構成

データ ソースが応答ペイロード全体を一度に送信できない場合、CCF データ コネクタは、応答 ページ内のデータの一部を受信する方法を認識する必要があります。 選択するページングの種類は次のとおりです。

LinkHeader または PersistentLinkHeader の構成

最も一般的なページングの種類は、サーバー データ ソース API がデータの次のページと前のページに URL を提供する場合です。 リンクヘッダ仕様の詳細については、RFC 5988を参照してください。

LinkHeader ページングは、API 応答に次のいずれかが含まれていることを意味します。

• Link HTTP 応答ヘッダー
• または、応答本文からリンクを取得する JSON パス。

PersistentLinkHeader ページングには、バックエンド ストレージにリンク ヘッダーが保持される点を除き、 LinkHeaderと同じプロパティがあります。 このオプションを使用すると、クエリ ウィンドウ間のページング リンクが有効になります。 たとえば、一部の API ではクエリの開始時刻や終了時刻がサポートされていません。 代わりに、サーバー側の cursor をサポートします。 永続的なページの種類は、サーバー側の cursorを記憶するために使用できます。 詳細については、「カーソルとは」を参照してください。

次に例をいくつか示します。

Paging: {
  "pagingType": "LinkHeader",
  "linkHeaderTokenJsonPath" : "$.metadata.links.next"
}

Paging: {
 "pagingType" : "PersistentLinkHeader", 
 "pageSizeParameterName" : "limit", 
 "pageSize" : 500 
}

NextPageUrl の構成

NextPageUrl ページングとは、API 応答の応答本文に LinkHeader のような複雑なリンクが含まれていることを意味しますが、URL はヘッダーではなく応答本文に含まれます。

例:

Paging: {
 "pagingType" : "NextPageUrl", 
  "nextPageTokenJsonPath" : "$.data.repository.pageInfo.endCursor", 
  "hasNextFlagJsonPath" : "$.data.repository.pageInfo.hasNextPage", 
  "nextPageUrl" : "https://api.github.com/graphql", 
  "nextPageUrlQueryParametersTemplate" : "{'query':'query{repository(owner:\"xyz\")}" 
}

NextPageToken または PersistentToken の構成

NextPageToken 改ページでは、現在のページの状態を表すトークン (ハッシュまたはカーソル) が使用されます。 トークンは API 応答に含まれており、クライアントは次の要求にトークンを追加して次のページをフェッチします。 この方法は、サーバーが要求間で正確な状態を維持する必要がある場合によく使用されます。

PersistentToken 改ページでは、サーバー側を保持するトークンが使用されます。 サーバーは、クライアントによって取得された最後のトークンを記憶し、後続の要求で次のトークンを提供します。 クライアントは、後で新しい要求を行った場合でも、中断した場所を続行します。

例 :

Paging: {
 "pagingType" : "NextPageToken", 
 "nextPageRequestHeader" : "ETag", 
 "nextPageTokenResponseHeader" : "ETag" 
}

Paging: {
 "pagingType" : "PersistentToken", 
    "nextPageParaName" : "gta", 
    "nextPageTokenJsonPath" : "$.alerts[-1:]._id" 
}

オフセットの構成

Offset pagination は、スキップするページ数と、要求のページごとに取得するイベントの数の制限を指定します。 クライアントは、データ セットから特定の範囲の項目をフェッチします。

例:

Paging: {
   
       "pagingType": "Offset", 
        "offsetParaName": "offset" 
 }

DCR の構成

CCF データ コネクタの例

CCF データ コネクタ JSON のすべてのコンポーネントの一例を次に示します。

{
   "kind": "RestApiPoller",
   "properties": {
      "connectorDefinitionName": "ConnectorDefinitionExample",
      "dcrConfig": {
           "streamName": "Custom-ExampleConnectorInput",
           "dataCollectionEndpoint": "https://example-dce-sbsr.___location.ingest.monitor.azure.com",
           "dataCollectionRuleImmutableId": "dcr-32_character_hexadecimal_id"
            },
      "dataType": "ExampleLogs",
      "auth": {
         "type": "Basic",
         "password": "[[parameters('username')]",
         "userName": "[[parameters('password')]"
      },
      "request": {
         "apiEndpoint": "https://rest.contoso.com/example",
         "rateLimitQPS": 10,
         "queryWindowInMin": 5,
         "httpMethod": "GET",
         "queryTimeFormat": "UnixTimestamp",
         "startTimeAttributeName": "t0",
         "endTimeAttributeName": "t1",
         "retryCount": 3,
         "timeoutInSeconds": 60,
         "headers": {
            "Accept": "application/json",
            "User-Agent": "Example-app-agent"
         } 
      },
      "paging": {
         "pagingType": "LinkHeader"
      },
      "response": {
         "eventsJsonPaths": ["$"]
      }
   }
}