Как отправлять GET-запросы с помощью cURLпараметры, заголовки, перенаправления и JSON

cURL, рабочая лошадка командной строки для передачи данных по сети. Он поддерживает HTTP, HTTPS и длинный список других протоколов, установлен практически на каждой машине, с которой вам придётся работать, поэтому именно к нему инженеры обращаются в первую очередь, когда нужно проверить эндпоинт, протестировать API или загрузить страницу. Метод GET занимает центральное место во всём этом: именно так вы запрашиваете ресурс у сервера и читаете ответ.

Это руководство, сфокусированный обзор того, как отправлять GET-запросы с помощью cURL. Вы начнёте с простой команды, а затем постепенно добавите параметры запроса, заголовки, перенаправления, обработку JSON и флаги, позволяющие точно видеть, что прислал сервер. По окончании вы будете достаточно хорошо понимать cURL для реальной отладки и небольших задач по скрапингу, а также знать, когда «сырого» GET уже недостаточно.

Что на самом деле делает GET-запрос

GET, простейший и наиболее распространённый метод HTTP. Когда вы открываете URL в браузере, он отправляет GET-запрос серверу, а сервер отвечает ресурсом: HTML, изображением, JSON-данными, всем, что находится по этому адресу. GET только читает. Он не отправляет тело для создания или изменения чего-либо, как это делают POST или PUT, что делает его правильным методом для получения страниц, обращения к API только для чтения и загрузки статических ресурсов.

cURL по умолчанию использует GET, поэтому для простой загрузки никогда не нужно указывать метод явно. Минимально возможный запрос, это имя программы и URL:

curl https://httpbin.org/get

Это выводит тело ответа в терминал. httpbin.org, бесплатный сервис для инспекции запросов, который отражает обратно всё полученное, что делает его идеальным для обучения: каждый пример ниже использует его, чтобы вы могли запускать команды и точно видеть, что отправил cURL. Если вы хотите явно указать метод, -X GET или --request GET позволяет это сделать, но для обычного GET это избыточно.

Передача параметров строки запроса

Большинство реальных эндпоинтов ожидают параметры. Строка запроса, это часть URL после ?, записанная в виде пар key=value, соединённых символом &. Самый прямой способ их передать, включить прямо в URL, взяв в кавычки, чтобы оболочка не интерпретировала & как фоновый процесс:

curl 'https://httpbin.org/get?city=Berlin&page=2'

Одиночные кавычки важны. Без них оболочка видит & и разбивает команду, поэтому всегда берите в кавычки любой URL, содержащий &, ? или пробелы.

cURL также может сам собрать строку запроса с помощью -G и -d. Флаг -d обычно формирует тело POST-запроса, но добавление -G указывает cURL взять эти данные и добавить их к URL как GET-параметры:

curl -G \
  -d "city=Berlin" \
  -d "page=2" \
  https://httpbin.org/get

Обе команды формируют одинаковый запрос. Форма с -G лучше читается при большом количестве параметров или их генерации в скрипте, поскольку каждая пара оформляется отдельным флагом и не нужно вручную строить строку ?key=value&key=value.

URL-кодирование значений параметров

Обычный -d ничего не кодирует, поэтому значение с пробелом, амперсандом или косой чертой нарушит строку запроса. Когда значение небезопасно, используйте --data-urlencode вместе с -G. cURL закодирует значение за вас и всё равно добавит его как параметр запроса:

curl -G \
  --data-urlencode "q=web scraping & data" \
  --data-urlencode "sort=date desc" \
  https://httpbin.org/get

В отражённом ответе вы увидите, что пробелы превращены в %20, а амперсанд, в %26, что именно и ожидает сервер. Используйте --data-urlencode всякий раз, когда значение поступает из пользовательского ввода или содержит что-либо помимо букв, цифр и базовой пунктуации. Это избавит вас от трудноуловимых ошибок кодирования.

Добавление заголовков запроса

Заголовки передают метаданные о запросе: какой тип контента вы принимаете, каким User-Agent представляетесь, токен авторизации и ожидаемый язык или формат. Флаг -H задаёт один заголовок на использование, и его можно повторять столько раз, сколько нужно:

curl \
  -H "Accept: application/json" \
  -H "User-Agent: my-script/1.0" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  https://httpbin.org/headers

Эндпоинт /headers отражает обратно каждый полученный заголовок, поэтому вы можете убедиться, что cURL отправил именно то, что нужно. Установка реалистичного User-Agent и явного заголовка Accept, это также первый небольшой шаг к тому, чтобы автоматизированные запросы были менее похожи на стандартный скрипт cURL, что важно, как только вы начинаете получать реальные сайты. Подробнее об обработке заголовков смотрите в статье как отправлять HTTP-заголовки с помощью cURL.

