你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

无代码连接器平台的 RestApiPoller 数据连接器参考

若要使用无代码连接器平台(CCP)创建RestApiPoller数据连接器,请使用此参考作为数据连接器文档Microsoft Sentinel REST API 的补充

每个 dataConnector 都表示 Microsoft Sentinel 数据连接器的一个特定连接。 一个数据连接器可能有多个连接,这些连接从不同的终结点提取数据。 使用此参考文档生成的 JSON 配置用于完善 CCP 数据连接器的部署模板。

有关详细信息,请参阅为 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 参数

名称 描述
dataConnectorId 数据连接器 ID 必须是唯一的名称,并且与请求正文中的 name 参数相同。
resourceGroupName 资源组的名称,不区分大小写。
subscriptionId 目标订阅的 ID。
workspaceName 工作区的名称,而不是 ID
正则表达式模式:^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$
api-version 要用于此操作的 API 版本。

请求正文

CCP 数据连接器的请求正文 RestApiPoller 具有以下结构:

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

RestApiPoller

RestApiPoller 表示 API Poller CCP 数据连接器,可在其中自定义数据源的分页、授权和请求/响应有效负载。

名称 必需 类型​​ 说明
name True string 与 URI 参数匹配的连接的唯一名称
kind True string 必须是 RestApiPoller
etag GUID 为创建新连接器留空。 对于更新操作,etag 必须与现有连接器的 etag (GUID) 匹配。
properties.connectorDefinitionName string 定义数据连接器 UI 配置的 DataConnectorDefinition 资源的名称。 有关详细信息,请参阅数据连接器定义
properties.auth True 嵌套的 JSON 描述用于轮询数据的身份验证属性。 有关详细信息,请参阅身份验证配置
properties.request True 嵌套的 JSON 描述用于轮询数据的请求有效负载,例如 API 终结点。 有关详细信息,请参阅请求配置
properties.response True 嵌套的 JSON 描述在轮询数据时从 API 返回的响应对象和嵌套消息。 有关详细信息,请参阅响应配置
properties.paging 嵌套的 JSON 描述轮询数据时的分页有效负载。 有关详细信息,请参阅分页配置
properties.dcrConfig 嵌套的 JSON 将数据发送到数据收集规则 (DCR) 时所需的参数。 有关详细信息,请参阅 DCR 配置

身份验证配置

CCP 支持以下身份验证类型:

注意

CCP OAuth2 实现不支持客户端证书凭据。

最佳做法是在身份验证部分中使用参数,而不是硬编码凭据。 有关详细信息,请参阅安全机密输入

若要创建同时使用参数的部署模板,需要通过额外的起始 [ 对本节中的参数进行转义。 这样,参数可以根据用户与连接器的交互来分配值。 有关详细信息,请参阅模板表达式转义字符

若要允许从 UI 输入凭据,connectorUIConfig 部分需要具有所需参数的 instructions。 有关详细信息,请参阅无代码连接器平台的数据连接器定义参考

基本身份验证

字段 必须 类型
UserName True string
密码 True string

使用 connectorUIconfig 中定义的参数进行基本身份验证的示例:

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

APIKey

字段 必须 类型​​ 说明 默认值
ApiKey True string 用户密钥
ApiKeyName string 包含 ApiKey 值的 Uri 标头的名称 Authorization
ApiKeyIdentifier string 在令牌前添加的字符串值 token
IsApiKeyInPostPayload boolean 在 POST 正文(而不是标头)中发送机密 false

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 中获取授权代码,并使用它来请求访问令牌。

字段 必须 类型​​ 描述
ClientId True 字符串 客户端 ID
ClientSecret True 字符串 客户端密码
AuthorizationCode 当 grantType = authorization_code 时为 True 字符串 如果授权类型为 authorization_code,此字段值将是从身份验证服务返回的授权代码。
范围 对于 authorization_code 授权类型,True
对于 client_credentials 授权类型,可选
字符串 用户同意的范围的空格分隔列表。 有关详细信息,请参阅 OAuth2 范围和权限
RedirectUri 当 grantType = authorization_code 时为 True 字符串 重定向的 URL 必须为 https://portal.azure.com/TokenAuthorize/ExtensionName/Microsoft_Azure_Security_Insights
GrantType True 字符串 authorization_codeclient_credentials
TokenEndpoint True 字符串 用于与 authorization_code 授权中的有效令牌交换代码或与 client_credentials 授权中的有效令牌交换客户端 ID 和机密的 URL。
TokenEndpointHeaders Object 用于将自定义标头发送到令牌服务器的可选键值对象
TokenEndpointQueryParameters Object 用于将自定义查询参数发送到令牌服务器的可选键值对象
AuthorizationEndpoint True 字符串 authorization_code 流的用户同意 URL
AuthorizationEndpointHeaders 对象 用于将自定义标头发送到身份验证服务器的可选键值对象
AuthorizationEndpointQueryParameters Object OAuth2 授权代码流请求中使用的可选键值对

身份验证代码流用于代表用户的权限提取数据,而客户端凭据用于使用应用程序权限提取数据。 数据服务器授予对应用程序的访问权限。 由于客户端凭据流中没有用户,因此不需要授权终结点,只需令牌终结点。

示例: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
}

