Что JavaScript-разработчику следует знать о Curl

Доброго времени суток, друзья!

Представляю Вашему вниманию перевод статьи «What JavaScript Developers Should Know About Curl» автора Valery Karpov.

Curl — это популярный инструмент командной строки, часто используемый для отправки HTTP-запросов. Curl поддерживает большое количество протоколов, однако как Node.js-разработчик вы, скорее всего, будете использовать его для отпраки http-запросов к RESTful API.

Документация curl представляет собой перечень из 383 флагов командной строки, поэтому в ней очень трудно найти то, что ищешь. В этой статье я хочу поделиться с вами некоторыми часто используемыми мной шаблонами. Для примеров будет использоваться сервис httpbin.org.

Отправка http-запроса

Для начала убедитесь в том, что у вас установлен curl, выполнив команду curl --version.

$ curl --version curl 7.58.0 (x86_64-pc-linux-gnu) libcurl/7.58.0 OpenSSL/1.1.1 zlib/1.2.11 libidn2/2.0.4 libpsl/0.19.1 (+libidn2/2.0.4) nghttp2/1.30.0 librtmp/2.3 Release-Date: 2018-01-24 Protocols: dict file ftp ftps gopher http https imap imaps ldap ldaps pop3 pop3s rtmp rtsp smb smbs smtp smtps telnet tftp  Features: AsynchDNS IDN IPv6 Largefile GSS-API Kerberos SPNEGO NTLM NTLM_WB SSL libz TLS-SRP HTTP2 UnixSockets HTTPS-proxy PSL  

Для отправки запроса необходимо запустить curl url. Например, для отправки GET-запроса к https://httpbin.org/get?answer=42 следует запустить curl https://httpbin.org/get?answer=42.

$ curl https://httpbin.org/get?answer=42 {   "args": {     "answer": "42"   },    "headers": {     "Accept": "*/*",      "Host": "httpbin.org",      "User-Agent": "curl/7.58.0",      "X-Amzn-Trace-Id": "Root=1-5ee8d737-b39c6a466892725bbb52b916"   },    "origin": "69.84.111.39",    "url": "https://httpbin.org/get?answer=42" } 

После успешного завершения запроса curl возвращает тело http-ответа. Для того, чтобы заставить curl вернуть весь ответ, включая заголовки, используйте флаг -i.

$ curl -i https://httpbin.org/get?answer=42 HTTP/2 200  date: Tue, 16 Jun 2020 14:30:57 GMT content-type: application/json content-length: 801 server: istio-envoy access-control-allow-origin: * access-control-allow-credentials: true x-envoy-upstream-service-time: 2  {   "args": {     "answer": "42"   },    "headers": {     "Accept": "*/*",      "Content-Length": "0",      "Host": "httpbin.org",      "User-Agent": "curl/7.58.0",      "X-Amzn-Trace-Id": "Root=1-5ee8d7a1-cb3954c09299eb9e0dff70a6",      "X-B3-Parentspanid": "dffc55451e64b5fc",      "X-B3-Sampled": "0",      "X-B3-Spanid": "8e233a863fb18b6c",      "X-B3-Traceid": "45bd12a9067fb5c0dffc55451e64b5fc",      "X-Envoy-External-Address": "10.100.91.201",      "X-Forwarded-Client-Cert": "By=spiffe://cluster.local/ns/httpbin-istio/sa/httpbin;Hash=c1ff14671b3e24ee794f9a486570abf8ccc9d622846611d3f91a322db4d480cd;Subject=\"\";URI=spiffe://cluster.local/ns/istio-system/sa/istio-ingressgateway-service-account"   },    "origin": "69.84.111.39,10.100.91.201",    "url": "http://httpbin.org/get?answer=42" } 

Это полный http-ответ. Заголовками ответа являются строки от date: до x-envoy-upstream-service-time:.

Загрузка файлов

Wget — самый распространенный инструмент для загрузки файлов посредством командной строки. Он входит в комплект большинства диструбутивов Linux. Однако в OSX его нет.

Команда wget url аналогична команде curl -OL url. Опция -О — это опция --remote-name, которая говорит curl сохранить тело ответа в локальном файле. Опция -L говорит curl следовать перенаправлениям.

Например, ниже представлено изображение с Unsplash, его URL — https://images.unsplash.com/photo-1506812574058-fc75fa93fead.

