RestApiPoller 資料連接器參考，適用於無碼連接器框架

你可以利用 Codeless Connector Framework (CCF) 建立RestApiPoller資料連接器，本文作為 Microsoft Sentinel REST API for Data connectors 文件的補充。

每個資料連接器代表 Microsoft Sentinel 資料連接器的特定連接。 一個資料連接器可能有多個連接點，從不同端點擷取資料。 你可以利用本文所建立的 JSON 配置，完成 CCF 資料連接器的部署範本。

欲了解更多資訊，請參閱「為 Microsoft Sentinel 建立無程式碼連接器」。

建立或更新資料連接器

透過參考 REST API 文件中的 or create操作，找到最新的穩定或預覽版 API 版本。和 operations 的差別在於需要 value 值。updatecreateupdateupdateetag

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 參數。

要求內文

CCF 資料連接器的請求體 RestApiPoller 結構如下：

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

RestApiPoller

RestApiPoller 是一個 API 輪詢器 CCF 資料連接器，你可以用來自訂資料來源的分頁、授權及請求/回應有效載荷。

認證設定

CCF 支援以下認證類型：

• 基本
• API 金鑰
• OAuth2
• JWT

最佳做法是，在認證部分使用參數，而非硬編碼憑證。 欲了解更多資訊，請參閱 安全機密輸入。

要建立部署範本（同樣使用參數），你需要用額外的起始 [碼 轉離本節的參數。 此步驟允許參數根據使用者與連接器的互動來分配值。 更多資訊請參見 範本表達式跳脫字元。

要啟用從 UI 輸入憑證，該 connectorUIConfig 區塊要求你在 中輸入所需的參數 instructions。 欲了解更多資訊，請參閱無碼連接器框架的資料連接器定義參考。

基本認證

這裡有一個基本驗證的範例，使用定義在 的參數：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

無碼連接器框架支援 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

JWT (JSON Web Token) 認證支援透過使用者名稱與密碼憑證取得憑證，並用於 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. 發送憑證到 TokenEndpoint 以取得 JWT 憑證，當使用 userName 和 password時 IsCredentialsInHeaders ，會用來決定請求中應將憑證放在哪裡。

   • 如果 IsCredentialsInHeaders: true：傳送帶有 username:password的基本認證標頭。
   • 如果 IsCredentialsInHeaders: false：傳送憑證到 POST 實體。

2. 透過使用 JwtTokenJsonPath 或從回應標頭中提取權杖。

3. JWT 標記的授權標頭為常數，且永遠為「授權」。

請求設定

請求部分定義了 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
  }
}

當回應包含速率限制標頭時，連接器可利用此資訊調整請求速率。

請求使用 Microsoft Graph 作為資料來源 API 的範例

此範例查詢帶有過濾查詢參數的訊息。 欲了解更多資訊，請參閱 Microsoft 圖形 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}"
  }
}

當資料來源預期有兩個查詢參數 (一個是開始時間，一個是結束時間) ，還有另一個選項。

例如:

"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}))\"}"
}

響應配置

請使用以下參數定義您的資料連接器如何處理回應：

響應配置範例

伺服器回應以 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 回應包含以下其中之一：

• HTTP 回應標頭。Link
• 一個 JSON 路徑，用來從回應主體擷取連結。

PersistentLinkHeader-類型分頁具有與 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-型分頁使用一個符號 (雜湊值或游標) ，代表當前頁面的狀態。 該權杖包含在 API 回應中，客戶端會將其附加到下一個請求中以取得下一頁。 此方法常用於伺服器需要維持請求間精確狀態的情況。

PersistentToken 分頁使用一個持續存在於伺服器端的標記。 伺服器會記住用戶端最後取得的標記，並在後續請求中提供下一個標記。 客戶端會繼續從中斷的地方繼續，即使之後會提出新的請求。

範例：

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

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

設定偏移量

Offset-type 分頁指定要跳過的頁面數，以及請求中每頁可檢索事件數量的限制。 用戶端會從資料集中擷取特定範圍的項目。

例如:

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

設定 CountBasedPaging

CountBasedPaging-類型分頁允許用戶端指定回應中要回傳的項目數量。 此功能對於支援以計數參數作為回應有效載荷一部分分頁的 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": ["$"]
      }
   }
}