无代码连接器框架的 RestApiPoller 数据连接器参考

若要使用无代码连接器框架（CCF）创建 RestApiPoller 数据连接器，请使用此参考作为数据 连接器文档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",
}

此示例使用以下标头中的默认值和结果：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

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

另一个选项是数据源需要 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 格式的服务器响应，并在属性 value 中包含请求的数据。 响应属性 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 不支持查询开始时间或结束时间。 而是支持服务器端游标。 永久性页类型可用于记住服务器端游标。 有关详细信息，请参阅什么是游标？。

以下是一些示例：

"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 分页指定要跳过的页数，以及请求中每页检索的事件数的限制。 客户端从数据集中提取特定范围的项目。

示例：

"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": ["$"]
      }
   }
}