Справочник по соединителю данных RestApiPoller для платформы без кода

Соединитель данных RestApiPoller с помощью платформы CCF можно создать с помощью этой статьи в качестве дополнения к REST API Microsoft Sentinel документации.

Каждый соединитель данных представляет собой определенный connection соединителя данных Microsoft Sentinel. Один соединитель данных может иметь несколько подключений, которые извлекает данные из разных конечных точек. Шаблон развертывания для соединителя данных CCF можно завершить с помощью конфигурации JSON, созданной с помощью этой статьи.

Дополнительные сведения см. в разделе Create без кода соединителя для Microsoft Sentinel.

Создание или обновление соединителей данных

Найдите последнюю стабильную или предварительную версию API, ссылаясь на create операции или update инструкции в документации по REST API. Разница между операциями create и update операциями заключается в том, что update требуется 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`	Идентификатор соединителя данных. Это должно быть уникальное имя, которое совпадает с `name` параметром в тексте запроса.
`resourceGroupName`	Имя группы ресурсов, а не регистр.
`subscriptionId`	Идентификатор целевой подписки.
`workspaceName`	Имя рабочей области, а не идентификатор. Шаблон регулярных выражений .`^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$`
`api-version`	Версия API, используемая для данной операции.

Текст запроса

Текст запроса для RestApiPoller соединителя данных CCF имеет следующую структуру:

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

RestApiPoller

RestApiPoller — это соединитель данных CCF для опроса API, который можно использовать для настройки разбиения на страницы, авторизации и полезных данных запроса и ответа для источника данных.

Имя	Обязательно	Тип	Описание
`name`	Истина	Строка	Уникальное имя соединения, соответствующего параметру URI.
`kind`	Истина	Строка	Значение `kind`. Это поле должно иметь `RestApiPoller`значение .
`etag`		ГУИД	Значение `etag`. Это поле должно оставаться пустым для создания нового соединителя. Для операций `etag` обновления должен соответствовать существующему соединителю `etag` (GUID).
`properties.connectorDefinitionName`		Строка	Имя ресурса, определяющего `DataConnectorDefinition` конфигурацию пользовательского интерфейса соединителя данных. Дополнительные сведения см. в определении соединителя данных.
`properties.auth`	Истина	Вложенный массив JSON	Свойства проверки подлинности для опроса данных. Дополнительные сведения см. в разделе "Конфигурация проверки подлинности".
`properties.request`	Истина	Вложенный массив JSON	Полезные данные запроса для опроса данных, таких как конечная точка API. Дополнительные сведения см. в разделе "Настройка запроса".
`properties. response`	Истина	Вложенный массив JSON	Объект ответа и вложенное сообщение API возвращается при опросе данных. Дополнительные сведения см. в разделе "Конфигурация ответа".
`properties.paging`		Вложенный массив JSON	Полезные данные разбиения на страницы при опросе данных. Дополнительные сведения см. в разделе "Конфигурация разбиения по страницам".
`properties.dcrConfig`		Вложенный массив JSON	Обязательные параметры при отправке данных в правило сбора данных (DCR). Дополнительные сведения см. в разделе конфигурации DCR.

Конфигурация проверки подлинности

CCF поддерживает следующие типы проверки подлинности:

Базовая
Ключ API
OAuth2
JWT

Примечание.

Реализация CCF OAuth2 не поддерживает учетные данные сертификата клиента.

Рекомендуется использовать параметры в разделе проверки подлинности вместо учетных данных жесткого кодирования. Дополнительные сведения см. в разделе "Безопасные конфиденциальные входные данные".

Чтобы создать шаблон развертывания, который также использует параметры, необходимо экранировать параметры в этом разделе с дополнительным запуском [. Этот шаг позволяет параметрам назначать значение на основе взаимодействия пользователя с соединителем. Дополнительные сведения см. в статье "Выражения шаблонов", экранные символы.

Чтобы включить ввод учетных данных из пользовательского интерфейса, в connectorUIConfig разделе требуется ввести нужные параметры instructions. Дополнительные сведения см. в справочнике по определениям соединителя данных для платформы соединителей без кода.

Обычная проверка подлинности

Поле	Обязательно	Тип
`UserName`	Истина	Строка
`Password`	Истина	Строка

Ниже приведен пример базовой проверки подлинности, которая использует параметры, определенные в connectorUIconfig:

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

Ключ API

Поле	Обязательно	Тип	Описание	Значение по умолчанию
`ApiKey`	Истина	Строка	Ключ секрета пользователя.
`ApiKeyName`		Строка	Имя заголовка URI, содержащего `ApiKey` значение.	`Authorization`
`ApiKeyIdentifier`		Строка	Строковое значение для подготовки маркера.	`token`
`IsApiKeyInPostPayload`		Логический	Значение, определяющее, следует ли отправлять секрет в тексте `POST` вместо заголовка.	`false`

APIKey Примеры проверки подлинности:

"auth": {
    "type": "APIKey",
    "ApiKey": "[[parameters('apikey')]",
    "ApiKeyName": "X-MyApp-Auth-Header",
    "ApiKeyIdentifier": "Bearer"
}

Результатом этого примера является секрет, определенный из входных данных пользователя, отправленных в следующем заголовке: : X-MyApp-Auth-HeaderBearer apikey.

"auth": { 
    "type": "APIKey",
    "ApiKey": "123123123",
}

В этом примере используются значения по умолчанию и результаты в следующем заголовке: : Authorizationtoken 123123123.

"auth": { 
    "type": "APIKey",
    "ApiKey": "123123123",
    "ApiKeyName": ""
}

Так как явно задано ApiKeyNameзначение, результатом является следующий заголовок: : ""Authorization.123123123

OAuth2

Платформа соединителя без кода поддерживает предоставление кода авторизации OAuth 2.0 и учетные данные клиента. Тип предоставления кода авторизации используется конфиденциальными и общедоступными клиентами для обмена кодом авторизации для маркера доступа.

После того как пользователь вернется к клиенту через URL-адрес перенаправления, приложение получит код авторизации из URL-адреса и будет использовать его для запроса маркера доступа.

Поле	Обязательно	Тип	Описание
`ClientId`	Верно.	Строка	Идентификатор клиента.
`ClientSecret`	Верно.	Строка	Секрет клиента.
`AuthorizationCode`	Значение True, если `grantType` значение равно `authorization_code`.	Строка	Если тип предоставления указан `authorization_code`, это значение поля является кодом авторизации, возвращенным сервером проверки подлинности.
`Scope`	Значение true для типа гранта `authorization_code` . Необязательный для типа гранта `client_credentials` .	Строка	Разделенный пробелами список областей для согласия пользователя. Дополнительные сведения см. в разделе "Области и разрешения OAuth2".
`RedirectUri`	Значение True, если `grantType` значение равно `authorization_code`.	Строка	URL-адрес перенаправления должен быть `https://portal.azure.com/TokenAuthorize/ExtensionName/Microsoft_Azure_Security_Insights`.
`GrantType`	Верно.	Строка	Тип гранта. Может иметь значение `authorization_code` или `client_credentials`.
`TokenEndpoint`	Верно.	Строка	URL-адрес для обмена кодом с допустимым маркером в гранте `authorization_code` или идентификатором клиента и секретом с допустимым маркером в гранте `client_credentials` .
`TokenEndpointHeaders`		Объект	Необязательный объект key/value для отправки пользовательских заголовков на сервер токенов.
`TokenEndpointQueryParameters`		Объект	Необязательный объект key/value для отправки пользовательских параметров запроса на сервер токенов.
`AuthorizationEndpoint`	Верно.	Строка	URL-адрес согласия пользователя для `authorization_code` потока.
`AuthorizationEndpointHeaders`		Объект	Необязательный объект key/value для отправки пользовательских заголовков на сервер проверки подлинности.
`AuthorizationEndpointQueryParameters`		Объект	Необязательная пара "ключ-значение", используемая в запросе потока кода авторизации 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 (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"
}

