Действие - «Отправить запрос» (POST, GET, PUT, PATCH, DELETE)

Назначение

Действие предназначено для простых интеграций со сторонними сервисами или сайтами. Простых = не требующих запуска PHP скриптов для формирования подписи. Например: ваш собственный скрипт, Airtable, Zapier или даже Телеграм (последнее возможно, но не рекомендуется).

Если такое действие добавлено в команду, то команда будет отправлять запрос (вебхук) на адрес, указанный в текстовом поле действия.

Адрес может иметь произвольное количество GET-параметров. Но в общей сумме не более 3000 символов. Дополнительно можно передавать параметры при помощи удобного интерфейса доп. полей. Значения и названия параметров можно формировать с помощью переменных. Подробнее ниже.

Немножко теории

Объясню методы (типы) запросов. Дело в том, что запросы между сервисами, это своеобразная имитация программой действий человека. Обычно выделяют 3 основных метода (для интеграций больше и не используют):

• GET — эквивалент перехода человеком по ссылке. Ссылка при этом может содержать в себе набор так называемых GET-параметров. Даже в виде многомерного массива. Обеспечивается это специальным синтаксисом. Описал этот синтаксис тут.
• POST — эквивалент заполнения HTML формы (такой, как форма подписки или форма заказа). Легко и полноценно поддерживает большие текстовые поля. В ссылке при этом эти данные не фигурируют.
• POST JSON — по сути тот же POST = заполнение формы, но в форме нету полей, а только 1 текстовый файлик JSON-формата. Там на самом деле просто пачка текста уходит. Но файл лучше для понимания сути.
• Все последующие (PATCH, PUT, DELETE) аналогичные POST JSON. Просто другое название чтобы определенные сервисы (которые это поддерживают) сразу понимали к чему готовиться.

Разные методы имеют свои определенные особенности. И, главное, поддерживаются разными сервисами. Но их общие возможности при этом практически идентичны.

Опции

Параметры действия довольно простые:

• (1) Переключатель метода: POST (по умолчанию), GET или POST JSON (это тоже POST, но с парочкой дополнительных заголовков и данные передаются в нем текстом в виде JSON-массива а не обычной form-data). Есть еще дополнительные современные методы: PATCH, PUT и DELETE. Это аналоги последнего, но чуточку отличаются по назначению. Ну и просто название метода другое. :) Некоторым сервисам это важно.
• (2) Текстовое поле, в которое нужно прописать адрес для отправки запроса. Если вы допишите ей GET-параметры, то они передадутся как GET-массив, не зависимо от метода (типа) запроса из пункта 1.
• (3) Массив параметров запроса. Это основные данные которые передаются внешнему ресурсу. Подробнее в соотвествующем разделе статьи ↓ (обязательно к ознакомлению!)
• (4) Аналогичный массив заголовков запроса. Важно уметь читать формат заголовков. Например для заголовка sign: autopilot названием заголовка будет sign, а значением autopilot (см. пример на скрине ниже).
• (5) этим пунктом я показал еще один вариант, как можно передать данные для запроса методом PUT JSON. К этому еще вернемся ниже.

GET-параметры ссылки

Для всех методов отправки доступны GET-параметры ссылки запроса, которые передаются как GET-массив. Для обычных GET запросов Они имеют следующий синтаксис:

? — начало параметров,

& — разделитель параметров,

= — ставим между названием параметра и его значением.

Немного подробнее с примерами можете почитать статье Формирование GET-запроса для вызова события.

Пример готового адреса для запроса:

https://skyjoom.com/example/path/script.php?email=%email%&first_name=%first_name%&last_name=%last_name%&utm_source=autopilot&another_param=%value%

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

Пробелы и переносы строк внутри ссылки могут Автопилот попытается обработать автоматически. Можете о них сильно не переживать.

Поля параметров

Некоторые особенности параметров для каждого из методов запроса:

• В запросах с методом GET, поля из параметров будут перезаписывать GET-параметры ссылки запроса. В остальных методах основные параметры будут передаваться отдельно.
• Если нужно передавать большие данные (например текст на много строк) воспользуйтесь временной переменной и в значение параметра пропишите эту самую переменную (и в идеале метод используйте не GET).
• Поле «название параметра» тоже должно поддерживать переменные.