请求配置

请求部分定义 CCP 数据连接器如何将请求发送到数据源,例如 API 终结点以及轮询该终结点的频率。

字段 必须 类型​​ 说明
ApiEndpoint True 字符串 远程服务器的 URL。 定义要从中拉取数据的终结点。
RateLimitQPS 整数 定义一秒钟内允许的调用或查询次数。
QueryWindowInMin Integer 定义可用的查询时段(以分钟为单位)。 最小值为 1 分钟。 默认值为 5 分钟。
HttpMethod 字符串 定义 API 方法:GET(默认)或 POST
QueryTimeFormat 字符串 定义终结点(远程服务器)预期的日期和时间格式。 CCP 使用当前日期和时间,无论何时使用此变量。 可能的值为常量:UnixTimestampUnixTimestampInMills 或日期时间的任何其他有效表示形式,例如:yyyy-MM-ddMM/dd/yyyy HH:mm:ss
默认为 ISO 8601 UTC
RetryCount 整数 (1...6) 定义允许从故障中恢复的重试次数为 16 次。 默认为 3
TimeoutInSeconds 整数 (1...180) 定义请求超时,以秒为单位。 默认为 20
IsPostPayloadJson 布尔 确定 POST 有效负载是否采用 JSON 格式。 默认为 false
标头 Object 定义请求头的键值对。
QueryParameters Object 定义请求查询参数的键值对。
StartTimeAttributeName 设置 EndTimeAttributeName 时为 True 字符串 定义查询开始时间的查询参数名称。 请查看示例
EndTimeAttributeName 设置 StartTimeAttributeName 时为 True 字符串 定义查询结束时间的查询参数名称。
QueryTimeIntervalAttributeName 字符串 如果终结点需要一种专用格式来查询期限内的数据,则将此属性与 QueryTimeIntervalPrependQueryTimeIntervalDelimiter 参数配合使用。 请查看示例
QueryTimeIntervalPrepend 设置 QueryTimeIntervalAttributeName 时为 True 字符串 请参见QueryTimeIntervalAttributeName
QueryTimeIntervalDelimiter 设置 QueryTimeIntervalAttributeName 时为 True 字符串 请参见QueryTimeIntervalAttributeName
QueryParametersTemplate 字符串 在高级方案中传递参数时使用的查询模板。
br>例如:"queryParametersTemplate": "{'cid': 1234567, 'cmd': 'reporting', 'format': 'siem', 'data': { 'from': '{_QueryWindowStartTime}', 'to': '{_QueryWindowEndTime}'}, '{_APIKeyName}': '{_APIKey}'}"

当 API 需要复杂参数时,请使用 queryParametersqueryParametersTemplate,其中包括某些内置变量。

内置变量 用于 queryParameters 用于 queryParametersTemplate
_QueryWindowStartTime
_QueryWindowEndTime
_APIKeyName
_APIKey

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

上一个示例向 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}))\"}"
}

响应配置

使用以下参数定义数据连接器的响应处理:

字段 必须 类型​​ 说明
EventsJsonPaths True 字符串列表 定义响应 JSON 中消息的路径。 JSON 路径表达式以 JSON 结构指定一个或一组元素的路径
SuccessStatusJsonPath 字符串 定义响应 JSON 中成功消息的路径。 定义此参数时,还应定义 SuccessStatusValue 参数。
SuccessStatusValue 字符串 定义响应 JSON 中成功消息值的路径
IsGzipCompressed 布尔 确定响应是否压缩为 gzip 文件
format True 字符串 jsoncsvxml
CompressionAlgo 字符串 压缩算法 multi-gzipdeflate。 对于 gzip 压缩算法,只需将 IsGzipCompressed 配置为 True,不为此参数设置值。
CsvDelimiter 字符串 如果响应格式为 CSV,并且需要更改默认 CSV 分隔符 ","
HasCsvBoundary 布尔 指示 CSV 数据是否具有边界
HasCsvHeader 布尔 指示 CSV 数据是否具有标头,默认为 True
CsvEscape 字符串 字段边界的转义字符,默认为 "

例如,带有标头 id,name,avg 和一行包含空格(如 1,"my name",5.5)的数据的 CSV 需要 " 字段边界。
ConvertChildPropertiesToArray 布尔 特殊情况,远程服务器返回一个对象而不是事件列表,其中每个属性都包含数据。

注意

CSV 格式类型由 RFC4180 规范进行分析。

响应配置示例

需要 JSON 格式的服务器响应,并在属性 value 中包含请求的数据。 响应属性 status 指示仅在值为 success 时才引入数据。

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