Следуйте этому потоку проверки подлинности:

Отправка учетных данных для TokenEndpoint получения маркера JWT при использовании userName и passwordIsCredentialsInHeaders используется для определения того, куда помещать учетные данные в запрос.
- If IsCredentialsInHeaders: true: отправляет базовый заголовок проверки подлинности с username:passwordпомощью .
- If IsCredentialsInHeaders: false: отправляет учетные данные в тексте POST .
Извлеките маркер с помощью JwtTokenJsonPath заголовка ответа или из нее.
Заголовок авторизации для токенов JWT является константой и всегда будет "Авторизация".

Поле	Обязательно	Тип	Описание
`type`	Истина	Строка	Тип. Должен содержать значение `JwtToken`.
`userName`	True (если `userToken` не используется)	Объект	Пара "ключ-значение" для учетных `userName` данных. Если `userName` и `password` отправляются в запросе заголовка, укажите `value` свойство с именем пользователя. Если `userName` и `password` отправляются в тексте запроса, укажите `Key` и `Value`.
`password`	True (если `userToken` не используется)	Объект	Пара "ключ-значение" для учетных данных пароля. Если `userName` и `password` отправляются в запросе заголовка, укажите `value` свойство с параметром `userName`. Если `userName` и `password` отправляются в тексте запроса, укажите `Key` и `Value`.
`userToken`	True (если `userName` не используется)	Строка	Маркер пользователя, созданный клиентом, для получения системного маркера для проверки подлинности.
`UserTokenPrepend`	Неправда	Строка	Значение, указывающее, следует ли добавлять текст перед маркером. По умолчанию: `Bearer`.
`NoAccessTokenPrepend`	Неправда	Логический	Флаг доступа, указывающий, что маркер не должен быть предустановлен.
`TokenEndpointHttpMethod`	Неправда	Строка	Метод HTTP для конечной точки токена. Это может быть `Get` или `Post`. Значение по умолчанию — `Post`.
`TokenEndpoint`	Истина	Строка	Конечная точка URL-адреса, используемая для получения маркера JWT.
`IsCredentialsInHeaders`		Логический	Значение, указывающее, следует ли отправлять учетные данные как базовый заголовок проверки подлинности (`true`) и `POST` текст (`false`), игнорируемый при использовании `userToken`. Значение по умолчанию — `false`.
`IsJsonRequest`		Логический	Значение, указывающее, следует ли отправлять запрос в формате JSON (заголовок `Content-Type = application/json`) и закодированный в форме (заголовок `Content-Type = application/x-www-form-urlencoded`). Значение по умолчанию — `false`.
`JwtTokenJsonPath`		Строка	Значение, указывающее `JSONPath` значение, используемое для извлечения маркера из ответа. Например: `$.access_token`.
`JwtTokenInResponseHeader`		Логический	Значение, указывающее, следует ли извлечь маркер из заголовка ответа и текста. Значение по умолчанию — `false`.
`JwtTokenHeaderName`.		Строка	Значение, указывающее имя заголовка, когда маркер находится в заголовке ответа. Значение по умолчанию — `Authorization`.
`JwtTokenIdentifier`		Строка	Идентификатор, используемый для извлечения JWT из строки маркера с префиксом.
`QueryParameters`		Объект	Настраиваемые параметры запроса, которые необходимо включить при отправке запроса в конечную точку маркера.
`Headers`		Объект	Пользовательские заголовки, которые необходимо включить при отправке запроса в конечную точку маркера.
`RequestTimeoutInSeconds`		Целое	Время ожидания запроса в секундах. Значение по умолчанию — `100`максимальное значение `180`.

