Выполнить запрос по URL (Fetch URL)

Блок Выполнить запрос по URL (Fetch URL) получает веб-содержимое по URL указанным методом и разбирает его в переменные сценария.

Поддерживаются HTTP, базовая аутентификация HTTPS, Bearer Token и OAuth 2.0 Client Credentials. Создавайте учетные записи Web Client Credentials для хранения учетных данных аутентификации и их повторного использования в блоках Выполнить запрос по URL (Fetch URL).

Блок сценария Fetch URL

Условные выходы

В блоке Fetch URL предусмотрены три условных выхода:

Ошибка
Выход Failed используется при ошибке выполнения метода HTTP или невозможности разобрать тело ответа HTTP. Подробнее см. раздел Коды ответа HTTP ниже.
Нет данных
Выход No Data используется, если в теле ответа HTTP нет данных.
Тайм-аут
Выход Timeout используется, если время обработки превышает значение поля Тайм-аут запроса (Request Timeout).

Настройки

Текст заголовка
Название экземпляра блока, отображаемое на схеме.
Тип запроса
Метод HTTP, используемый для запроса.
Тип запроса (метод HTTP) Тип содержимого (Content Type) Примечания
GET
  • application/json
  • application/x-www-form-urlencoded
  • application/soap+xml; charset=utf-8
POST
  • application/json
  • application/x-www-form-urlencoded
  • application/soap+xml; charset=utf-8
  • multipart/form-data
  • <загрузка одного файла; тип содержимого задается ниже>
PUT
  • application/json
  • application/x-www-form-urlencoded
PATCH
  • application/json
  • application/x-www-form-urlencoded
DELETE
  • application/json
  • application/x-www-form-urlencoded