Для загрузки этого изобюражения необходимо выполнить следующее:

$ curl -OL https://images.unsplash.com/photo-1506812574058-fc75fa93fead   % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current                                  Dload  Upload   Total   Spent    Left  Speed 100 12.1M  100 12.1M    0     0  3927k      0  0:00:03  0:00:03 --:--:-- 3927k 

Опция -O говорит curl использовать строку после последнего / в качестве имени файла. В приведенном примере изображение будет сохранено в текущей директории с именем photo-1506812574058-fc75fa93fead. Для определения имени файла используйте опцию -о (строчная буква «о»).

$ curl -o miami-beach.jpg https://images.unsplash.com/photo-1506812574058-fc75fa93fead   % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current                                  Dload  Upload   Total   Spent    Left  Speed 100 12.1M  100 12.1M    0     0  6083k      0  0:00:02  0:00:02 --:--:-- 6083k $ ls -l miami-beach-jpg -rw-rw-r-- 1 val val 12788445 Jun 16 11:03 miami-beach.jpg 

Отправка авторизованного запроса

Заголовок авторизации используется для включения в запрос данных для авторизации при обращении к RESTful API. Для добавления указанных данных необходимо использовать флаг -H. Например, если ваш ключ интерфейса (API key) my-secret-token, вы можете включить его в http-запрос следующим образом:

$ curl -H "Authorization: my-secret-token" https://httpbin.org/get {   "args": {},    "headers": {     "Accept": "*/*",      "Authorization": "my-secret-token",      "Host": "httpbin.org",      "User-Agent": "curl/7.58.0",      "X-Amzn-Trace-Id": "Root=1-5ee8e1a5-a3aa30e0765a7980b04ca4a0"   },    "origin": "69.84.111.39",    "url": "https://httpbin.org/get" } 

Обратите внимание, что httpbin.org возвращает заголовки http-запроса в теле ответа в свойстве headers.

Curl также поддерживает авторизацию по-умолчанию посредством флага -u. В следующем примере мы отправляем запрос с именем пользователя user и паролем pass:

$ curl -i -u "user:pass" https://httpbin.org/basic-auth/user/pass HTTP/2 200  date: Tue, 16 Jun 2020 15:18:45 GMT content-type: application/json content-length: 47 server: istio-envoy access-control-allow-origin: * access-control-allow-credentials: true x-envoy-upstream-service-time: 1  {   "authenticated": true,    "user": "user" } 

Вот что происходит при отправке неправильного имени пользователя или пароля:

$ curl -i -u "user:wrongpass" https://httpbin.org/basic-auth/user/pass HTTP/2 401  date: Tue, 16 Jun 2020 15:18:51 GMT content-length: 0 server: istio-envoy www-authenticate: Basic realm="Fake Realm" access-control-allow-origin: * access-control-allow-credentials: true x-envoy-upstream-service-time: 12 

Отправка POST-запроса, содержащего JSON

Флаг -X говорит curl, какой метод следует использовать: PUT, POST и т.д. По-умолчанию curl использует метод GET, поэтому писать curl -X GET не нужно.

Флаг -X часто используется совместно с флагом -d, позволяющим добавить тело запроса. В следующем примере показано как отправить POST-запрос, содержащий некоторый json:

$ curl -X POST -d '{"answer":42}' https://httpbin.org/post {   "args": {},    "data": "",    "files": {},    "form": {     "{\"answer\":42}": ""   },    "headers": {     "Accept": "*/*",      "Content-Length": "13",      "Content-Type": "application/x-www-form-urlencoded",      "Host": "httpbin.org",      "User-Agent": "curl/7.58.0",      "X-Amzn-Trace-Id": "Root=1-5ee8e3fd-8437029087be44707bd15320",      "X-B3-Parentspanid": "2a739cfc42d28236",      "X-B3-Sampled": "0",      "X-B3-Spanid": "8bdf030613bb9c8d",      "X-B3-Traceid": "75d84f317abad5232a739cfc42d28236",      "X-Envoy-External-Address": "10.100.91.201",      "X-Forwarded-Client-Cert": "By=spiffe://cluster.local/ns/httpbin-istio/sa/httpbin;Hash=ea8c3d70befa0d73aa0f07fdb74ec4700d42a72889a04630741193548f1a7ae1;Subject=\"\";URI=spiffe://cluster.local/ns/istio-system/sa/istio-ingressgateway-service-account"   },    "json": null,    "origin": "69.84.111.39,10.100.91.201",    "url": "http://httpbin.org/post" } 

