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

コードレス コネクタ フレームワーク (CCF) を使用してRestApiPoller データ コネクタを作成するには、この記事をデータ コネクタ用の Microsoft Sentinel REST API の補足資料として使用します。

各データ コネクタは、Microsoft Sentinel データ コネクタの特定の接続を表します。 1 つのデータ コネクタに複数の接続があり、異なるエンドポイントからデータをフェッチします。 この記事でビルドした JSON 構成を使用して、CCF データ コネクタのデプロイ テンプレートを完了できます。

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

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

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

PUT メソッド：

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

URI パラメーター

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

要求本文

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

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

RestApiPoller

RestApiPoller は、データ ソースのページング、承認、要求/応答ペイロードをカスタマイズするために使用できる API ポーリングツール CCF データ コネクタです。

認証の構成

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

• 基本
• API キー
• OAuth2
• Jwt

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

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

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

基本認証

connectorUIconfigで定義されているパラメーターを使用する基本認証の例を次に示します。

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

API キー

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) 認証では、ユーザー名とパスワードの資格情報を使用してトークンを取得し、API 要求に使用できます。

基本的な例

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

POST 本文の資格情報 (既定値)

"auth": {
    "type": "JwtToken",
    "userName": {
        "key": "username",
        "value": "[[parameters('UserName')]"
    },
    "password": {
        "key": "password",
        "value": "[[parameters('Password')]"
    },
    "TokenEndpoint": "https://api.example.com/token",
    "Headers": {
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    "IsCredentialsInHeaders": false,
    "IsJsonRequest": true,
    "JwtTokenJsonPath": "$.access_token"
}

ヘッダー内の資格情報 (基本認証)

"auth": {
    "type": "JwtToken",
    "userName": {
        "key": "client_id",
        "value": "[[parameters('ClientId')]"
    },
    "password": {
        "key": "client_secret",
        "value": "[[parameters('ClientSecret')]"
    },
    "TokenEndpoint": "https://api.example.com/oauth/token",
    "Headers": {
        "Accept": "application/json"
    },
    "IsCredentialsInHeaders": true,
    "IsJsonRequest": true,
    "JwtTokenJsonPath": "$.access_token",
    "RequestTimeoutInSeconds": 30
}

ヘッダー内の資格情報 (ユーザー トークン)

"auth": {
    "type": "JwtToken",
    "UserToken": "[[parameters('userToken')]",
    "UserTokenPrepend": "Bearer",
    "TokenEndpoint": "https://api.example.com/oauth/token",
    "Headers": {
        "Accept": "application/json"
    },
    "TokenEndpointHttpMethod": "GET",
    "NoAccessTokenPrepend": true,
    "JwtTokenJsonPath": "$.systemToken"
}

次の認証フローに従います。

1. passwordに資格情報を送信して JWT トークンを取得します。userNameとpasswordを使用する場合は、IsCredentialsInHeadersを使用して要求に資格情報を配置する場所を決定します。

   • IsCredentialsInHeaders: true場合: username:passwordを含む基本認証ヘッダーを送信します。
   • IsCredentialsInHeaders: false場合: POST本文で資格情報を送信します。

2. JwtTokenJsonPathを使用するか、応答ヘッダーからトークンを抽出します。

3. JWT トークンの Authorization ヘッダーは定数であり、常に "Authorization" になります。

要求の構成

要求セクションでは、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}です。

RateLimitConfig の例

次の例を考えてみましょう。

ApiEndpoint = https://www.example.com.

"rateLimitConfig": {
  "evaluation": {
    "checkMode": "OnlyWhen429"
  },
  "extraction": {
    "source": "CustomHeaders",
    "headers": {
      "limit": {
        "name": "X-RateLimit-Limit",
        "format": "Integer"
      },
      "remaining": {
        "name": "X-RateLimit-Remaining",
        "format": "Integer"
      },
      "reset": {
        "name": "X-RateLimit-RetryAfter",
        "format": "UnixTimeSeconds"
      }
    }
  },
  "retryStrategy": {
    "useResetOrRetryAfterHeaders": true
  }
}

