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

可以使用本文作为数据连接器Microsoft Sentinel REST API 文档的补充，使用无代码连接器框架 (CCF) 创建RestApiPoller数据连接器。

每个数据连接器表示Microsoft Sentinel数据连接器的特定连接。 一个数据连接器可能有多个连接，这些连接从不同的终结点提取数据。 可以使用本文生成的 JSON 配置完成 CCF 数据连接器的部署模板。

有关详细信息，请参阅为Microsoft Sentinel创建无代码连接器。

创建或更新数据连接器

通过引用 REST API 文档中的 或 操作，查找最新的稳定或update预览版 API 版本。create和 操作之间的区别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 参数。

请求正文

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

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. 使用 userName 和 passwordIsCredentialsInHeaders 时，将凭据TokenEndpoint发送到 以获取 JWT 令牌，用于确定在请求中放置凭据的位置。

   • 如果 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
  }
}

当响应包含速率限制标头时，连接器可以使用此信息来调整其请求速率。

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

此选项将请求发送到 GEThttps://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-type 分页具有与 LinkHeader相同的属性，只是链接标头保留在后端存储中。 此选项启用跨查询窗口的分页链接。

例如，某些 API 不支持查询开始时间或结束时间。 相反，它们支持服务器端 游标。 可以使用持久页类型来记住服务器端 游标。 有关详细信息，请参阅 什么是游标？。

下面是一些示例：

"paging": {
  "pagingType": "LinkHeader",
  "linkHeaderTokenJsonPath" : "$.metadata.links.next"
}

"paging": {
 "pagingType" : "PersistentLinkHeader", 
 "pageSizeParameterName" : "limit", 
 "pageSize" : 500 
}

配置 NextPageUrl

NextPageUrl-type 分页表示 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 分页使用保留服务器端的令牌。 服务器会记住客户端检索到的最后一个令牌，并在后续请求中提供下一个令牌。 客户端在中断的位置继续，即使稍后发出新请求也是如此。

示例：

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

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

配置 Offset

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

示例：

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

配置 CountBasedPaging

CountBasedPaging-type 分页允许客户端指定要在响应中返回的项数。 此功能对于支持基于计数参数作为响应有效负载一部分的分页的 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": ["$"]
      }
   }
}