Обратите внимание, что по-умолчанию значением заголовка Content-Type является application/x-www-form-urlencoded. Для json это является неверным, поэтому для определения Content-Type следует использовать флаг -H:

$ curl -X POST -d '{"answer":42}' -H "Content-Type: application/json" https://httpbin.org/post {   "args": {},    "data": "{\"answer\":42}",    "files": {},    "form": {},    "headers": {     "Accept": "*/*",      "Content-Length": "13",      "Content-Type": "application/json",      "Host": "httpbin.org",      "User-Agent": "curl/7.58.0",      "X-Amzn-Trace-Id": "Root=1-5ee8e45e-ad875af4f83efd4379b86c34",      "X-B3-Parentspanid": "5f4f33d1c5ea13aa",      "X-B3-Sampled": "0",      "X-B3-Spanid": "a062c9bf2ebfd4bd",      "X-B3-Traceid": "44aa8d62412ae34d5f4f33d1c5ea13aa",      "X-Envoy-External-Address": "10.100.86.47",      "X-Forwarded-Client-Cert": "By=spiffe://cluster.local/ns/httpbin-istio/sa/httpbin;Hash=2f0b3331fe4d512975b4b82583a55dd5d1196023d0dfce9e0abed246991c5b67;Subject=\"\";URI=spiffe://cluster.local/ns/istio-system/sa/istio-ingressgateway-service-account"   },    "json": {     "answer": 42   },    "origin": "69.84.111.39,10.100.86.47",    "url": "http://httpbin.org/post" } 

Отправка PUT-запроса, содержащего JSON-файл

Флаг -d также поддерживает отправку данных из локальных файлов.

Например, представим, что у нас есть файл data.js, содержащий такие данные:

{"answer": 42} 

Для отправки PUT-запроса с этим файлом в качестве тела запроса вы можете присвоить флагу -d значение @data.json. Префикс @ говорит curl загрузить тело запроса из файла data.json:

$ curl -X PUT -d '@data.json' -H "Content-Type: application/json" https://httpbin.org/put {   "args": {},    "data": "{\"answer\":42}",    "files": {},    "form": {},    "headers": {     "Accept": "*/*",      "Content-Length": "13",      "Content-Type": "application/json",      "Host": "httpbin.org",      "User-Agent": "curl/7.58.0",      "X-Amzn-Trace-Id": "Root=1-5ee8e745-37c4ef06326b7b4354a16b94",      "X-B3-Parentspanid": "a4f8f91f4f1b051e",      "X-B3-Sampled": "0",      "X-B3-Spanid": "a018b1a3fcebdc68",      "X-B3-Traceid": "7b48b01dc3f632eea4f8f91f4f1b051e",      "X-Envoy-External-Address": "10.100.91.201",      "X-Forwarded-Client-Cert": "By=spiffe://cluster.local/ns/httpbin-istio/sa/httpbin;Hash=6035260d9d551af6c1907270653214e8d3195abbdd19078c1c84fd9a4106f260;Subject=\"\";URI=spiffe://cluster.local/ns/istio-system/sa/istio-ingressgateway-service-account"   },    "json": {     "answer": 42   },    "origin": "69.84.111.39,10.100.91.201",    "url": "http://httpbin.org/put" } 

Заключение

Резюмируя, вот опции curl, которые я нахожу самыми полезными:

• -X определяет метод запроса, например, curl -X POST url
• -d определяет тело запроса в виде строки в PUT и POST-запросах. Используйте @ для извлечения данных из файла
• -H определяет заголовок запроса, например, curl -H "Authorization: my-secret-token" url
• -u аутентификационные данные для стандартной авторизации
• -O сохраняет тело запроса в файл
• -i показывает полный ответ, включая заголовки

Curl — полезный инструмент взаимодействия с API посредством командной строки, независимо от того, сторонний это API или API, который вы разрабатываете. Для быстрого тестирования curl подходит лучше, чем Axios в Node.js или настройка запроса в Postman, если вы знакомы с их синтаксисом.

Благодарю за потраченное время. Надеюсь, оно было потрачено не зря.