Время на прочтение9 мин
Количество просмотров223K
Curl (client URL) — это инструмент командной строки на основе библиотеки libcurl для передачи данных с сервера и на сервер при помощи различных протоколов, в том числе HTTP, HTTPS, FTP, FTPS, IMAP, IMAPS, POP3, POP3S, SMTP и SMTPS. Он очень популярен в сфере автоматизации и скриптов благодаря широкому диапазону функций и поддерживаемых протоколов. В этой статье мы расскажем, как использовать curl в Windows на различных примерах.
▍ Установка в Windows
Во всех современных версиях Windows, начиная с Windows 10 (версия 1803) и Server 2019, исполняемый файл curl поставляется в комплекте, поэтому ручная установка не требуется. Чтобы определить местоположение curl и его версию в системе, можно использовать следующие команды:
where curl
curl --version
Определение местоположения и версии curl в Windows
Команда curl —version также выводит список протоколов и функций, поддерживаемых текущей версией curl. Как видно из показанного выше скриншота, к использованию встроенной утилиты curl всё готово. Если вместо этого отображается сообщение об ошибке, curl может быть недоступен потому, что вы используете более раннюю версию Windows (например, Windows 8.1 или Server 2016). В таком случае вам потребуется установить curl в Windows вручную.
▍ Синтаксис curl
Команда curl использует следующий синтаксис:
curl [options...] [url]Инструмент поддерживает различные опции, которые мы рассмотрим ниже. Как и в любом инструменте командной строки, вы можете использовать для получения справки команду curl —help.
Получение справки при помощи команды curl
Для получения подробной справки можно использовать команду curl —help all. Справка разделена на категории, поэтому при помощи curl —help category можно просмотреть все темы.
Ознакомившись с синтаксисом curl, давайте рассмотрим различные способы применения этого инструмента на примерах.
▍ HTTP-запрос GET
При использовании curl с URL и без указания опций запрос по умолчанию использует метод GET протокола HTTP. Попробуйте выполнить такую команду:
curl https://4sysops.comПриведённая выше команда по сути эквивалентна curl —request GET 4sysops.com, отправляющей запрос GET к 4sysops.com по протоколу HTTPS. Чтобы указать версию протокола HTTP (например, http/2), используйте опцию —http2:
curl --http2 https://4sysops.comВ случае URL, начинающихся с HTTPS, curl сначала пытается установить соединение http/2 и автоматически откатывается к http/1.1, если это не удаётся. Также он поддерживает другие методы, например, HEAD, POST, PUT и DELETE. Для использования этих методов вместе с командой curl нужно указать опцию —request (или -X), за которой следует указание метода. Стоит заметить, что список доступных методов зависит от используемого протокола.
▍ Получение информации об удалённом файле
Если вы администратор, то иногда вам могут быть интересны только заголовки HTTP. Их можно получить при помощи опции —head (или -I). Иногда URL может перенаправлять пользователя в другую точку. В таком случае опция —location (или -L) позволяет curl выполнять перенаправления. Также можно использовать —insecure (или -k), чтобы разрешить незащищённые подключения и избежать ошибок с сертификатом TLS в случае, если целевой URL использует самоподписанный сертификат. Пользуйтесь этой опцией только при абсолютной необходимости. Все эти три опции можно скомбинировать в одну краткую запись, как показано в следующей команде:
curl -kIL 4sysops.com
Опции просмотра заголовков запросов, включения незащищённого соединения и использования перенаправлений
Как можно заметить, такая краткая запись особенно полезна для комбинирования нескольких опций. Приведённая выше команда по сути эквивалентна команде curl —insecure —head —location 4sysops.com.
Опция —head (или -I) также даёт основную информацию об удалённом файле без его скачивания. Как показано на скриншоте ниже, при использовании curl с URL удалённого файла он отображает различные заголовки, дающие информацию об удалённом файле.
curl -IL https://curl.se/windows/dl-7.85.0_5/curl-7.85.0_5-win64-mingw.zip
Использование curl для просмотра основной информации удалённых файлов
Заголовок Content-Length обозначает размер файла (в байтах), Content-Type сообщает о типе медиафайла (например, image/png, text/html), Server обозначает тип серверного приложения (Apache, Gunicorn и так далее), Last-Modified показывает дату последнего изменения файла на сервере, а заголовок Accept-Ranges обозначает поддержку частичных запросов для скачивания от клиента, что по сути определяет возможность продолжения прерванной загрузки.
▍ Скачивание файла
Для скачивания файла и сохранения с тем же именем, что и на сервере, можно использовать curl с опцией —remote-name (или -O). Показанная ниже команда скачивает последнюю версию curl для Windows с официального сайта:
curl -OL https://curl.se/windows/latest.cgi?p=win64-mingw.zip
Скачивание файла с именем по умолчанию и индикатором прогресса
При необходимости для нахождения ресурса добавляется опция -L, разрешающая перенаправления. Если нужно сохранить файл с новым именем, используйте опцию —output (или -o). Кроме того, при использовании команды curl в скрипте может понадобиться отключить индикатор прогресса, что можно сделать при помощи опции —silent (или -s). Эти две опции можно скомбинировать:
curl -sLo curl.zip https://curl.se/windows/latest.cgi?p=win64-mingw.zip
Скачивание файла без индикатора и сохранение под произвольным именем
▍ Продолжение прерванного скачивания
Наличие Accept-Ranges: bytes в заголовке ответа в буквальном смысле обозначает, что сервер поддерживает скачивания с возможностью продолжения. Чтобы продолжить прерванное скачивание, можно использовать опцию —continue-at (или -C), получающую смещение (в байтах). Обычно указывать смещение непросто, поэтому curl предоставляет простой способ продолжения прерванной загрузки:
curl -OLC - https://releases.ubuntu.com/22.04/ubuntu-22.04.1-desktop-amd64.isoПродолжение прерванного скачивания
Как видно из скриншота, я скачивал iso-файл Ubuntu, но скачивание было прервано. Затем я снова запустил команду curl с опцией -C, и передача продолжилась с того диапазона байтов, на котором была прервана. Знак минус (—) рядом с -C позволяет curl автоматически определить, как и где продолжить прерванное скачивание.
▍ Аутентификация с Curl
Также Curl поддерживает аутентификацию, что позволяет скачать защищённый файл, предоставив учётные данные при помощи опции —user (or -u), принимающей имя пользователя и пароль в формате username:password. Если не вводить пароль, curl попросит ввести его в режиме no-echo.
curl -u surender -OL https://techtutsonline.com/secretFiles/sample.zip
Скачивание файла с аутентификацией по имени пользователя и паролю
Если вы используете Basic authentication, то необходимо передать имя пользователя и пароль, а значит, воспользоваться защищённым протоколом наподобие HTTPS (вместо HTTP) или FTPS (вместо FTP). Если по каким-то причинам приходится использовать протокол без шифрования, то убедитесь, что вы используете способ аутентификации, не передающий учётные данные в виде простого текста (например, аутентификацию Digest, NTLM или Negotiate).
Также curl поддерживает использование файлов конфигурации .curlrc, _curlrc и .netrc, позволяющих задавать различные опции curl в файле, а затем добавлять файл в команду при помощи опции curl —config (или curl -K), что особенно полезно при написании скриптов.
▍ Выгрузка файла
Опция —upload-file (или -T) позволяет выгружать локальный файл на удалённый сервер. Показанная ниже команда выгружает файл из локальной системы на удалённый веб-сервер по протоколу FTPS:
curl -kT C:\Users\Surender\Downloads\sample1.zip -u testlab\surender ftps://192.168.0.80/awesomewebsite.com/files/
Выгрузка файла на удалённый сервер
Опция -k добавляется для устранения проблем с сертификатами на случай, если веб-сервер использует самоподписанный сертификат. Наклонная черта в конце URL сообщает curl, что конечная точка является папкой. Можно указать несколько имён файлов, например «{sample1.zip,sample2.zip}». Ниже показано, как с помощью одной команды curl можно выгрузить на сервер несколько файлов:
curl -kT sample[1-5].zip -u testlab\surender ftps://192.168.0.80/awesomewebsite.com/files/
Выгрузка нескольких файлов на сервер
▍ Последовательность команд
Как говорилось ранее, curl поддерживает различные методы в зависимости от используемого протокола. Дополнительные команды можно отправлять при помощи —quote (или -Q) для выполнения операции до или после обычной операции curl. Например, можно скачать файл с удалённого сервера по протоколу FTPS и удалить файл с сервера после успешного скачивания. Для этого нужно выполнить следующую команду:
curl -u testlab\surender -kO "ftps://192.168.0.80/awesomewebsite.com/files/sample1.zip" -Q "-DELE sample1.zip"
Удаление файла после успешного скачивания
В показанном выше примере я скачал файл sample1.zip с FTPS-сервера при помощи опции -O. После опции -Q я добавил минус (-) перед командой DELE, что заставляет curl отправить команду DELE sample1.zip сразу после успешного скачивания файла. Аналогично, если вы хотите отправить команду на сервер до выполнения операции curl, используйте плюс (+) вместо минуса.
▍ Изменение user-agent
Информация user-agent сообщает серверу тип клиента, отправляющего запрос. При отправке запроса curl на сервер по умолчанию используется user-agent curl/<version>. Если сервер настроен так, чтобы блокировать запросы curl, можно задать собственный user-agent при помощи опции —user-agent (или -A). Показанная ниже команда отправляет стандартный user-agent Google Chrome:
curl -kIA "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/106.0.0.0" https://awesomewebsite.com/files/secretFile.zip
Использование собственного user-agent с командой curl, чтобы избежать блокировки сервером
На показанном выше скриншоте видно, что обычный запрос curl был отклонён веб-сервером (с ответом 403 Forbidden), но при передаче другого user-agent запрос выполняется успешно, возвращая ответ 200 OK.
▍ Отправка куки
По умолчанию запрос curl не отправляет и не сохраняет куки. Для записи куки можно использовать опцию —cookie-jar (или -c), а отправить куки можно опцией —cookie (or -b):
curl -c /path/cookie_file https://awesomewebsite.com/
curl -b /path/cookie_file https://awesomewebsite.com/Первая команда записывает файл куки, а вторая отправляет куки с запросом curl. Также можно отправить куки в формате ‘name = value’:
curl -b 'session=abcxyz' -b 'loggedin=true' http://echo.hoppscotch.io
Отправка нескольких куки командой curl
Я воспользовался веб-сайтом echo.hoppscotch.io для демонстрации заголовков HTTP-запросов, которые обычно невидимы клиентам, отправляющим запрос. Если вы не хотите пользоваться этим веб-сайтом, то можете применить опцию –verbose (или -v) для отображения запроса в сыром виде (который отображает и заголовки запросов).
▍ Использование прокси-сервера
Если вы пользуетесь прокси-сервером для подключения к интернету, в curl можно указать прокси опцией —proxy (или -x). Если прокси-сервер требует аутентификации, то добавьте —proxy-user (или -U):
curl -x 192.168.0.250:8088 -U username:password https://awesomewebsite.com/Прокси-сервер указывается в формате server:port, а пользователь прокси — в формате username:password. Можно не вводить пароль пользователя прокси, тогда curl попросит ввести его в режиме no-echo.
Использование прокси-сервера и аутентификации
▍ Дополнительные заголовки запросов
Иногда вместе с запросом к серверу необходимо отправить дополнительную информацию. В curl это можно сделать при помощи —header (или -H), как показано в следующей команде:
curl -vkIH "x-client-os: Windows 11 Enterprise (x64)" https://awesomewebsite.com
Указание дополнительных заголовков для запроса curl
Можно отправлять любую информацию, недоступную через стандартные заголовки HTTP-запросов. В этом примере я отправил название своей операционной системы. Также я добавил опцию -v для включения verbose-вывода, отображающего дополнительный заголовок, отправляемый вместе с каждым моим запросом curl.
▍ Отправка электронного письма
Так как curl поддерживает протокол SMTP, его можно использовать для отправки электронного письма. Показанная ниже команда позволяет отправить электронное письмо при помощи curl:
curl --insecure --ssl-reqd smtps://mail.yourdomain.com –-mail-from sender@yourdomain.com –-mail-rcpt receiver@company.com --user sender@yourdomain.com --upload-file email_msg.txt
Отправка электронного письма командой curl
Давайте вкратце перечислим использованные здесь опции:
- Опция —insecure (или -k) используется, чтобы избежать ошибки сертификата SSL. Мы уже применяли её ранее.
- Опция —ssl-reql используется для апгрейда соединения передачи простого текста до зашифрованного соединения, если оно поддерживается SMTP-сервером. Если вы уверены, что ваш SMTP-сервер поддерживает SSL, то можно использовать непосредственно имя сервера smtps (например, smtps://smtp.yourdomain.com), как показано на скриншоте.
- Опция —mail-from используется для указания адреса электронной почты отправителя.
- Опция mail-rcpt указывает адрес электронной почты получателя.
- Опция —user (или -u) отправляет имя пользователя для аутентификации, оно должно совпадать с адресом mail-from, потому что в противном случае письмо может быть отклонено или помечено как спам.
- Опция —upload-file (или -T) используется для указания файла, в котором находится отправляемое письмо.
На скриншоте ниже показано письмо, полученное мной во входящие:
Просмотр письма, отправленного с помощью curl
Это всего лишь несколько примеров использования curl — на самом деле их гораздо больше. Я настоятельно рекомендую проверить справку по curl и поэкспериментировать с ней.
А вы используете curl? И если да, то для чего?
Telegram-канал с полезностями и уютный чат
#статьи
-
0
Осваиваем швейцарский нож для взаимодействия с сетевыми протоколами.
Иллюстрация: Оля Ежак для Skillbox Media
Филолог и технарь, пишет об IT так, что поймут даже новички. Коммерческий редактор, автор технических статей для vc.ru и «Хабра».
Curl (Client URL, или «Клиентский URL») — это инструмент командной строки, предназначенный для передачи данных по различным сетевым протоколам. Он помогает разработчикам, системным администраторам и другим специалистам выполнять HTTP-запросы, загружать файлы, тестировать API и решать множество задач по отладке веб-приложений.
Давайте сразу проверим Curl в действии. Для этого откройте на своём компьютере терминал, скопируйте следующую команду и нажмите Enter:
curl https://httpbin.org/ip
После ввода команды Curl отправит GET-запрос на сервис httpbin.org, который обработает запрос и вернёт ваш текущий IP-адрес в формате JSON:
C:\Users\user>curl https://httpbin.org/ip
{
"origin": "95.165.134.78"
}
Похожим образом Curl позволяет легко взаимодействовать с различными API и получать нужную информацию. Теперь поговорим об этом подробней.
Содержание
- Описание Curl
- Установка и запуск
- Синтаксис команд
- Использование Curl
- GET-запрос
- POST-запрос
- Скачивание файла
- Вывод заголовков
- Аутентификация
- Следование редиректам
- Загрузка файла
- Подборка ресурсов для работы с Curl
В 1997 году шведский программист Даниэль Стенберг разработал утилиту httpget — инструмент для загрузки валютных курсов через IRC-бота. Если вы хотели узнать текущий курс доллара, процесс выглядел примерно так:
- Бот подключался к сайту с актуальными курсами валют.
- Программа httpget загружала страницу и извлекала нужные данные о курсе доллара. Например, 1 USD = 30 RUB ?
- Затем она передавала эту информацию IRC-боту, который отвечал на ваш запрос в IRC-чате.
Проект привлёк внимание многих разработчиков, поскольку решал актуальную проблему того времени — загрузку данных из интернета. До появления httpget разработчикам приходилось создавать отдельные скрипты для каждого случая получения данных. Программа позволяла получить нужную информацию всего несколькими простыми командами.
Со временем проект HTTPget сменил название на Urlget, а затем на Curl. Сегодня Curl — это кросс-платформенная утилита командной строки, которая позволяет передавать или загружать данные с сервера, устанавливая подключение через различные протоколы: HTTP, HTTPS, FTP, SFTP, TFTP, SCP, Telnet, DICT, LDAP, POP3, IMAP, SMTP и другие.
Сейчас, помимо Curl, существуют и другие инструменты для работы с HTTP-запросами. Вот некоторые из популярных:
- Wget — утилита командной строки для загрузки файлов, удобная для рекурсивной загрузки и работы с FTP-протоколом.
- Postman — графический инструмент для тестирования API. Он лучше Curl подходит для сложных запросов и визуализации ответов, однако уступает в гибкости при автоматизации задач.
- HTTPie — это современный аналог Curl с упрощённым синтаксисом, цветным выводом результатов и менее широким набором функций.
- Axios — это JavaScript-библиотека для выполнения HTTP-запросов. Она удобна для веб-разработки, но ограничена средой JavaScript: Axios можно использовать только в браузерах для HTTP-запросов на стороне клиента и в Node.js для запросов на стороне сервера.
Несмотря на множество альтернатив, Curl остаётся популярным инструментом благодаря своей универсальности, широкой поддержке протоколов и кросс-платформенности. Давайте перейдём к его установке.
? Возможности Curl и других бесплатных инструментов для передачи данных: сравнительная таблица
В современных операционных системах утилита Curl обычно установлена по умолчанию. Для проверки откройте терминал и введите команду:
curl --version
Должен отобразиться номер версии и поддерживаемые протоколы:
Скриншот: Windows 10 / Skillbox Media
Если Curl не установлен, в терминале появится сообщение об ошибке:
'curl' is not recognized as an internal or external command,
operable program or batch file.
Если вы видите подобное сообщение, значит, программа Curl недоступна и её нужно загрузить. Способ установки зависит от операционной системы.
Если у вас macOS, установите менеджер пакетов Homebrew и выполните в терминале следующую команду:
brew install curl
После завершения установки проверьте версию Curl:
curl --version
Если у вас Linux, то способ установки будет зависеть от дистрибутива. Для Ubuntu или Debian выполните последовательно следующие команды:
sudo apt-get update sudo apt-get install curl
Для Fedora:
sudo dnf install curl
Для CentOS или RHEL:
sudo yum install curl
Для Arch Linux:
sudo pacman -S curl
После установки проверьте версию Curl командой:
curl --version
Если у вас Windows 10 или 11, откройте PowerShell или командную строку от имени администратора и установите Curl через менеджер пакетов:
winget install curl
После установки перезапустите PowerShell или командную строку и проверьте установку:
curl --version
Если у вас Windows 7, 8 или 8.1, скачайте архив с утилитой с сайта curl.se через браузер Pale Moon. Современные браузеры могут не поддерживаться устаревшими версиями Windows или блокировать загрузку по соображениям безопасности. Pale Moon — это легковесный браузер, позволяющий загружать сторонние файлы без подобных ограничений.
После загрузки распакуйте папку из архива, переименуйте её в Curl и поместите в удобное место. Например, наша папка находится по пути: C:/Program Files/Curl. Затем откройте папку Curl, перейдите в подпапку bin и скопируйте полный путь к этому каталогу:
Не выходя из проводника, щёлкните правой кнопкой мыши по разделу Компьютер и в появившемся меню выберите пункт Свойства:
Откроется информационное окно со сведениями о вашем компьютере. В левой панели щёлкните на пункт Дополнительные параметры системы:
В открывшемся окне нажмите кнопку Переменные среды:
В разделе Системные переменные найдите пункт Path, выделите его и нажмите кнопку Изменить:
Появится окно Изменение системной переменной, в котором вам нужна строка Значение переменной. Поставьте точку с запятой в конце текущего значения и сразу после него без пробела вставьте скопированный путь к каталогу. Нажмите ОК во всех открытых окнах и перезагрузите компьютер:
После перезагрузки откройте командную строку и выполните проверку:
curl --version
Если отобразилась версия утилиты, значит, всё правильно. Если появилось сообщение об ошибке или команда не распознана, попробуйте следующее:
- Проверьте путь к Curl в разделе Переменные среды Path — убедитесь, что вы добавили его согласно инструкции.
- Перезапустите командную строку или PowerShell.
- Если проблема сохраняется, перезагрузите компьютер ещё раз.
- Если ничего не помогло, повторите процедуру установки.
Общий синтаксис Curl-команд выглядит следующим образом:
curl [параметры] [URL]
Базовые команды можно выполнять без параметров по указанию URL-адреса. Например, с помощью следующей команды вы сможете загрузить HTML-структуру выбранного сайта в свой терминал:
# Замените example.com на адрес любого сайта
curl https://www.example.com
Хотя параметры необязательны, они позволяют точно настроить поведение Curl и расширить его функциональность. Вот несколько частых параметров:
- -O: сохраняет скачиваемый файл с его оригинальным именем;
- -o: сохраняет файл с указанным вами именем;
- -I: получает только HTTP-заголовки ответа сервера;
- -L: следует редиректам. Например, если сайт перенаправляет запрос с http://example.com на https://example.com, curl с параметром -L автоматически выполнит это перенаправление.
Параметры всегда должны располагаться перед URL и их можно комбинировать. Вот пример комбинированной команды:
curl -LO <https://example.com/file.zip>
# Эта команда следует редиректам (-L) и сохраняет файл с оригинальным именем (-O)
Для просмотра всех доступных параметров используйте команду:
curl --help all
В следующем разделе мы рассмотрим основные сценарии использования Curl и попрактикуемся применять команды с различными параметрами.
Рассмотрим команды для основных сценариев использования Curl:
- GET-запрос: curl https://example.com
- POST-запрос: curl -X POST -d «data» https://example.com
- Скачивание файла: curl -O https://example.com/file.zip
- Вывод заголовков: curl -I https://example.com
- Аутентификация: curl -u username:password https://example.com
- Следование редиректам: curl -L https://example.com
- Загрузка файла: curl -T file.txt https://example.com/upload
Для закрепления этих команд воспользуемся сервисом JSONPlaceholder. Это бесплатный онлайн REST API, предоставляющий фиктивные данные для обучения и тестирования. Данный ресурс позволяет практиковаться в работе с API без настройки собственного сервера.
Эта команда позволяет получать данные с сервера без их изменения. С её помощью вы можете просматривать содержимое ресурса, проверять доступность API или проводить отладку приложения.
Отправим GET-запрос для получения информации о посте:
curl https://jsonplaceholder.typicode.com/posts/1
В результате мы получим примерно такой JSON-объект:
{
"userId": 1,
"id": 1,
"title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
"body": "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto"
}
В ответе содержится информация о посте: идентификатор пользователя (userId), идентификатор поста (id), заголовок (title) и содержание (body). Поскольку сервис JSONPlaceholder предоставляет фиктивные данные, содержимое вашего поста может отличаться от приведённого примера.
Эта команда применяется для передачи данных на сервер при заполнении веб-форм, отправке сообщений или создании новых записей в базе данных.
Создадим новый пост и отправим на сервер следующие JSON-данные:
{
"title": "Заголовок поста",
"body": "Здесь мы добавляем содержание поста",
"userId": 1
}
Выполним Curl-команду:
curl -X POST -H "Content-Type: application/json" -d "{\"title\": \"Заголовок поста\", \"body\": \"Здесь мы добавляем содержание поста\", \"userId\": 1}" "https://jsonplaceholder.typicode.com/posts"
После обработки запроса сервер вернёт ответ, в котором содержится информация о созданном посте с его уникальным идентификатором:
{
"title": "Заголовок поста",
"body": "Здесь мы добавляем содержание поста",
"userId": 1,
"id": 101
}
Эта команда позволяет сохранить полученные данные в файл на вашем компьютере. Это удобно при работе с большими объёмами данных или когда требуется дальнейшая обработка полученной информации.
Сохраним JSON-ответ в файл post.json в нашей текущей директории:
curl -o post.json https://jsonplaceholder.typicode.com/posts/1
Результат вывода:
C:\Users\user>curl -o post.json https://jsonplaceholder.typicode.com/posts/1 % Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 100 292 100 292 0 0 380 0 --:--:-- --:--:-- --:--:-- 382
Файл post.json сохранён в директории C:\Users\user. Вывод также содержит статистику загрузки данных:
- Общий размер файла: 292 байта.
- Процент загрузки: 100%.
- Скорость загрузки: 380 байт/с.
- Время выполнения: мгновенно (—:—:—).
Эта команда позволяет получить заголовки HTTP-ответов без тела сообщения. Это полезно для проверки статуса ответа, типа содержимого, заголовков кэширования и других метаданных с запрашиваемого ресурса.
Отправим запрос для получения HTTP-заголовков из нашего сервиса:
curl -I https://jsonplaceholder.typicode.com/posts/1
Пример ответа:
HTTP/1.1 200 OK Date: Wed, 23 Oct 2024 07:34:44 GMT Content-Type: application/json; charset=utf-8 Content-Length: 292 Connection: keep-alive Report-To: {"group":"heroku-nel","max_age":3600,"endpoints":[{"url":"https://nel.heroku.com/reports?ts=1729551695&sid=e11707d5-02a7-43ef-b45e-2cf4d2036f7d&s=T06zv%2Bip6vp%2FcW6OahKqDwFYY1PQhd6eXYmDv1DMf3g%3D"}]} Reporting-Endpoints: heroku-nel=https://nel.heroku.com/reports?ts=1729551695&sid=e11707d5-02a7-43ef-b45e-2cf4d2036f7d&s=T06zv%2Bip6vp%2FcW6OahKqDwFYY1PQhd6eXYmDv1DMf3g%3D Nel: {"report_to":"heroku-nel","max_age":3600,"success_fraction":0.005,"failure_fraction":0.05,"response_headers":["Via"]} X-Powered-By: Express X-Ratelimit-Limit: 1000 X-Ratelimit-Remaining: 999 X-Ratelimit-Reset: 1729551747 Vary: Origin, Accept-Encoding Access-Control-Allow-Credentials: true Cache-Control: max-age=43200 Pragma: no-cache Expires: -1 X-Content-Type-Options: nosniff Etag: W/"124-yiKdLzqO5gfBrJFrcdJ8Yq0LGnU" Via: 1.1 vegur CF-Cache-Status: HIT Age: 1983 Accept-Ranges: bytes Server: cloudflare CF-RAY: 8d700bdd4a385b4f-VIE alt-svc: h3=":443"; ma=86400 server-timing: cfL4;desc="?proto=TCP&rtt=25362&sent=5&recv=6&lost=0&retrans=0&sent_bytes=3130&recv_bytes=510&delivery_rate=144240&cwnd=252&unsent_bytes=0&cid=748ae82f39ab1e32&ts=71&x=0"
Этот вывод содержит важную информацию для анализа ответов API и отладки запросов. В нём есть статус ответа (200 OK), тип содержимого (например, application/json), длина контента, а также заголовки кэширования, безопасности и ограничения скорости. Такие сведения помогают разработчикам лучше понять взаимодействие с сервером и выявить потенциальные проблемы.
Аутентификация обеспечивает доступ к частным или защищённым ресурсам. Сервис JSONPlaceholder не требует аутентификации, однако вы можете выполнить команду, демонстрирующую передачу данных при работе с защищёнными API. В нашем примере сервер вернёт список постов, а в реальном сценарии такой запрос открыл бы доступ к закрытому ресурсу:
curl -u username:password https://jsonplaceholder.typicode.com/posts
Редиректы полезны при работе с URL-адресами, которые могут перенаправлять на другие ресурсы. JSONPlaceholder не использует редиректы, поэтому команда ниже эмулирует этот процесс, позволяя Curl автоматически следовать по цепочке переадресаций сайтов. При реальном запросе вы получите конечный ресурс после различных перенаправлений:
curl -L https://jsonplaceholder.typicode.com/posts/1
Вы можете отправлять POST-запросы для передачи больших объёмов данных или заранее подготовленной информации. Создадим файл newpost.json и сразу отправим его содержимое на JSONPlaceholder.
Добавим кодировку UTF-8, чтобы избежать ошибок при отображении данных на русском языке:
chcp 65001
Создадим файл newpost.json:
echo {"title": "Загруженный пост", "body": "Содержимое поста", "userId": 1} > newpost.json
curl -X POST -H "Content-Type: application/json" -d @newpost.json https://jsonplaceholder.typicode.com/posts
Получаем ответ от сервера, подтверждающий выполнение запроса:
C:\Users\user>curl -X POST -H "Content-Type: application/json" -d @newpost.json https://jsonplaceholder.typicode.com/posts { "title": "Загруженный пост", "body": "Содержимое поста", "userId": 1, "id": 101 }
Вы познакомились с возможностями Curl, и, если считаете, что этот инструмент может пригодиться в работе, рекомендуем следующие ресурсы:
- Everything curl — бесплатная онлайн-версия книги от создателя Curl, в которой он подробно рассказывает об устройстве технологии.
- Официальная документация с описанием всех опций и команд Curl.
- Блог Даниэля Стенберга, где он часто пишет о Curl и смежных технологиях.
- GitHub-репозиторий Curl — позволяет отслеживать разработку проекта, сообщать о проблемах и вносить свой вклад в развитие Curl.
- Curl Сookbook — сборник практических примеров использования Curl для решения различных задач.
Научитесь: Старт в DevOps: системное администрирование для начинающих
Узнать больше
If you’ve ever wanted to extract data from websites, mastering cURL is an essential skill. Whether you’re troubleshooting a server issue or performing web scraping, using cURL to send GET requests offers a powerful and flexible way to interact with APIs and web pages right from your terminal.
In this article, we’ll dive into the fundamentals of curl GET requests, showing you how to handle URL structures, parameters, and headers for optimal results. Along the way, you’ll learn practical examples and how to troubleshoot common issues with cURL.
Let’s get started and unlock the potential of cURL for your web projects.
What is cURL?
cURL (short for «client URL») is an open-source command-line tool used to transfer data to or from a server. It supports numerous protocols such as HTTP, HTTPS, FTP, and more. When it comes to web scraping or making simple HTTP requests, cURL is a powerful, lightweight option.
You can use cURL to perform various types of requests, such as sending a GET request to retrieve data from a server. Moreover, it allows handling complex requests with the ability to add parameters, headers, and even authentication tokens.
Why Use cURL for Web Scraping?
cURL is particularly useful for web scraping because of its simplicity and flexibility. With cURL, you can interact with websites directly from your terminal, allowing you to:
- Send HTTP requests (including cURL GET, POST, PUT, DELETE).
- Handle cURL with headers and cURL parameters for more refined control over requests.
- Download files or save output.
- Perform authentication, including cURL basic auth and proxy requests.
Furthermore, cURL supports HTTP/2 and can be integrated with tools like curl-impersonate, which allows your requests to better mimic browser-like behavior by adjusting the connection fingerprint. This helps bypass scraper blocking by mimicking browser-like TLS and HTTP2 configurations, avoiding detection from anti-scraping tools.
You can learn more about how Curl Impersonate Prevents Scraper Blocking in our dedicated article:
Use Curl Impersonate to scrape as Chrome or Firefox
Learn how Curl Impersonate can help you bypass scraper blocking by mimicking browser-like TLS and HTTP2 configurations, avoiding detection from anti-scraping tools.
GET Requests Overview
Before we dive into the mechanics of curl GET requests, let’s briefly cover HTTP methods. The most commonly used methods are:
- GET: Used to request data from a server (e.g., download or view content) using a curl GET request.
- POST: Sends data to a server (e.g., form submissions).
- PUT: Updates or replaces data.
- DELETE: Deletes data from a server.
In GET requests, cURL parameters are sent as part of the URL, making them perfect for scenarios where you need to retrieve data from a website or API.
Setting Up cURL
cURL is typically pre-installed on most operating systems, making it easy to get started with curl GET requests and other types of HTTP requests. However, it’s always good practice to ensure you have the latest version installed. To check if you have cURL installed and verify the version, use this terminal command:
curl --version
This command will display the current version of cURL installed on your system. If it’s not installed, follow the instructions below to install cURL on different operating systems.
Linux
On most Linux distributions, you can install cURL by running the following terminal command:
sudo apt install curl
This will install cURL and allow you to send HTTP requests, such as a GET request with cURL, directly from the terminal.
MacOS
If you’re using macOS, the easiest way to install cURL is through the Homebrew package manager. Run this command in your terminal:
brew install curl
Once installed, you can start using cURL to send GET requests, work with cURL headers, and handle cURL parameters for more advanced use cases.
Windows
For Windows users, cURL can be downloaded from the official cURL website, or you can use the Chocolatey package manager. Using Chocolatey, install cURL with this command:
choco install curl
After installation, you can open your command prompt or PowerShell and start making cURL requests, including the curl GET command, without needing a separate GUI tool.
Even if you have curl installed Keeping cURL updated ensures that you’re able to use the latest features, such as enhanced support for cURL with headers, cURL multiple headers, or handling new protocols and security standards. This is particularly important when working with curl GET requests for APIs or web scraping, where newer versions may offer better compatibility and performance.
Once cURL is installed and ready, you can start using it to interact with APIs or websites, including sending GET requests, which is one of the most common operations with cURL. Let’s now take a look at how to use cURL to send GET requests.
Sending a GET Request with cURL
The curl GET command is simple and widely used to retrieve data from a server. The basic syntax for sending a GET request with cURL is:
curl [URL]
For example, to perform a curl GET request from a simple API endpoint like httpbin.dev/get, you can use:
curl https://httpbin.dev/get
The response from this API will look something like:
{
"args": {},
"headers": {
"Host": "httpbin.dev",
"User-Agent": "curl/7.68.0",
"Accept": "*/*"
},
"url": "https://httpbin.dev/get"
}
This cURL example shows the data returned by the server, including the headers and the URL used.
Adding URL Parameters
When sending a GET request with cURL, you often need to pass extra data to the server, such as search terms, filters, or pagination. These are called URL parameters, which are added to the request as part of the URL in the form of query strings.
The query string is a set of key-value pair parameters after the ? character in an URL. The structure for adding cURL parameters looks like this:
curl https://httpbin.dev/get?param1=value1¶m2=value2
In the example above, param1=value1 and param2=value2 are query strings, separated by an & symbol and preceded by a ? in the URL. Query strings are essential when you need to send specific data to a cURL API endpoint, allowing the server to interpret and return the relevant response based on the parameters you provide.
Use Case: Pagination and Filtering
In real-world scenarios, you can use curl with an API to retrieve paginated data, you might need to send curl GET request with parameters for pagination or filters. Here’s curl GET example of adding pagination parameters to curl GET request example:
curl "https://web-scraping.dev/products?page=2&order=desc"
This request uses page=2 parameter to indcate the 2nd results page and order=desc to indicate result ordering.
Next, let’s take a look at value encoding which is often required for correct GET requests.
Handling URL Encoding
When your URL parameter values contain non-url safe characters, you’ll need to encode them into a URL safe format — this is called URL encoding.
If you don’t properly encode special characters, your request may fail or return incorrect results. This is because special characters (such as &, =, ?, and spaces) are reserved in URLs and are used for specific purposes like separating query string parameters. For instance, a space would be misinterpreted as a separator between parameters if not encoded as %20:
curl "https://httpbin.dev/get?query=hello%20world"
In the above command, %20 represents a space character.
How to Perform URL Encoding
To avoid issues with special characters, always ensure your URL is encoded. Most programming languages, tools, and services offer built-in URL encoding functions. cURL does not automatically handle encoding, so you must encode any special characters manually. Here are some examples:
Python
Javascript
PHP
Ruby
Go
Rust
from urllib.parse import quote
quote("me&myself and I?")
'me%26myself%20and%20I%3F'
const originalString = "me&myself and I?";
const urlSafeString = encodeURIComponent(originalString);
console.log(urlSafeString); // Output: me%26myself%20and%20I%3F
<?php
$originalString = "me&myself and I?";
$urlSafeString = urlencode($originalString);
echo $urlSafeString; // Output: me%26myself+and+I%3F
?>
require 'uri'
original_string = "me&myself and I?"
url_safe_string = URI.encode(original_string)
puts url_safe_string # Output: me%26myself%20and%20I%3F
package main
import (
"fmt"
"net/url"
)
func main() {
originalString := "me&myself and I?"
urlSafeString := url.QueryEscape(originalString)
fmt.Println(urlSafeString) // Output: me%26myself%20and%20I%3F
}
use url::form_urlencoded;
fn main() {
let original_string = "me&myself and I?";
let url_safe_string = form_urlencoded::byte_serialize(original_string.as_bytes()).collect::<String>();
println!("{}", url_safe_string); // Output: me%26myself%20and%20I%3F
}
Automated URL Encoding with Scrapfly
Scrapfly offers a reliable solution to handle URL encoding and ensure your requests are correctly formatted, especially when dealing with web scraping tasks. You can use Scrapfly’s encoding tools to correctly URL encode in your browser:
When making HTTP requests, you may need to add custom cURL headers to provide additional information to the server.
Headers are key-value pairs that provide request meta dateails, such as:
- Who’s making the request?
User-Agent - The expected result format?
Accept - Authentication credentials?
Authorization - Many more.
In a curl GET request, headers can be vital for successful requests and missing values or misconfiguration can result in failed request or even client blocking.
To set headers in cURL, use the -H option. For example, to include multiple headers in your request, such as a User-Agent and Accept-Language, the command would look like this:
curl -H "User-Agent: Mozilla/5.0" -H "Accept-Language: en-US" https://httpbin.dev/get
This sends both custom headers with your request. If you want to verify that the headers were received, you can show response headers by including the -i option. The response might look like this:
{
"headers": {
"User-Agent": "Mozilla/5.0",
"Accept-Language": "en-US",
...
}
}
If you’re working with an API or server that requires a specific Host header, you can add it with the same -H option:
$ curl -H "Host: api.example.com" https://api.example.com/data
This ability to send multiple headers with cURL allows you to tailor your request to the server’s requirements and handle specific use cases like authentication or setting the expected response format.
When making a curl GET request, it’s often useful to see not just the body of the response but also the headers returned by the server. Headers provide key details such as the HTTP status code, content type, and caching rules. To show response headers in your curl request, use the -i option:
$ curl -i https://httpbin.dev/get
HTTP/2 200
access-control-allow-credentials: true
access-control-allow-origin: *
content-security-policy: frame-ancestors 'self' *.httpbin.dev; font-src 'self' *.httpbin.dev; default-src 'self' *.httpbin.dev; img-src 'self' *.httpbin.dev https://cdn.scrapfly.io; media-src 'self' *.httpbin.dev; script-src 'self' 'unsafe-inline' 'unsafe-eval' *.httpbin.dev; style-src 'self' 'unsafe-inline' *.httpbin.dev https://unpkg.com; frame-src 'self' *.httpbin.dev; worker-src 'self' *.httpbin.dev; connect-src 'self' *.httpbin.dev
content-type: application/json; encoding=utf-8
date: Thu, 03 Oct 2024 08:06:24 GMT
permissions-policy: fullscreen=(self), autoplay=*, geolocation=(), camera=()
referrer-policy: strict-origin-when-cross-origin
strict-transport-security: max-age=31536000; includeSubDomains; preload
x-content-type-options: nosniff
x-xss-protection: 1; mode=block
content-length: 589
...
This command will display both the response headers and the body, giving you critical insights into how the server processed your request. For example, you might want to inspect the curl GET status code to ensure the request was successful or check what content type the server is sending. This is especially useful when troubleshooting and debugging your curl get requests.
Saving Results to a File
To save the output of your curl GET request to a file, you can use the -o or --output flag:
curl -o output.txt https://httpbin.dev/get
This is particularly helpful when working with larger API responses or files that need to be reviewed later. For example, after using curl to request data from an API, you might want to save the result for further analysis or logging.
Proxy and Network Issues
If you are in a restricted network or need to route your curl GET request through a proxy, you can configure cURL to use a proxy server. This can be done using the -x option:
curl -x http://proxy.example.com:8080 https://httpbin.dev/get
This ensures that your requests are correctly routed through the desired network proxy. For more advanced setups and cURL examples involving proxies, you can consult the official documentation.
Troubleshooting Common Issues with curl GET Requests
When using cURL, you may encounter several common issues that can impact the success of your GET request. Let’s explore how to resolve some of these, from authentication problems to handling multiple headers.
Authentication Issues
Many APIs require authentication, and cURL supports different methods to handle these requirements. Whether you are using Basic Authentication or a token-based system, you can easily pass credentials with cURL.
Basic Authentication
For APIs using basic authentication, you can use curl with username and password authentication through the -u option followed by the username and password:
curl -u username:password https://httpbin.dev/basic-auth/username/password
This sends the credentials in the request header to authenticate your session.
Token Authentication
For APIs using token-based authentication, you can set the header to include the bearer token. This is an example of a curl GET request with headers for token authentication:
curl -H "Authorization: Bearer your_token_here" https://api.example.com/data
These cURL examples allow you to easily authenticate requests when accessing protected resources.
Handling Multiple Headers
When working with APIs, you might need to send multiple headers in your curl GET request. Headers such as User-Agent, Authorization, and Host are essential in many scenarios. You can use the -H option to set headers in cURL, adding as many as necessary for your request:
curl -H "User-Agent: Custom" -H "Authorization: Bearer your_token_here" -H "Host: api.example.com" https://api.example.com/data
In this example, we are setting a User-Agent, passing an authorization token, and specifying a curl host header. These headers give you flexibility when interacting with various APIs or services, enabling you to meet the server’s requirements for proper authentication and data handling.
Common cURL Errors
If you encounter issues like «Connection timed out» or «SSL certificate problems,» cURL’s verbose mode can help identify the cause. Using the -v option will provide a detailed breakdown of the request and response:
curl -v https://httpbin.dev/get
Verbose mode helps you trace every step of the request, from DNS resolution to the server’s response, including the curl GET status code and headers. This makes it easier to troubleshoot issues with SSL, timeouts, or misconfigurations.
For example, you might want to inspect the curl request get status to verify if the issue lies with the server response (e.g., a 404 error) or if there are issues with the request itself. Verbose output is especially useful when debugging curl GET request examples that aren’t behaving as expected.
cURL Alternatives
While cURL is powerful, it can be a bit tricky to use for more complex requests. Here are some popular alternatives:
- Curlie: A more user-friendly cURL alternative with an easier-to-read syntax. Learn more about Curlie here.
- HTTPie: Another CLI tool designed to simplify HTTP requests and provide a more readable output.
- Postman: A GUI-based HTTP client, perfect for testing and developing web APIs.
Scrapfly API – An Enhanced Solution for Web Scraping
For those seeking a more advanced and scalable solution for web scraping, Scrapfly offers a powerful API designed to handle the complexities of scraping at scale.
Here’s a quick example of how you can integrate Scrapfly into your scraping workflow using cURL:
curl -G \
--request "GET" \
--url "https://api.scrapfly.io/scrape" \
--data-urlencode "proxy_pool=public_residential_pool" \
--data-urlencode "country=us" \
--data-urlencode "asp=true" \
--data-urlencode "render_js=true" \
--data-urlencode "Your ScrapFly API key" \
--data-urlencode "url=https://web-scraping.dev/products" \
--data-urlencode "headers[Referer]=https://www.google.com/"
This example demonstrates how to send a POST request to Scrapfly’s API to scrape a webpage, with options to set custom headers and enable JavaScript rendering, a feature often required for dynamic content extraction.
FAQ
To wrap up our guide on using cURL for GET requests, let’s address some common questions:
Can I Use cURL for Web Scraping?
Yes, cURL can be used for basic web scraping tasks. However, for more complex scraping, such as handling dynamic content, it’s better to use tools like Scrapfly or integrate cURL with programming languages like Python.
To send multiple headers in a single cURL request, you can use the -H option for each header you want to add. This is useful when you need to set custom User-Agent, Authorization, or other headers simultaneously.
Example:
curl -H "User-Agent: CustomUserAgent" -H "Authorization: Bearer your_token" https://example.com
This sends both the User-Agent and Authorization headers in the same request.
What’s the Difference Between cURL and Curlie?
Curlie is a more user-friendly interface for cURL, offering easier syntax and colorful output formatting. It combines the flexibility of cURL with the simplicity of HTTPie.
Summary
In this guide, we explored how to perform a GET request using cURL. We covered the basics, such as sending GET requests, handling URL parameters, adding headers, troubleshooting common issues, and alternatives to cURL.
For more advanced web scraping, consider using Scrapfly, which provides a scalable and robust solution with enhanced features like proxy rotation and anti-bot bypass.
Feel free to check out our other cURL-related articles for more detailed tutorials!
Осваиваем быстрый, маленький и простой инструмент тестирования API
- Настройка
- Базовые опции
- GET-метод
- POST-метод
- Отправка простого текста
- Параметры строки запроса
- Отправка JSON-объекта
- Эмуляция отправки значений формы
- Отправка файла
- Другие методы
- Аутентификация
- Платный тариф
“Когда я начал изучать HTTP-протокол и надо было работать с URL-ами и передаваемыми в них данными, в каждом найденном инструменте не хватало хорошей документации, или она была, но в виде избыточно сложных инструкций для простых вещей, типа отправки простого HTTP-запроса. Однажды обратил внимание на curl, которым раньше скачивал файлы, и это оказался лучший инструмент для изучения веб-API.
Этот материал требует базового знакомства с HTTP-протоколом, понимания что такое веб-API, а также умения работать с командной строкой в Windows, надеемся ты это умеешь.
Итак, поехали.
Настройка
Как всякий серьезный софт, curl требует установки в операционной системе. Хорошая новость: скорее всего, он уже установлен! Точнее, встроен в операционку. Уважающий себя тестировщик, разумеется, работает в Linux, а почти каждый дистрибутив Linux уже идет с curl. Более того, даже Windows 10 (начиная с версии 1803) поставляется с curl.
Проверим, есть ли в системе curl.
В Linux набираем в терминале:
curl --version
Если все-таки работаешь в Windows, то запускаешь cmd или, лучше, PowerShell:
curl.exe --version
Команда покажет версию curl, прикрепленные библиотеки, дату релиза, поддерживаемые протоколы и поддерживаемые функции. В Linux увидим следующее:
curl 7.68.0 (x86_64-pc-linux-gnu) libcurl/7.68.0 OpenSSL/1.1.1f zlib/1.2.11 brotli/1.0.7 libidn2/2.2.0 libpsl/0.21.0 (+libidn2/2.2.0) libssh/0.9.3/openssl/zlib nghttp2/1.40.0 librtmp/2.3 Release-Date: 2020-01-08 Protocols: dict file ftp ftps gopher http https imap imaps ldap ldaps pop3 pop3s rtmp rtsp scp sftp smb smbs smtp smtps telnet tftp Features: AsynchDNS brotli GSS-API HTTP2 HTTPS-proxy IDN IPv6 Kerberos Largefile libz NTLM NTLM_WB PSL SPNEGO SSL TLS-SRP UnixSockets
Если введенная команда выдала ошибку, то curl не установлен, значит его надо скачать и поставить. Еще одна хорошая новость: он бесплатный (но есть нюансы, о которых в конце). Есть версии для практически всех операционных систем, размер ехе-шника не превышает 5 Мб.
Если понадобилось ознакомиться с curl, а опыта с API нет, ситуацию облегчит тестовый httpbin-сервис, примеры с которым приведены далее в этом посте.
Примечание. С этого момента, будут приводиться исключительно «линуксовые» bash-команды, для ясности и читабельности. Если ты сидишь в Windows и примеры почему-то не работают, попробуй добавлять «.exe» после команды curl, или удалять (возможные) лишние пробелы в строках (line breaks).
Базовые опции
Несмотря на то, что Curl очень простой инструмент, он имеет множество различных функций. Начнем с ними знакомиться:
--requestили-X: Указывает нужный http-метод (здесь подробнее — желательно хорошо разобраться). Если опции нет, запрос по умолчанию обрабатывается как GET. Например:curl -X POST ...
--headerили-H: В HTTP-запрос добавляется дополнительный заголовок, их может быть сколько угодно. Например:curl -H "X-First-Name: John" -H "X-Last-Name: Doe" ...
--dataили-d: В запрос включаются какие-то данные. Они могут добавляться в той же строке, или указывать на текстовый файл, откуда считываются. Пример:curl -d "тут текстовые данные" ...
- —
-formили-F: curl эмулирует заполненную форму, с нажатием кнопки отправки. Допускается отправка бинарных файлов. Пример:curl -F name=John -F shoesize=11 ...
--user <user:password>или-u <user:password>: Логин и пароль для аутентификации на сервере.
curl показывает логи HTTP-транзакций в терминале. Если нужно еще больше подробностей, то curl сохраняет все в файлы для проверки при необходимости. Для это есть функции:
--dump-headerили-D: Сохраняет в указанный дамп-файл полученные заголовки. Пример:curl -D result.header ...--outputили-O: Выводит в указанный дамп-файл, минуя stdout. Пример:curl -o result.json ...
GET-метод
Мы познакомились с основами, пора перейти к более серьезным вещам.
Во первых, меняем текущую папку в командной оболочке, на домашнюю папку или на рабочий стол (desktop), чтобы легче было найти выведенные из curl файлы.
Делаем первые запросы:
curl -X GET "https://httpbin.org/get" \ -H "accept: application/json" \ -D result.headers \ -o result.json
В первой строке указываем curl выполнить HTTP-запрос GET-методом, по такому-то URL. Во второй строке добавляем заголовок, чтобы сервер знал, что нам отправить в ответе. В третьей строке прописываем вывод полученных заголовков в файл дампа, который мы назовем result.headers. В последней строчке даем указание вывести результат запроса в файл result.json.
Если все пошло как надо, после запуска команды в прописанной на первом этапе домашней папке появятся нужные файлы. В данном случае будет выглядеть так.
файл result.headers
HTTP/2 200 date: Thu, 02 Sep 2021 05:47:14 GMT content-type: application/json content-length: 169
В файле result.headers видим, что запрос успешно выполнен, с кодом ответа 200 (все ОК), от сервера получен таймкод ответа (timestamp), и все заголовки.
Файл result.json
{
"args": {},
"headers": {
"Accept": "application/json",
"Host": "httpbin.org",
"User-Agent": "curl/7.68.0"
},
"url": "https://httpbin.org/get"
}
В этом файле result.json находится тело ответа. Это данные, возвращенные сервером, в красивом JSON-формате (об особенностях формата читаем здесь).
POST-метод
Отправка простого текста
Сейчас попробуем отправить обычный текст (plaintext) на сервер, с помощью метода POST.
curl -X POST "https://httpbin.org/post" \ -H "accept: application/json" \ -H "Content-Type: text/plain" \ -H "Custom-Header: Testing" \ -d "I love hashnode" \ -D result.headers \ -o result.json
Как видим, в запрос включен кастомный заголовок "Custom-Header: Testing". Он должен отображаться в теле ответа.
Смотрим теперь в файл result.headers
HTTP/2 200 date: Fri, 03 Sep 2021 03:16:20 GMT content-type: application/json content-length: 182
и файл result.json
{
"data": "I love hashnode",
"headers": {
"Accept": "application/json",
"Content-Length": "15",
"Content-Type": "text/plain",
"Custom-Header": "Testing"
}
}
Видим, что сервер получил plaintext-сообщение с тестовым заголовком и вернул его обратно без изменений.
Параметры строки запроса
В curl поддерживается не только простой текст, но и достаточно сложные параметры типа:
curl -X POST "https://httpbin.org/post?name=Carlos&last=Jasso" \ -H "accept: application/json" \ -D result.headers \ -o result.json
файл result.headers
HTTP/2 200 date: Fri, 03 Sep 2021 03:30:47 GMT content-type: application/json content-length: 120
файл result.json
{
"args": {
"lastname": "Jasso",
"name": "Carlos"
},
"headers": {
"Accept": "application/json"
}
}
Сервер, как и предыдущем примере, правильно «зеркалит» параметры, которые curl отправил.
Отправка JSON-объекта
Поставим curl-у задачу посложнее, попытаемся отправить на сервер json-файл и посмотрим что получится:
curl -X POST "https://httpbin.org/post" \ -H "Content-Type: application/json; charset=utf-8" \ -d @data.json \ -o result.json
Тут мы добавили специальный заголовок Content-Type, сообщающий серверу, что ему посылается json-файл. Путь к файлу с данными указывается флагом -d с собачкой @, и далее путь к файлу (в нашем случае это будет текущая папка).
Вот содержимое файла data.json, который надо создать:
{
"name": "Jane",
"last": "Doe"
}
И файл result.json:
{
"data": "{ \"name\": \"Jane\", \"last\": \"Doe\"}",
"headers": {
"Accept": "*/*",
"Content-Length": "38",
"Content-Type": "application/json; charset=utf-8"
},
"json": {
"last": "Doe",
"name": "Jane"
}
}
И снова видим, как curl умеет корректно отправлять контент JSON-файлов на сервер.
Эмуляция отправки значений формы
Иногда может понадобиться имитировать отправку формы. Curl умеет и это:
curl -X POST "https://httpbin.org/post" \ -H "Content-Type: multipart/form-data" \ -F "FavoriteFood=Pizza" \ -F "FavoriteBeverage=Beer" \ -o result.json
Чтобы обозначить для сервера, что посылаются данные формы, добавляется заголовок с соответствующим MIME-типом (как показано выше), плюс параметр -F в каждом из полей и значений.
result.json:
{
"form": {
"FavoriteBeverage": "Beer",
"FavoriteFood": "Pizza"
},
"headers": {
"Accept": "*/*",
"Content-Length": "261",
"Content-Type": "multipart/form-data;"
}
}
Видим, что сервер получил форму и правильно обработал все поля.
Отправка файла
Выше мы демонстрировали достаточно простые действия. А как насчет передачи файла? Файлы передаются таким же образом, как формы выше. Отправим изображение из текущей папки:
curl -X POST "https://httpbin.org/post" \ -H "Content-Type: multipart/form-data" \ -F "FileComment=This is a JPG file" \ -F "image=@image.jpg" \ -o result.json
result.json:
{
"files": {
"image": "data:image/jpeg;base64,/9j/4AAQSkZJ..."
},
"form": {
"FileComment": "This is a JPG file"
},
"headers": {
"Accept": "*/*",
"Content-Length": "78592",
"Content-Type": "multipart/form-data;"
}
}
curl может потребоваться некоторое время чтобы отправить большой файл, а потом сервер вернет этот файл (причем закодированный в Base64). Curl должен правильно обработать такой запрос.
Другие методы
Можно попробовать «погонять» любые запросы, чтобы убедиться, как полезен бывает curl при тестировании API. В целом, обработка запросов зависит от типа API и имплементации метода.
Аутентификация
curl умеет проводить аутентификацию на сервере, когда по URL-адресу нужен ввод пользовательских имени-пароля. В этом случае httpbin получает ожидаемые имя и пароль в формате /basic-auth/{user}/{passwd} и сопоставляет значения с введенными. Если эти данные не введены, получается следующее:
curl -X GET "https://httpbin.org/basic-auth/carlos/secret" \ -H "accept: application/json" \ -D result.headers
result.headers:
HTTP/2 401 date: Fri, 03 Sep 2021 04:08:44 GMT content-length: 0
То есть код 401 (не прошла авторизация).
Добавим в запрос логин и пароль:
curl -X GET "https://httpbin.org/basic-auth/carlos/secret" \ -u carlos:secret -H "accept: application/json" \ -D result.headers
result.headers:
HTTP/2 200 date: Fri, 03 Sep 2021 04:14:19 GMT content-type: application/json content-length: 48
result.json:
{
"authenticated": true,
"user": "carlos"
}
Все хорошо, авторизация прошла успешно.
Curl позволяет авторизоваться и другими методами — например, с помощью токена. Токен просто отправляется в соответствующем заголовке.
Платный тариф
Уже должно быть понятно, что curl — полезная вещь для тестировщика. Чтобы в этом мнении укрепиться, рассмотрим еще некоторые нюансы.
Распространенные инструменты тестирования API — бесплатные, но в них чаще всего бывают платными функции командной работы. Или например, запросы к социальным сетям (Вконтакте и Facebook) блокированы в бесплатном тарифе, и это один из немногих минусов в столь приятном продукте.
В других похожих инструментах бывает слишком сложный интерфейс, но это не об curl. Для простоты, рекомендую работать в VSCode. Связка VSCode c curl — идеальная.
На скрине слева отрендеренный markdown-документ, справа полученные result.headers и result.json, и терминал внизу, куда тестировщику приходится глядеть чаще всего.
Вопреки убеждению, бытующему в определенных кругах, curl хорошо работает не только в REST-архитектуре, но и в SOAP.
Конечно, раскрыть все нюансы в одной статье невозможно, и чтобы продолжить знакомство с такой полезной вещью как curl, не обойтись без чтения официальной документации на их сайте. Там же и примеры использования.”
Edit me
Почти каждый API показывает, как взаимодействовать с API с помощью curl. Поэтому, прежде чем двигаться дальше, давайте немного остановимся и узнаем больше о curl.
Одним из преимуществ API REST является то, что вы можете использовать практически любой язык программирования для вызова конечной точки. Конечная точка — это просто ресурс, расположенный на веб-сервере по определенному пути.
Каждый язык программирования имеет свой способ совершать веб-вызовы. Вместо того, чтобы тратить силы, пытаясь показать, как совершать веб-вызовы на Java, Python, C ++, JavaScript, Ruby и т.д., можно просто использовать curl.
curl предоставляет общий, независимый от языка способ демонстрации HTTP-запросов и ответов. Пользователи могут видеть формат запроса, включая любые заголовки и другие параметры. Можно перевести результат в определенный формат для используемого языка.
Используем curl для получения веб-страницы
Как упоминалось ранее, одна из причин, по которой API REST настолько знакомы, заключается в том, что REST следует той же модели, что и веб (см. Что такое REST API?). При вводе http-адреса в адресную строку браузера мы говорим браузеру сделать HTTP-запрос к ресурсу на сервере. Сервер возвращает ответ, а наш браузер преобразует ответ в более визуальное отображение. Но мы также можем увидеть и сырой код.
Чтобы увидеть пример того, как curl извлекает веб-ресурс, откройте терминал и введите следующее:
Curl извлечет HTML-код для сайта example.com. Задача браузера — сделать этот код визуально читаемым. curl показывает, что мы на самом деле получаем.
Запросы и ответы содержат заголовки
При вводе адреса веб-сайта мы видим только текст ответа. Но на самом деле происходит гораздо больше процессов. Когда мы делаем запрос, мы отправляем заголовок запроса, который содержит информацию о запросе. Ответ также содержит заголовок ответа.
Для того чтобы увидеть заголовок ответа в запрос curl, добавим ключ -i:
curl http://example.com -i
Заголовок будет включен над телом ответа:
~/projects $ curl http://example.com -I
HTTP/1.1 200 OK
Content-Encoding: gzip
Accept-Ranges: bytes
Cache-Control: max-age=604800
Content-Type: text/html; charset=UTF-8
Date: Tue, 04 Dec 2018 04:35:43 GMT
Etag: "1541025663+gzip"
Expires: Tue, 11 Dec 2018 04:35:43 GMT
Last-Modified: Fri, 09 Aug 2013 23:54:35 GMT
Server: ECS (sjc/4F91)
X-Cache: HIT
Content-Length: 606
Чтобы в ответе получить только заголовок, используем ключ -I
curl http://example.com -I
Заголовок содержит метаданные ответа. Вся эта информация передается в браузер при запросе URL в нашем браузере (например, при просмотре веб-страницы в Интернете), но браузер не отображает эту информацию. Можно просмотреть информацию заголовка с помощью консоли Chrome Developer Tools, перейдя на вкладку Network.
Теперь давайте уточним метод. Метод GET (чтение) подразумевается по умолчанию, когда не указан другой метод, но мы сделаем это здесь явно с параметром -X:
curl -X GET http://example.com -I
При посещении веб-сайта мы отправляем запрос, используя метод GET. Существуют и другие методы HTTP, которые можно использовать при взаимодействии с REST API. Вот общие методы, используемые при работе с конечными точками REST:
| HTTP метод | Описание |
|---|---|
| POST | Создание ресурса |
| GET | Чтение (получение) ресурса |
| PUT | Обновление ресурса |
| DELETE | Удаление ресурса |
Распаковка curl запроса API сервиса прогноза погоды
Рассмотрим подробнее запрос, который сделали в API сервиса прогноза погоды в предыдущем разделе Создание curl запроса:
curl -X GET -H "Cache-Control: no-cache" -H "Postman-Token: 930d08d6-7b2a-6ea2-0725-27324755c684" "https://api.openweathermap.org/data/2.5/weather?zip=95050&appid=fd4698c940c6d1da602a70ac34f0b147&units=imperial"
У curl есть сокращенные имена для различных опций, которые вы включаете в свой запрос.
Вот расшифровка команд:
-Х GET.-XПоказывает, что в запросе будет использоваться какой-то метод. Общие параметры:GET,POST,DELETE,PUT. (Также можете увидеть использование--get. Большинство команд curl имеют несколько разных представлений.-X GETтакже можно записать как--get.);-HОтправляет пользовательский заголовок. Для каждого заголовка пары ключ-значение включаем дополнительный-H.
Строки запроса и параметры
Параметры почтового индекса (zip), идентификатора приложения (appid) и единиц (units) были переданы в конечную точку с помощью «строк запроса». Знак ? добавленный к URL указывает начало строки запроса. Параметры строки запроса — это параметры, которые появляются после знака ?:
?zip=95050&appid=fd4698c940c6d1da602a70ac34f0b147&units=imperial
После строки запроса каждый параметр объединяется с другими параметрами через символ амперсанда &. Порядок параметров в строке запроса не имеет значения. Порядок имеет значение только в том случае, если параметры находятся слева от строки запроса (и, следовательно, являются частью самого URL-адреса). Любые настраиваемые части конечной точки, которые появляются перед строкой запроса, называются параметрами пути (разберем их позже).
Общие команды curl, связанные с REST
У curl много возможных команд, но при работе с REST API наиболее распространены следующие:
| curl Команда | Описание | Пример |
|---|---|---|
i или --include |
Включает заголовки ответа в ответ | curl -i http://www.example.com |
-d или --data |
Включает данные для публикации на URL. Данные должны быть в кодировке URL. Данные также могут быть переданы в теле запроса. | curl -d "data-to-post" http://www.example.com |
-H или --header |
Отправляет заголовок запроса на ресурс. Заголовки являются общими с запросами REST API, потому что авторизация обычно включается в заголовок | curl -H "key:12345" http://www.example.com |
-X POST |
Задает метод HTTP для использования с запросом (в данном примере, POST). При использовании -d в запросе, curl автоматически указывает метод POST. С GET-запросами, в том числе HTTP-метод является необязательным, поскольку GET-метод используется по умолчанию |
curl -X POST -d "resource-to-update" http://www.example.com |
@filename |
Загружает контент из файла | curl -X POST -d @mypet.json http://www.example.com |
В документации curl есть полный список команд curl.
Пример curl команды
Вот пример запроса curl, который объединяет некоторые из этих команд:
curl -i -H "Accept: application/json" -X POST -d "{status:MIA}" http://personsreport.com/status/person123
Запрос также может быть отформатирован с разрывом строки, чтобы быть более читабельным:
curl -i \
-H "Accept: application/json" \
-X POST \
-d "{status:MIA}" \
http://personsreport.com/status/person123 \
Разрывы строк является проблемой для Windows, поэтому лучше не форматировать запросы curl.
Заголовок Accept сообщает серверу, что в ответе мы принимаем только формат JSON.
👨💻 Опрос
Проверьте свою внимательность. Что означают следующие параметры?
-i-H-X POST-d
Для более подробного изучения curl в документировании REST API можно посмотреть REST-esting with curl.
🔙
Go next ➡