本示例中的预期响应为没有标头的 CSV 做准备。

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

分页配置

当数据源无法一次发送整个响应负载时,CCP 数据连接器需要知道如何接收响应页中的部分数据。 分页类型从以下类型中选择:

分页类型 决策因子
  • LinkHeader
  • PersistentLinkHeader
  • NextPageUrl
API 响应是否具有指向下一页和上一页的链接?
  • NextPageToken
  • PersistentToken
API 响应是否具有下一页和上一页的令牌或游标?
API 响应是否支持分页时要跳过的对象数的参数?

配置 LinkHeader 或 PersistentLinkHeader

最常用的分页类型是服务器数据源 API 为数据的下一页和上一页提供 URL。 有关“链接标头”规范的详细信息,请参阅 RFC 5988

LinkHeader 分页意味着 API 响应包括以下任一项:

  • Link HTTP 响应头
  • 用于从响应正文中检索链接的 JSON 路径。

PersistentLinkHeader 分页的属性与 LinkHeader 相同,但链接标头保留在后端存储中。 此选项支持跨查询窗口的分页链接。 例如,某些 API 不支持查询开始时间或结束时间。 而是支持服务器端游标。 永久性页类型可用于记住服务器端游标。 有关详细信息,请参阅什么是游标?

注意

只能为具有 PersistentLinkHeader 的连接器运行一个查询,以避免服务器端游标上的争用条件。 这可能会影响延迟。

字段 必须 类型​​ 描述
LinkHeaderTokenJsonPath False 字符串 使用此属性指示在响应正文中获取值的位置。

例如,如果数据源返回以下 JSON:{ nextPage: "foo", value: [{data}]},则 LinkHeaderTokenJsonPath 将为 $.nextPage
PageSize False Integer 每页的事件数
PageSizeParameterName False 字符串 页面大小的查询参数名称

以下是一些示例:

Paging: {
  "pagingType": "LinkHeader",
  "linkHeaderTokenJsonPath" : "$.metadata.links.next"
}
Paging: {
 "pagingType" : "PersistentLinkHeader", 
 "pageSizeParameterName" : "limit", 
 "pageSize" : 500 
}

配置 NextPageUrl

NextPageUrl 分页意味着 API 响应在响应正文中包含一个与 LinkHeader 类似的复杂链接,但 URL 包含在响应正文而不是标头中。

字段 必须 类型​​ 描述
PageSize False Integer 每页的事件数
PageSizeParameterName False 字符串 页面大小的查询参数名称
NextPageUrl False 字符串 仅当连接器用于 Coralogix API 时
NextPageUrlQueryParameters False 对象键值对 - 向下一页的每个请求中添加自定义查询参数
NextPageParaName False 字符串 确定请求中的下一页名称。
HasNextFlagJsonPath False 字符串 定义 HasNextPage 标志属性的路径
NextPageRequestHeader False 字符串 确定请求中的下一页标头名称。
NextPageUrlQueryParametersTemplate False 字符串 仅当连接器用于 Coralogix API 时

示例:

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 分页使用保留在服务器端的令牌。 服务器会记住客户端检索的最后一个令牌,并在后续请求中提供下一个令牌。 即使客户端稍后发出新请求,也会从上次中断的地方继续。

字段 必须 类型​​ 描述
PageSize False Integer 每页的事件数
PageSizeParameterName False string 页面大小的查询参数名称
NextPageTokenJsonPath False string 响应正文中下一页令牌的 JSON 路径。
NextPageTokenResponseHeader False string 如果 NextPageTokenJsonPath 为空,则在下一页的标头名称中使用令牌。
NextPageParaName False string 确定请求中的下一页名称。
HasNextFlagJsonPath False string 在确定响应中是否还有更多页面时,定义 HasNextPage 标志属性的路径
NextPageRequestHeader False string 确定请求中的下一页标头名称。

示例:

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

配置偏移

Offset 分页指定要跳过的页数,以及请求中每页检索的事件数的限制。 客户端从数据集中提取特定范围的项目。

字段 必须 类型​​ 描述
PageSize False Integer 每页的事件数
PageSizeParameterName False 字符串 页面大小的查询参数名称
OffsetParaName False 字符串 下一个请求查询参数名称。 CCP 计算每个请求的偏移值(引入的所有事件 + 1)

示例:

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

DCR 配置

字段 必须 类型​​ 描述
DataCollectionEndpoint True 字符串 DCE(数据收集终结点),例如:https://example.ingest.monitor.azure.com
DataCollectionRuleImmutableId True 字符串 DCR 不可变 ID。 通过查看 DCR 创建响应或使用 DCR API 查找
StreamName True string 此值是在 DCR 中定义的 streamDeclaration(前缀必须以 Custom- 开头)

CCP 数据连接器示例

以下是 CCP 数据连接器 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": ["$"]
      }
   }
}