Сохранение тела ответа в файл

По умолчанию cURL выводит ответ в стандартный вывод. Чтобы записать его в файл, используйте -o с именем файла на ваш выбор или -O, чтобы повторно использовать имя удалённого файла из URL:

# write to a name you pick
curl -o page.html https://httpbin.org/html

# keep the remote filename
curl -O https://httpbin.org/image/png

Используйте -O для загрузок, где сервер уже использует осмысленное имя файла, и -o, когда вам нужен контроль над местом сохранения байтов. Добавьте -s (silent) для подавления индикатора прогресса при написании скриптов и -f (fail), чтобы cURL возвращал ненулевой код завершения при HTTP-ошибках вместо того, чтобы радостно сохранять страницу с ошибкой.

Просмотр заголовков и статуса, а не только тела

При отладке тело ответа зачастую наименее интересная часть. cURL предоставляет несколько способов проверить метаданные ответа. -i добавляет заголовки ответа перед телом, -I отправляет HEAD-запрос и показывает только заголовки, а -D - дампит заголовки в место назначения (здесь - означает стандартный вывод), пока тело направляется туда, куда указывает -o:

# body with headers on top
curl -i https://httpbin.org/get

# headers only (HEAD request)
curl -I https://httpbin.org/get

# headers to stdout, body to a file
curl -D - -o body.html https://httpbin.org/html

Используйте -I, когда вас интересуют только метаданные: тип контента, длина контента, заголовки кеширования или строка статуса, без загрузки всей полезной нагрузки. Это быстрый способ проверить, существует ли ресурс и какого он типа, прежде чем брать на себя обязательство его загрузить.

Следование перенаправлениям

Серверы часто отвечают на GET перенаправлением 301 или 302 в другое место. cURL не следует перенаправлениям самостоятельно, поэтому «голый» запрос на перенаправляющий URL возвращает короткий ответ с перенаправлением, а не конечную страницу. Добавьте -L (location), чтобы cURL проследовал по перенаправлению до места назначения:

curl -L "https://httpbin.org/redirect-to?url=https://httpbin.org/get"

Без -L вы получаете само перенаправление; с ним, контент по конечному URL. Если вы хотите ограничить количество переходов, которым будет следовать cURL, добавьте --max-redirs с числом, чтобы цикл перенаправления не выполнялся бесконечно.

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

Для проверок работоспособности и скриптов вам часто нужен один конкретный факт, например код HTTP-статуса или время выполнения запроса, а не весь ответ. Флаг -w (write-out) выводит выбранные переменные после завершения передачи. Используйте его вместе с -o /dev/null для отбрасывания тела и -s для тишины:

# just the status code
curl -s -o /dev/null -w "%{http_code}\n" https://httpbin.org/get

# status plus total time in seconds
curl -s -o /dev/null \
  -w "status=%{http_code} time=%{time_total}s\n" \
  https://httpbin.org/get

Первая команда выводит что-то вроде 200 и ничего больше, это идеально для условий в оболочке или мониторинговых задач cron. Другие полезные переменные -w: %{size_download}, %{num_redirects} и %{url_effective}, последняя удобна для отслеживания места, на котором завершилась цепочка перенаправлений.

Обработка JSON-ответов API

Многие GET-эндпоинты возвращают JSON. Чтобы сообщить, что вы хотите JSON, установите заголовок Accept, а для удобного чтения результата направьте вывод cURL в jq, процессор JSON для командной строки. jq форматирует данные с отступами и позволяет выбирать поля на небольшом языке запросов:

# pretty-print the whole JSON response
curl -s -H "Accept: application/json" https://httpbin.org/get | jq .

# pull a single field out of the response
curl -s https://httpbin.org/get | jq '.headers["User-Agent"]'

Флаг -s важен при конвейеризации: он убирает индикатор прогресса, чтобы в jq поступал только чистый JSON. Далее можно извлекать именно нужные значения, что превращает cURL вместе с jq в быстрый скриптуемый API-клиент без единой строки программного кода.

Режим подробного вывода для отладки

Когда запрос ведёт себя необъяснимо, флаг -v (verbose) показывает весь обмен: настройку DNS и TLS, точную строку запроса и заголовки, отправленные cURL (с префиксом >), а также статус ответа и полученные заголовки (с префиксом <):

curl -v https://httpbin.org/get

Подробный вывод, самый быстрый способ ответить на вопросы «а мой заголовок вообще был отправлен?» или «куда идёт это перенаправление?». Если нужно захватить сырые байты для отчёта об ошибке, флаг --trace-ascii trace.txt записывает ещё более детальный лог в файл.