Примечание.

Ограничения

Требуется проверка подлинности имени пользователя и пароля для получения маркера
Не поддерживает запросы маркеров на основе ключей API
Не поддерживает проверку подлинности пользовательского заголовка (без имени пользователя и пароля)

Конфигурация request

В разделе запроса определяется, как соединитель данных CCF отправляет запросы в источник данных (например, конечную точку API и частоту опроса этой конечной точки).

Поле	Обязательно	Тип	Описание
`ApiEndpoint`	Верно.	Строка	Это поле определяет URL-адрес удаленного сервера и определяет конечную точку, из которой следует извлекать данные.
`RateLimitQPS`		Целое	Это поле определяет количество вызовов или запросов, разрешенных в секунду.
`RateLimitConfig`		Объект	Это поле определяет конфигурацию ограничения скорости для API RESTful. Дополнительные сведения см. в `RateLimitConfig` примере.
`QueryWindowInMin`		Целое	Это поле определяет доступное окно запроса в минутах. Минимальное значение составляет 1 минуту. Значение по умолчанию равно 5 минутам.
`HttpMethod`		Строка	Это поле определяет метод API: `GET`(по умолчанию) или `POST`.
`QueryTimeFormat`		Строка	Это поле определяет формат даты и времени, который ожидает конечная точка (удаленный сервер). В CCF используется текущая дата и время, где используется эта переменная. Возможные значения — константы: `UnixTimestamp`или `UnixTimestampInMills`любое другое допустимое представление даты и времени. Например: `yyyy-MM-dd`, `MM/dd/yyyy HH:mm:ss`. Значение по умолчанию — `ISO 8601 UTC`.
`RetryCount`		Целое число (1...6)	Это поле определяет, что значения повторных `16` попыток разрешены для восстановления после сбоя. Значение по умолчанию — `3`.
`TimeoutInSeconds`		Целое число (1...180)	Это поле определяет время ожидания запроса в секундах. Значение по умолчанию — `20`.
`IsPostPayloadJson`		Логический	Это поле определяет, находится ли полезные `POST` данные в формате JSON. Значение по умолчанию — `false`.
`Headers`		Объект	Это поле включает пары "ключ-значение", определяющие заголовки запроса.
`QueryParameters`		Объект	Это поле включает пары "ключ-значение", определяющие параметры запроса запроса.
`StartTimeAttributeName`	Значение True, если задано `EndTimeAttributeName` значение.	Строка	Это поле определяет имя параметра запроса для времени начала запроса. Дополнительные сведения см. в `StartTimeAttributeName` примере.
`EndTimeAttributeName`	Значение True, если `StartTimeAttributeName` задано значение.	Строка	Это поле определяет имя параметра запроса для времени окончания запроса.
`QueryTimeIntervalAttributeName`		Строка	Это поле используется, если для конечной точки требуется специализированный формат для запроса данных в интервале времени. Используйте это свойство с параметрами и `QueryTimeIntervalPrepend` параметрами`QueryTimeIntervalDelimiter`. Дополнительные сведения см. в `QueryTimeIntervalAttributeName` примере.
`QueryTimeIntervalPrepend`	Значение True, если `QueryTimeIntervalAttributeName` задано значение.	Строка	Справочник `QueryTimeIntervalAttributeName`.
`QueryTimeIntervalDelimiter`	Значение True, если `QueryTimeIntervalAttributeName` задано значение.	Строка	Справочник `QueryTimeIntervalAttributeName`.
`QueryParametersTemplate`		Строка	Это поле ссылается на шаблон запроса, используемый при передаче параметров в расширенных сценариях. Например: `"queryParametersTemplate": "{'cid': 1234567, 'cmd': 'reporting', 'format': 'siem', 'data': { 'from': '{_QueryWindowStartTime}', 'to': '{_QueryWindowEndTime}'}, '{_APIKeyName}': '{_APIKey}'}"`.