応答にレート制限ヘッダーが含まれている場合、コネクタはこの情報を使用して要求レートを調整できます。

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

次の使用例は、フィルター クエリ パラメーターを使用してメッセージを照会します。 詳細については、「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 "
}

前の例では、https://graph.microsoft.com/v1.0/me/messages?filter=receivedDateTime gt {time of request} and receivedDateTime lt 2019-09-01T17:00:00.0000000にGET要求を送信します。 タイム スタンプは、 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}"
  }
}

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

例:

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

このオプションは、https://graph.microsoft.com/me/calendarView?startDateTime=2019-09-01T09:00:00.0000000&endDateTime=2019-09-01T17:00:00.0000000にGET要求を送信します。

複雑なクエリの場合は、 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}))\"}"
}

応答構成

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

応答構成の例

JSON 形式のサーバー応答が必要です。 応答には、プロパティ 値に要求されたデータがあります。 応答プロパティの 状態 は、値が 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-type ページングには、リンク ヘッダーがバックエンド ストレージに保持される以外は、 LinkHeaderと同じプロパティがあります。 このオプションを使用すると、クエリ ウィンドウ間のページング リンクが有効になります。

たとえば、一部の API ではクエリの開始時刻や終了時刻がサポートされていません。 代わりに、サーバー側カーソルをサポート します。 永続的なページの種類を使用して、サーバー側 カーソルを記憶できます。 詳細については、「 カーソルとは」を参照してください。

次に、いくつかの例を示します:

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

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

例:

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

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

オフセットの構成

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

例:

"paging": {
  "pagingType": "Offset", 
  "offsetParaName": "offset",
  "pageSize": 50,
  "pagingQueryParamOnly": true,
  "pagingInfoPlacement": "QueryString"
}

CountBasedPaging の構成

CountBasedPaging-type 改ページ分割を使用すると、クライアントは応答で返す項目の数を指定できます。 この機能は、応答ペイロードの一部として count パラメーターに基づく改ページをサポートする API に役立ちます。

例:

"paging": {
 "pagingType" : "CountBasedPaging", 
 "pageNumberParaName" : "page", 
 "pageSize" : 10, 
 "zeroBasedIndexing" : true, 
 "hasNextFlagJsonPath" : "$.hasNext", 
 "totalResultsJsonPath" : "$.totalResults", 
 "pageNumberJsonPath" : "$.pageNumber", 
 "pageCountJsonPath" : "$.pageCount"
}

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,
         "rateLimitConfig": {
            "evaluation": {
              "checkMode": "OnlyWhen429"
            },
            "extraction": {
              "source": "CustomHeaders",
              "headers": {
                "limit": {
                  "name": "X-RateLimit-Limit",
                  "format": "Integer"
                },
                "remaining": {
                  "name": "X-RateLimit-Remaining",
                  "format": "Integer"
                },
                "reset": {
                  "name": "X-RateLimit-RetryAfter",
                  "format": "UnixTimeSeconds"
                }
              }
            },
            "retryStrategy": {
              "useResetOrRetryAfterHeaders": true
            }
         },
         "queryWindowInMin": 5,
         "httpMethod": "POST",
         "queryTimeFormat": "UnixTimestamp",
         "startTimeAttributeName": "t0",
         "endTimeAttributeName": "t1",
         "retryCount": 3,
         "timeoutInSeconds": 60,
         "headers": {
            "Accept": "application/json",
            "User-Agent": "Example-app-agent"
         } 
      },
      "paging": {
         "pagingType": "LinkHeader",
         "pagingInfoPlacement": "RequestBody",
         "pagingQueryParamOnly": true
      },
      "response": {
         "eventsJsonPaths": ["$"]
      }
   }
}