Запрашиваемый URL (URL to fetch)
URL веб-ресурса HTTP/HTTPS, к которому обращается блок. Параметры строки запроса, если они есть, задаются в разделе Параметры URL (URL parameters). Если параметры заданы, они добавляются к URL. Разделители «?» и «&» вставляются автоматически.
Дополнительные заголовки
Заголовки HTTP, добавляемые к запросу, обычно для аутентификации. В качестве значения можно указать функцию. Нажмите Добавить (add), чтобы задать заголовок, затем введите его имя (name) и значение (value).
Например, платежный шлюз может иметь интерфейс RESTful, требующий аутентификации через заголовок «Authorization» и хеш SHA-256 от времени, имени пользователя и пароля. Для такой аутентификации задайте заголовок запроса с именем Authorization и значением вида bearer $(accessid), где переменной accessid присвоено, например, =hmac('SHA-256', '<key>', '<user>:<secret>').
Аутентификация через конечную точку OAuth 2.0 обычно выполняется аналогично. Получив токен доступа, например с помощью другого блока Выполнить запрос по URL (Fetch URL), который обращается к конечной точке токена и сохраняет результат в accessToken, можно передать его в заголовке Authorization со значением bearer $(accessTokenVariable).
Подробнее о функциях Конструктора сценариев см. Встроенные функции.
Параметры URL (URL parameters)
Параметры, кодируемые для URL и добавляемые к нему. Можно использовать переменные сценария в формате $(varname). Нажмите Добавить (add), чтобы задать параметры URL, затем введите имя и значение.
Тип содержимого (Content Type)
Тип данных, отправляемых в теле запроса или получаемых в теле ответа.
В раскрывающемся списке предложены наиболее распространенные типы содержимого. Нужное значение также можно ввести вручную прямо в поле списка.
Выберите application/json для структуры данных JSON, application/x-www-form-urlencoded для данных, закодированных как URI, или application/soap+xml; charset=utf-8 для тела в формате XML.
Тип содержимого (Content Type) Тип запроса (метод HTTP) Примечания
application/json GET, POST, PUT, PATCH, DELETE
application/x-www-form-urlencoded GET, POST, PUT, PATCH, DELETE
application/soap+xml; charset=utf-8 GET, POST
Multipart/form-data POST Позволяет добавлять несколько частей с вложениями или текстом.
Загрузка одного файла; тип содержимого задается ниже. POST Тип содержимого необязателен. Если он не указан, система использует тип содержимого вложения.
Тело запроса (Body)
Этот параметр отображается, если для Тип содержимого (Content Type) задано значение application/json, и определяет данные, передаваемые в запросе в формате JSON. Допускается подстановка переменных сценария.
Параметры формы (Form parameters)
Этот параметр отображается, если для Тип содержимого (Content Type) задано значение application/x-www-form-urlencoded, и определяет данные, передаваемые в запросе в виде строки пар «ключ — значение» с кодированием URL. Для каждого параметра нажмите Добавить (add), введите имя и задайте значение. Допускается подстановка переменных сценария.
Аутентификация (Authentication)
Выберите учетную запись Web Client Credentials для аутентификации.
Если выбрана учетная запись Web Client Credentials, для аутентификации используются ее учетные данные, а поля Имя пользователя и Пароль этого блока игнорируются и доступны только для чтения.
По умолчанию выбран вариант Имя пользователя и пароль в свойствах блока (Username & Password in block’s properties), который обеспечивает обратную совместимость и позволяет вводить учетные данные непосредственно в поля Имя пользователя и Пароль ниже.
Имя пользователя
Имя пользователя для аутентификации запроса. Допускается подстановка переменных.
Пароль
Пароль для аутентификации запроса. Допускается подстановка переменных.
Формат тела ответа (Response body content is)
Ожидаемый формат тела ответа: текст, XML или JSON.
Начальный путь в JSON результата
Если тело ответа содержит JSON, этот параметр позволяет сохранять отдельные части данных в переменные сценария. Пример: myobject.node.list[4]. Путь начинается от корня возвращенного JSON.
Префикс переменных сценария для данных JSON
Эта строка используется как имя переменной для полученных разобранных данных JSON. Если начальный путь ведет к массиву, то в зависимости от параметра Использовать GetNext для перебора данных эта переменная будет содержать весь массив либо его первый и последующие элементы. Подробнее см. раздел Обработка данных ответа ниже.
Извлечь переменные (Extract variables)
Если параметр Формат тела ответа (Response body content is) указывает на ответ XML, этот параметр определяет, какие данные ответа следует разобрать в переменные сценария. Можно задать любое количество выражений XPath и связать каждое с именем переменной.
Каждое выражение XPath используется для разбора ответа XML, а результат сохраняется в соответствующей переменной. Если выражение указывает на несколько значений или на узел с дочерними узлами, параметр Использовать GetNext для перебора данных определяет, будет ли переменная содержать массив значений или только первое значение. Подробнее см. раздел Обработка данных ответа ниже.
Тайм-аут запроса (Request timeout)
Задает тайм-аут на случай, если обработка API внешнего веб-сервиса длится дольше ожидаемого. Если ответ API не получен за заданное время, система может перейти к следующему блоку. Допустимый диапазон: от 2 до 100 секунд. Если поле пустое, используется 100 секунд. Это поле присутствует только при явно заданном значении.
Использовать GetNext для перебора данных
Установите этот флажок, если данные ответа JSON по начальному пути являются массивом. В переменную сценария записывается первый элемент массива, а блок Получить следующую запись (Get Next) позволяет перебирать остальные элементы, последовательно записывая следующий элемент в переменную.

Если GetNext включен, Fetch URL работает так же, как в Cloud Contact версии 3.13 и более ранних.

Обработка данных ответа

Размер данных ответа ограничен 100 КБ для всех типов содержимого.

Если данные ответа не имеют формат JSON или XML, они доступны как строка через переменную сценария $(integrationResultBody), описанную в разделе «Коды ответа HTTP» ниже.

Ответы в формате JSON

Если ответ содержит JSON, выполняются следующие действия:

  1. Данные разбираются.
  2. Если параметр Использовать GetNext для перебора данных включен, а элемент по начальному пути является обычным неассоциативным массивом:
    1. В переменную сценария записывается первый элемент массива.
    2. Получить следующую запись (Get Next) позволяет записывать в переменную второй и последующие элементы.
  3. В остальных случаях в переменную сценария записывается элемент, на который указывает начальный путь.