Если API требует сложных параметров, используйте queryParameters или queryParametersTemplate. Эти команды включают некоторые встроенные переменные.

Встроенная переменная	Для использования в `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}: .

Пример 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 источника данных

В этом примере сообщения запрашиваются с параметром запроса фильтра. Дополнительные сведения см. в разделе Параметры запроса Graph API Microsoft.

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

В предыдущем примере отправляется GEThttps://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}))\"}"
}

Конфигурация response

Определите, как соединитель данных обрабатывает ответы с помощью следующих параметров:

Поле	Обязательно	Тип	Описание
`EventsJsonPaths`	Истина	Список строк	Определяет путь к сообщению в ответе JSON. Выражение пути JSON указывает путь к элементу или набору элементов в структуре JSON.
`SuccessStatusJsonPath`		Строка	Определяет путь к сообщению об успешном выполнении в ответе JSON. При определении `SuccessStatusValue` этого параметра также следует определить параметр.
`SuccessStatusValue`		Строка	Определяет путь к значению сообщения об успешном выполнении в json ответа.
`IsGzipCompressed`		Логический	Определяет, сжимается ли ответ в файле GZIP.
`format`	Истина	Строка	Определяет, является `json`ли формат , `csv`или `xml`.
`CompressionAlgo`		Строка	Определяет алгоритм сжатия либо `multi-gzipdeflate`. Для алгоритма сжатия GZIP настройте `IsGzipCompressedTrue` вместо задания значения для этого параметра.
`CsvDelimiter`		Строка	Ссылается, если формат ответа — CSV, и вы хотите изменить разделитель `","`CSV по умолчанию.
`HasCsvBoundary`		Логический	Указывает, имеет ли данные CSV границы.
`HasCsvHeader`		Логический	Указывает, имеет ли данные CSV заголовок. Значение по умолчанию — `True`.
`CsvEscape`		Строка	Определяет escape-символ для границы поля. Значение по умолчанию — `"`. Например, CSV-файл с заголовками и строкой данных, содержащей пробелы `id,name,avg` , например `1,"my name",5.5` , требует `"` границы поля.
`ConvertChildPropertiesToArray`		Логический	Ссылается на особый случай, в котором удаленный сервер возвращает объект вместо списка событий, в которых каждое свойство содержит данные.

Примечание.

Тип формата CSV анализируется спецификацией RFC4180 .

Примеры конфигурации ответа

Ожидается ответ сервера в формате JSON. Ответ содержит запрошенные данные в значении свойства. Состояние свойства ответа указывает на прием данных только в том случае, если значение равноsuccess.

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

Ожидаемый ответ в этом примере готовится к csv-файлу без заголовка.

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

Конфигурация paging

Если источник данных не может одновременно отправлять всю полезные данные ответа, соединитель данных CCF должен знать, как получать части данных на страницах ответа. Выбор типов разбиения по страницам:

Тип разбиения по страницам	Фактор принятия решений
`LinkHeader` `PersistentLinkHeader` `NextPageUrl`	Есть ли в ответе API ссылки на следующие и предыдущие страницы?
`NextPageToken` `PersistentToken`	Имеет ли ответ API маркер или курсор для следующих и предыдущих страниц?
`Offset`	Поддерживает ли ответ API параметр для количества объектов, пропускаемых при разбиении по страницам?
`CountBasedPaging`	Поддерживает ли ответ API параметр для количества возвращаемых объектов?

Настройка LinkHeader или PersistentLinkHeader

Наиболее распространенный тип разбиения на страницы заключается в том, что API источника данных сервера предоставляет URL-адреса на следующие и предыдущие страницы данных. Дополнительные сведения о спецификации заголовка ссылки см. в разделе RFC 5988.

LinkHeader Разбиение по страницам означает, что ответ API включает в себя:

Заголовок Link ответа HTTP.
Путь JSON для получения ссылки из текста ответа.

PersistentLinkHeader-type paging имеет те же свойства, что LinkHeaderи заголовок ссылки, сохраняется в серверном хранилище. Этот параметр включает ссылки на разбиение по страницам в окнах запросов.

Например, некоторые API не поддерживают время начала запроса или время окончания. Вместо этого они поддерживают серверный курсор. Для запоминания серверного курсора можно использовать постоянные типы страниц. Дополнительные сведения см. в разделе "Что такое курсор?".

Примечание.

Только один запрос соединителя может выполняться, PersistentLinkHeader чтобы избежать условий гонки на стороне сервера. Эта проблема может повлиять на задержку.

Поле	Обязательно	Тип	Описание
`LinkHeaderTokenJsonPath`	Неправда	Строка	Используйте это свойство, чтобы указать, где получить значение в тексте ответа. Например, если источник данных возвращает следующий код JSON: `{ nextPage: "foo", value: [{data}]}LinkHeaderTokenJsonPath` значение равно`$.nextPage`.
`PageSize`	Неправда	Целое	Используйте это свойство для определения количества событий на странице.
`PageSizeParameterName`	Неправда	Строка	Используйте это имя параметра запроса, чтобы указать размер страницы.
`PagingInfoPlacement`	Неправда	Строка	Используйте это свойство для определения заполнения сведений о разбиении по страницам. Принимает либо `QueryStringRequestBody`.
`PagingQueryParamOnly`	Неправда	Логический	Используйте это свойство для указания параметров запроса. Если задано значение true, он пропускает все остальные параметры запроса, кроме параметров запроса на разбиение по страницам.

Далее приводятся некоторые примеры.

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

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

Настройка NextPageUrl

NextPageUrl-type paging означает, что ответ API содержит сложную ссылку в тексте ответа, аналогичную LinkHeader, но URL-адрес включен в текст ответа вместо заголовка.

Поле	Обязательно	Тип	Описание
`PageSize`	Неправда	Целое	Количество событий на страницу.
`PageSizeParameterName`	Неправда	Строка	Имя параметра запроса для размера страницы.
`NextPageUrl`	Неправда	Строка	Поле, используемое только в том случае, если соединитель предназначен для API Coralogix.
`NextPageUrlQueryParameters`	Неправда	Объект	Пары "ключ-значение", добавляющие настраиваемый параметр запроса к каждому запросу для следующей страницы.
`NextPageParaName`	Неправда	Строка	Следующее имя страницы в запросе.
`HasNextFlagJsonPath`	Неправда	Строка	Путь к атрибуту флага `HasNextPage` .
`NextPageRequestHeader`	Неправда	Строка	Следующее имя заголовка страницы в запросе.
`NextPageUrlQueryParametersTemplate`	Неправда	Строка	Поле, используемое только в том случае, если соединитель предназначен для API Coralogix.
`PagingInfoPlacement`	Неправда	Строка	Поле, определяющее заполнение сведений о разбиении по страницам. Принимает либо `QueryStringRequestBody`.
`PagingQueryParamOnly`	Неправда	Логический	Поле, определяющее параметры запроса. Если задано значение true, он пропускает все остальные параметры запроса, кроме параметров запроса на разбиение по страницам.

Пример:

"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 pagination использует маркер (хэш или курсор), представляющий состояние текущей страницы. Маркер включен в ответ API, и клиент добавляет его к следующему запросу, чтобы получить следующую страницу. Этот метод часто используется, когда серверу необходимо поддерживать точное состояние между запросами.

PersistentToken Разбиение на страницы использует маркер, сохраняющий сторону сервера. Сервер запоминает последний маркер, полученный клиентом, и предоставляет следующий маркер в последующих запросах. Клиент продолжает работу, когда он ушел, даже если он выполняет новые запросы позже.

Поле	Обязательно	Тип	Описание
`PageSize`	Неправда	Целое	Количество событий на страницу.
`PageSizeParameterName`	Неправда	Строка	Имя параметра запроса для размера страницы.
`NextPageTokenJsonPath`	Неправда	Строка	Путь JSON для следующего маркера страницы в тексте ответа.
`NextPageTokenResponseHeader`	Неправда	Строка	Поле, указывающее, что `NextPageTokenJsonPath` если пусто, используйте маркер в этом имени заголовка для следующей страницы.
`NextPageParaName`	Неправда	Строка	Поле, определяющее следующее имя страницы в запросе.
`HasNextFlagJsonPath`	Неправда	Строка	Поле, определяющее путь к атрибуту `HasNextPage` флага при определении того, осталось ли в ответе больше страниц.
`NextPageRequestHeader`	Неправда	Строка	Поле, определяющее имя следующего заголовка страницы в запросе.
`PagingInfoPlacement`	Неправда	Строка	Поле, определяющее заполнение сведений о разбиении по страницам. Принимает либо `QueryStringRequestBody`.
`PagingQueryParamOnly`	Неправда	Логический	Поле, определяющее параметры запроса. Если задано значение true, он пропускает все остальные параметры запроса, кроме параметров запроса на разбиение по страницам.

Примеры:

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

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

Настройка смещения

Offset-type pagination указывает количество страниц, которые нужно пропустить, и ограничение на количество событий, извлекаемых на каждую страницу в запросе. Клиенты получают определенный диапазон элементов из набора данных.

Поле	Обязательно	Тип	Описание
`PageSize`	Неправда	Целое	Количество событий на страницу.
`PageSizeParameterName`	Неправда	Строка	Имя параметра запроса для размера страницы.
`OffsetParaName`	Неправда	Строка	Имя параметра запроса следующего запроса. CCF вычисляет значение смещения для каждого запроса (все события приема + 1).
`PagingInfoPlacement`	Неправда	Строка	Поле, определяющее заполнение сведений о разбиении по страницам. Принимает либо `QueryStringRequestBody`.
`PagingQueryParamOnly`	Неправда	Логический	Поле, определяющее параметры запроса. Если задано значение true, он пропускает все остальные параметры запроса, кроме параметров запроса на разбиение по страницам.

Пример:

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

Настройка CountBasedPaging

CountBasedPaging-type pagination позволяет клиенту указать количество элементов, возвращаемых в ответе. Эта возможность полезна для API, которые поддерживают разбиение на страницы на основе параметра счетчика в рамках полезных данных ответа.

Поле	Обязательно	Тип	Описание
`pageNumberParaName`	Истина	Строка	Имя параметра номера страницы в HTTP-запросе.
`PageSize`	Неправда	Целое	Количество событий на страницу.
`ZeroBasedIndexing`	Неправда	Логический	Флаг, указывающий, что счетчик равен нулю.
`HasNextFlagJsonPath`	Неправда	Строка	Путь JSON флага в полезных данных ответа HTTP, указывающих на наличие дополнительных страниц.
`TotalResultsJsonPath`	Неправда	Строка	Путь JSON к общему количеству результатов полезных данных ответа HTTP.
`PageNumberJsonPath`	Неправда	Строка	Путь JSON номера страницы в полезных данных ответа HTTP. Обязательный, если `totalResultsJsonPath` он указан.
`PageCountJsonPath`	Неправда	Строка	Путь JSON счетчика страниц в полезных данных ответа HTTP. Обязательный, если `totalResultsJsonPath` он указан.
`PagingInfoPlacement`	Неправда	Строка	Поле, определяющее заполнение сведений о разбиении по страницам. Принимает либо `QueryStringRequestBody`.
`PagingQueryParamOnly`	Неправда	Логический	Поле, определяющее параметры запроса. Если задано значение true, он пропускает все остальные параметры запроса, кроме параметров запроса на разбиение по страницам.

Пример:

"paging": {
 "pagingType" : "CountBasedPaging", 
 "pageNumberParaName" : "page", 
 "pageSize" : 10, 
 "zeroBasedIndexing" : true, 
 "hasNextFlagJsonPath" : "$.hasNext", 
 "totalResultsJsonPath" : "$.totalResults", 
 "pageNumberJsonPath" : "$.pageNumber", 
 "pageCountJsonPath" : "$.pageCount"
}

Конфигурация DCR

Поле	Обязательно	Тип	Описание
`DataCollectionEndpoint`	Истина	Строка	Конечная точка сбора данных (DCE). Например: `https://example.ingest.monitor.azure.com`.
`DataCollectionRuleImmutableId`	Истина	Строка	Неизменяемый идентификатор DCR. Найдите его, просматривая ответ на создание DCR или используя API DCR.
`StreamName`	Истина	Строка	Это значение определяется `streamDeclaration` в DCR. Префикс должен начинаться с `Custom-`.

Пример соединителя данных 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": ["$"]
      }
   }
}

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-03-11

Поделиться через

Справочник по соединителю данных RestApiPoller для платформы без кода

Создание или обновление соединителей данных

Параметры универсального кода ресурса (URI)

Текст запроса

RestApiPoller

Конфигурация проверки подлинности

Обычная проверка подлинности

Ключ API

OAuth2

JWT

Базовый пример

Учетные данные в тексте POST (по умолчанию)

Учетные данные в заголовках (базовая проверка подлинности)

Учетные данные в заголовках (маркер пользователя)

Конфигурация request

Пример StartTimeAttributeName

Пример QueryTimeIntervalAttributeName

Пример RateLimitConfig

Примеры запросов, которые используют Microsoft Graph в качестве API источника данных

Конфигурация response

Примеры конфигурации ответа

Конфигурация paging

Настройка LinkHeader или PersistentLinkHeader

Настройка NextPageUrl

Настройка NextPageToken или PersistentToken

Настройка смещения

Настройка CountBasedPaging

Конфигурация DCR

Пример соединителя данных CCF

Обратная связь

Дополнительные ресурсы