ВНИМАНИЕ! Для отправки данных JSON массивом заголовки:
accept: application/json а также content-type: application/json прописывать не нужно! Автопилот их заполняет автоматически.
Достаточно переключить метод запроса на PUT JSON.

Многомерные массивы параметров

Многомерные можно еще назвать многоуровневыми. Это когда в одном из параметров (или в нескольких) может содержаться не значение, а отдельный набор параметров. Как с этим жить и как этим орудовать в Автопилоте я наглядно и подробно показал в видео, которе в начале статьи.

Если вкратце, то есть такая штука как JsonPath. Это синтаксис при котором погружение на внутренний уровень происходит при помощи символа . (точка)

Вы можете использовать этот синтаксис в названиях параметров чтобы задавать значения для параметров внутренних уровней.

Напрмер у нас есть вот такой JSON-массив (объект) ↓

{
    "sign": "d1616887f87720bd4c2f375c6332dd7634a0",
    "data": {
        "date": "2019-11-14T13:02:01+03:00",
        "order_id": "123456",
        "order_num": "1234567-0-12345-0",
        "sum": "1000.00",
        "user": {
        	"name": "Олександр Мойсеюк",
        	"phone":"+123456789",
        	"email":"[email protected]"
        }
    }
    "array":[
    	"value 1",
    	"value 2",
    	"value 3"
    ]
}

Зададим для него несколько значений:

• sign => d1616887f87720bd4c2f375c6332dd7634a0.
• data.order_num => 1234567-0-12345-0.
• data.user.name => Олександр Мойсеюк.
• data.user.phone => +123456789.
• array.0 => value 1.

Как вы могли заметить, всё довольно просто. Как только вы, проходя по массиву, вместо значения в кавычках натыкаетесь на {, то погружаетесь внутрь массива = на уровень глубже. И если name находится в асоциативном массиве user, а user в свою очередь находится в массиве data, то путь, ясное дело, будет выглядеть: data.user.name.

Я не зря выделил слово «асоциативный» в предыдущем абзаце. Проблемы с пониманием у вас могут возникнуть при изменении (или получении) значений параметров самых обычных массивов (обычных списков через запятую).

Дело в том, что там тоже есть названия параметров (точнее, индексы элементов массива). Но они стандартные и спрятанные. Это числа (порядковые номера), порядок которых начинается с 0. Вот так и выходит, что первый элемент — 0, второй — 1, третий — 2 и т. д.

При использовании метода POST JSON (или следующих) возможно вам нужно будет передавать большие и сложные JSON-массивы. Чтобы облегчить себе жизнь вы можете воспользоваться действием «Сменить ответ сервера».
Просто закиньте туда текст (объект / массив) в формате JSON и переключите в данном действии метод на POST JSON (или следующие). Автопилот сам подтянет массив и подставит в запрос.

При этом если передать еще вместе с этим несколько параметров, то они реккурсивно перезапишут значения «ответа сервера» при запросе.

Получение и использование ответа

Вы можете использовать переменную %response% в следующих действиях команды. Ее значение — это ответ сервиса / сайта, на который был отправлен запрос. В виде строки без каких либо преобразований.

Важно! Переменная доступна только в команде содержащей действие «Отправить запрос» и только в действиях которые расположены после упомянутого (ниже). Также имейте в виду, что многие действия (например «Отправить сообщение») имеют свой %response%, поэтому перезаписывают предыдущий!

Если сервис отвечает массивом в JSON формате (именно так чаще всего и делают), значение конкретного элемента массива (даже многомерного) можно получить при помощи функции {get_var}, или её альтернативы (прописать путь после точки сразу внутри %response%) например:

%response.result.some_field.value%

или старый более громоздкий (старый) вариант: 
{get_var}result.some_field.value|json|%request_response%{/get_var}

Чтобы скопировать переменную, можете просто кликнуть по ней в блоке данного действия (она в само низу блока находится)

Отправка запроса на произвольный порт

Для смены порта достаточно просто прописать его стандартным образом к ссылке. Например так: ↓

Вопросы и пожелания можно писать в комментариях к этому посту.