無程式代碼連接器架構的 RestApiPoller 資料連接器參考

RestApiPoller若要使用無程式代碼連接器架構建立數據連接器（CCF），請使用此參考做為 Data Connectors 檔Microsoft Sentinel REST API 的補充。

每個 dataConnector 都代表Microsoft Sentinel 數據連接器的特定 連線 。 一個數據連接器可能會有多個連線，可從不同的端點擷取數據。 使用此參考檔建置的 JSON 組態可用來完成 CCF 數據連接器的部署範本。

如需詳細資訊，請參閱為 Microsoft Sentinel 建立無程式碼連接器。

數據連接器 - 建立或更新

參考 REST API 檔中的建立或更新作業，以尋找最新的穩定或預覽 API 版本。 建立和更新作業之間的差異在於更新需要 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 版本的詳細資訊，請參閱 數據連接器 - 建立或更新 URI 參數。

要求本文

CCF 資料連接器的要求本文 RestApiPoller 具有下列結構：

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

此範例會使用預設值，併產生下列標頭： 授權：令牌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

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. 傳送認證以 TokenEndpoint 取得 JWT 權杖

   • 如果 IsCredentialsInHeaders: true：傳送帶有username：password的基本身份驗證標頭
   • 如果 IsCredentialsInHeaders: false：在POST內文中傳送認證

2. 使用 JwtTokenJsonPath 或 從回應標頭擷取權杖

3. 在後續的 API 請求中使用帶有標頭的 ApiKeyName 權杖

屬性：

身份驗證流程：

1. 傳送認證以 TokenEndpoint 取得 JWT 權杖

   • 如果 IsCredentialsInHeaders: true：傳送帶有username：password的基本身份驗證標頭
   • 如果 IsCredentialsInHeaders: false：在POST內文中傳送認證

2. 使用 JwtTokenJsonPath 或 從回應標頭擷取權杖

3. 在後續的 API 請求中使用帶有標頭的 ApiKeyName 權杖

要求設定

要求區段會定義 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}"
  }
}

另一個選項是數據源預期有 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",
}

這會將要求傳送 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 回應包括：

• Link HTTP 回應標頭
• 或 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

Offset 分頁會指定要略過的頁數，以及要求中每個頁面要擷取的事件數目限制。 用戶端會從數據集擷取特定範圍的專案。

範例：

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

設定 CountBasedPaging

CountBasedPaging 允許用戶端指定要在回應中傳回的專案數目。 這對於支援以 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": ["$"]
      }
   }
}