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

Вы можете создать RestApiPoller соединитель данных с помощью платформы соединителей без кода (CCF), используя эту статью в качестве дополнения к документации по MICROSOFT SENTINEL REST API для соединителей данных.

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

Дополнительные сведения см. в статье Создание соединителя без кода для 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.

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

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

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

RestApiPoller

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

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

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

• Базовый
• Ключ API
• OAuth2
• JWT

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

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

Чтобы включить ввод учетных данных из пользовательского интерфейса, в 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 (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 при использовании userName и passwordиспользуется IsCredentialsInHeaders для определения места для ввода учетных данных в запросе.

   • Если IsCredentialsInHeaders: true: отправляет базовый заголовок проверки подлинности с username:password.
   • Если IsCredentialsInHeaders: false: отправляет учетные данные в тексте POST .

2. Извлеките маркер с помощью JwtTokenJsonPath или из заголовка ответа.

3. Заголовок Authorization для маркеров JWT является константой и всегда будет иметь значение "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 Graph.

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

Этот параметр отправляет 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-type paging имеет те же свойства, что и LinkHeader, за исключением того, что заголовок ссылки сохраняется во внутреннем хранилище. Этот параметр включает разбиение ссылок на разбиение по страницам в окнах запросов.

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

Ниже приводятся примеры:

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

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

Настройка NextPageUrl

NextPageUrl-type paging означает, что ответ 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-type разбиение на страницы указывает количество пропущенных страниц и ограничение на количество событий, извлекаемых для каждой страницы в запросе. Клиенты получают определенный диапазон элементов из набора данных.

Пример:

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

Настройка CountBasedPaging

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

Пример:

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

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

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

Ниже приведен пример всех компонентов json соединителя данных CCF:

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