Когда «сырого» GET уже недостаточно

GET-запрос, это основа веб-скрапинга: загрузка страницы в итоге сводится к отправке GET и чтению возвращённого HTML. Для статических страниц и дружелюбных API одного cURL достаточно. Стены появляются, когда вы направляете его на современные коммерческие сайты. Быстро проявляются два ограничения.

Во-первых, cURL получает только сырой HTML и ничего более. Он не выполняет JavaScript, поэтому страница, формирующая контент в браузере, возвращает cURL почти пустую оболочку. Во-вторых, сайты, не желающие видеть ботов, следят за трафиком, характерным для скраперов: стандартный User-Agent, IP дата-центра и поток запросов с одного адреса блокируются или выдают CAPTCHA задолго до того, как вы успеете что-либо собрать. Частично это можно компенсировать ротацией IP и самостоятельным рендерингом страниц. Смотрите статьи cURL для веб-скрапинга и как использовать cURL с прокси, эти техники описаны там, но поддержание флота headless-браузеров и здорового пула прокси быстро становится основной частью работы.

Поскольку API принимает обычный GET, ваши знания cURL применимы к нему напрямую. Вы обращаетесь к его эндпоинту с двумя параметрами запроса: токеном и целевым URL, а отрендеренный HTML возвращается в теле ответа:

curl -G https://api.crawlbase.com/ \
  --data-urlencode "token=YOUR_CRAWLBASE_TOKEN" \
  --data-urlencode "url=https://www.example.com"

Это тот же паттерн -G плюс --data-urlencode из предыдущего раздела, поэтому правильное кодирование здесь принципиально важно: целевой URL сам является значением внутри строки запроса, а значит, он должен быть закодирован корректно. Замените обычный токен на JavaScript-токен, когда цель рендерится на стороне клиента, и API запустит страницу в реальном браузере перед возвратом HTML.

Часто задаваемые вопросы

Нужно ли указывать метод для отправки GET-запроса через cURL?

Нет. cURL по умолчанию использует GET, поэтому curl https://example.com уже отправляет GET-запрос. Можно написать curl -X GET https://example.com для ясности, но для обычной загрузки это ничего не меняет. Флаг -X нужен только когда вы хотите другой метод, например -X POST или -X DELETE.

Как передавать параметры запроса в GET-запросе cURL?

Двумя способами. Включите их прямо в URL в кавычках, например curl 'https://example.com/data?a=1&b=2', или пусть cURL построит строку запроса: curl -G -d "a=1" -d "b=2" https://example.com/data. Оба отправляют одинаковый запрос. Если любое значение содержит пробелы, амперсанды или другие специальные символы, замените флаги -d на --data-urlencode, чтобы cURL закодировал их правильно.

Как увидеть только HTTP-код статуса?

Используйте флаг write-out, отбрасывая тело: curl -s -o /dev/null -w "%{http_code}\n" https://example.com. Флаг -s скрывает индикатор прогресса, -o /dev/null выбрасывает тело ответа, а -w "%{http_code}\n" выводит только числовой статус. Это стандартная однострочная команда для проверок работоспособности и условий оболочки.

Почему cURL не следует перенаправлению?

cURL не следует перенаправлениям, пока вы не попросите его об этом. Когда сервер возвращает 301 или 302, обычный запрос показывает этот короткий ответ перенаправления, а не содержимое по адресу назначения. Добавьте -L (или --location), и cURL проследует по перенаправлению до конечного URL. Используйте --max-redirs, чтобы ограничить количество переходов.

Как получить и прочитать JSON из API с помощью cURL?

Установите заголовок Accept и направьте вывод в jq. Например, curl -s -H "Accept: application/json" https://example.com/api | jq . форматирует данные с отступами, а jq '.field' извлекает конкретное значение. Флаг -s не пропускает индикатор прогресса в конвейер, чтобы в jq поступал только чистый JSON.

Можно ли парсить JavaScript-сайт с помощью GET-запроса cURL?

Не напрямую. cURL получает сырой HTML, но не выполняет JavaScript, поэтому страницы, рендерящие контент в браузере, возвращают почти пустой результат, а антибот-системы быстро блокируют стандартный трафик cURL. Для таких целей отправьте GET через сервис рендеринга, например Crawling API, который запускает страницу в реальном браузере за ротируемым резидентным IP и возвращает готовый HTML для парсинга.

HR

Hassan Rehan

Инженер-программист · Crawlbase

Инженер-программист в Crawlbase, пишет практические руководства по ротирующимся прокси, скрейпингу и тонкостям подключения прокси к реальному коду.