Допустимый синтаксис начального пути и доступа к данным, сохраненным в переменной сценария:

  • item.Subitem
  • item[index]
  • item[attr1=value].attr2
  • комбинации, например item.subitem.array[index].value.array[attr=x].value)

Ответы в формате XML

Если данные ответа имеют формат XML и параметр Формат тела ответа (Response body content is) указывает XML, каждое выражение XPath, заданное в Извлечь переменные (Extract variables), используется для разбора ответа и присвоения значения связанной переменной по следующим правилам:

  • Если XPath указывает на конкретное значение, оно присваивается переменной <variableName>.
  • Если XPath указывает на узел XML с дочерними узлами:
    • Для каждого атрибута узла его значение присваивается переменной <variableName>.<attributeName>.
    • Для каждого дочернего узла его значение присваивается переменной <variableName>.<childNodeName>. Правило применяется рекурсивно: если у дочернего узла есть собственный дочерний узел, его значение присваивается переменной <variableName>.<childNodeName>.<childOfChild> и т. д.
    • Если имя атрибута совпадает с именем дочернего узла, используется значение дочернего узла, а атрибут игнорируется.
  • Если XPath не указывает ни на один элемент ответа XML, соответствующей переменной присваивается пустая строка.
  • Если выражение XPath указывает на массив:
    • Если параметр Использовать GetNext для перебора данных включен, сначала в переменную записывается первый элемент массива, заданного выражением XPath. Блок Получить следующую запись (Get Next Record) позволяет перебрать остальные значения.
    • Если параметр Использовать GetNext для перебора данных отключен, в переменную записывается весь массив значений. К нему можно обращаться в других частях сценария с помощью $(<variableName>[index])

Коды ответа HTTP

Код состояния и тело полученного ответа HTTP сохраняются соответственно в локальных переменных $(integrationResultCode) и $(integrationResultBody). Для диагностики можно использовать блок Отправить электронное письмо (EMail) или Внутреннее сообщение (Internal Message) для получения содержимого ответов, указывающих на неудачную попытку. Подробнее см. описание переменной $(integrationResultBody).

Для обратной совместимости код и тело полученного ответа HTTP также сохраняются в локальных переменных $(fetchURLResultCode) и $(fetchURLResultBody).

Возможные значения переменной $(fetchURLResultCode):

  • 0: Ответ 200 OK, то есть успешный ответ на запрос HTTP.
  • -1: Ответ 200 OK, но тело не удалось разобрать в переменную для ответа JSON или XML.
  • -2: Ответ 200 OK, но длина тела превышает 50 КБ.
  • -3: Не удалось подключиться к серверу HTTP или возникла другая ошибка соединения.
  • -4: Неверный синтаксис JSON в теле запроса PUT или POST.
  • Другие значения: Фактический код ответа HTTP, отличный от 200, например 400 или 500.

Примечание: при возврате кодов ошибок, например 500, некоторые серверы не предоставляют дополнительных сведений. Если они есть, они передаются сценарию как обычная строка. Далее можно проверить ошибки на соответствующем веб-сервере или извлечь подробности из тела ответа с помощью регулярного выражения.

Обработка перенаправлений HTTP

Блок Fetch URL обрабатывает коды ответа HTTP 3xx следующим образом:

При получении следующих кодов блок повторяет запрос по указанному URL перенаправления методом GET:

  • 301 Moved Permanently
  • 302 Found
  • 303 See Other (начиная с HTTP/1.1)

При получении следующих кодов блок повторяет запрос по указанному URL перенаправления исходным методом:

  • 307 Temporary Redirect (начиная с HTTP/1.1)
  • 308 Permanent Redirect (RFC 7538)

При получении следующих кодов состояния используется условный выход Ошибка:

  • 300 Multiple Choices
  • 304 Not Modified (RFC 7232)
  • 305 Use Proxy (начиная с HTTP/1.1)
  • 306 Switch Proxy |