hurl(1)

Hurl Manual

hurl(1)

نام (NAME)

hurl - اجرا و آزمودن درخواست‌های HTTP

خلاصه دستور (SYNOPSIS)

hurl [OPTIONS] [FILES...]

hurl --test [OPTIONS] [FILES...]

توضیحات (DESCRIPTION)

Hurl یک ابزار خط فرمانی است که درخواست‌های HTTP تعریف‌شده در یک قالب متنی ساده را اجرا می‌کند.

این ابزار می‌تواند درخواست‌ها را زنجیر کند، مقادیر را ضبط نماید و پرس‌وجوها را روی هدرها و بدنهٔ پاسخ ارزیابی کند. Hurl بسیار همه‌کاره است و می‌تواند برای دریافت داده‌ها و آزمودن نشست‌های HTTP به کار رود: محتوای HTML، رابط‌های برنامه‌نویسی REST / SOAP / GraphQL، یا هرگونه API مبتنی بر XML / JSON.

$ hurl session.hurl

اگر هیچ فایل ورودی مشخص نشود، ورودی از stdin خوانده می‌شود.

$ echo GET http://httpbin.org/get | hurl
{
"args": {},
"headers": {
"Accept": "*/*",
"Accept-Encoding": "gzip",
"Content-Length": "0",
"Host": "httpbin.org",
"User-Agent": "hurl/0.99.10",
"X-Amzn-Trace-Id": "Root=1-5eedf4c7-520814d64e2f9249ea44e0"
},
"origin": "1.2.3.4",
"url": "http://httpbin.org/get"
}

Hurl می‌تواند فایل‌ها یا پوشه‌ها را به عنوان ورودی دریافت کند. در حالت دوم، Hurl فایل‌های با پسوند .hurl را به‌صورت بازگشتی جستجو خواهد کرد.

خروجی به‌طور پیش‌فرض به stdout فرستاده می‌شود. برای هدایت خروجی به یک فایل، از گزینهٔ -o, --output استفاده کنید:

$ hurl -o output input.hurl

به‌طور پیش‌فرض، Hurl تمام درخواست‌های HTTP را اجرا کرده و بدنهٔ پاسخ آخرین فراخوانی HTTP را در خروجی نمایش می‌دهد.

برای داشتن خروجی با رویکرد آزمایشی، می‌توانید از گزینهٔ --test استفاده کنید:

$ hurl --test *.hurl

قالب فایل HURL (HURL FILE FORMAT)

قالب فایل Hurl به‌طور کامل در https://hurl.dev/docs/hurl-file.html مستند شده است.

این قالب شامل یک یا چند درخواست HTTP است:

GET http://example.org/endpoint1
GET http://example.org/endpoint2

ضبط مقادیر (Capturing values)

یک مقدار از پاسخ HTTP می‌تواند در درخواست‌های بعدی HTTP دوباره استفاده شود.

یک نمونهٔ متداول، کار با توکن‌های CSRF است:

GET https://example.org
HTTP 200
# Capture the CSRF token value from html body.
[Captures]
csrf_token: xpath "normalize-space(//meta[@name='_csrf_token']/@content)"

# Do the login !
POST https://example.org/login?user=toto&password=1234
X-CSRF-TOKEN: {{csrf_token}}

اطلاعات بیشتر دربارهٔ ضبط مقادیر را می‌توانید در اینجا بیابید: https://hurl.dev/docs/capturing-response.html.SS "ارزیابی‌ها (Asserts)"

پاسخ‌های HTTP تعریف‌شده در پروندهٔ Hurl برای ایجاد ارزیابی‌ها به کار می‌روند. پاسخ‌ها اختیاری هستند.

در کمترین حالت، پاسخ شامل ارزیابی روی کد وضعیت HTTP است.

GET http://example.org
HTTP 301

همچنین می‌تواند شامل ارزیابی‌ها روی هدرهای پاسخ باشد

GET http://example.org
HTTP 301
Location: http://www.example.org

ارزیابی‌های صریح را می‌توان با ترکیب یک پرس‌وجو و یک گزاره درج کرد

GET http://example.org
HTTP 301
[Asserts]
xpath "string(//title)" == "301 Moved"

با افزودن ارزیابی‌ها، می‌توان از Hurl به‌عنوان یک ابزار آزمون برای اجرای سناریوها استفاده کرد.

اطلاعات بیشتر دربارهٔ ارزیابی‌ها را می‌توان در اینجا یافت https://hurl.dev/docs/asserting-response.html

پیکربندی (CONFIGURATION)

گزینه‌هایی که در curl وجود دارند دقیقاً دارای همان بار معنایی هستند.

گزینه‌های مشخص‌شده در خط فرمان برای هر ورودی پروندهٔ Hurl تعریف می‌شوند، مگر اینکه برچسب cli-only خورده باشند (نمی‌توانند در ورودی `[Options]` درخواست Hurl تعریف شوند)

برای نمونه:

$ hurl --location foo.hurl

تغییر مسیر را برای هر ورودی در `foo.hurl` دنبال خواهد کرد. همچنین می‌توانید با یک بخش `[Options]` گزینه‌ای را تنها برای یک ورودی خاص تعریف کنید. برای نمونه، این پروندهٔ Hurl:

GET https://example.org
HTTP 301

GET https://example.org
[Options]
location: true
HTTP 200

تغییر مسیر را فقط برای ورودی دوم دنبال خواهد کرد.

بیشتر گزینه‌ها را می‌توان با متغیرهای محیطی نیز تعریف کرد (مانند `HURL_INSECURE` برای --insecure). بنابراین، برای پیکربندی Hurl، سه منبع از کمترین اولویت (ساده‌ترین برای بازنویسی) تا بیشترین اولویت (بازنویسی‌کنندهٔ همه) وجود دارد:

متغیرهای محیطی (مانند: `HURL_INSECURE`)
گزینه‌های خط فرمان (مانند: `--insecure`)
گزینه‌های بخش Options (مانند: `insecure: true` در پرونده)

همهٔ گزینه‌ها (ALL OPTIONS)

گزینه‌های HTTP (HTTP options)

--aws-sigv4 <PROVIDER1[:PROVIDER2[:REGION[:SERVICE]]]>

تولید یک هدر `Authorization` با امضای AWS SigV4.

از -u, --user برای مشخص کردن Access Key Id (نام کاربری) و Secret Key (گذرواژه) استفاده کنید.

برای استفاده از اعتبارسنجی موقت نشست (مثلاً برای یک AWS IAM Role)، هدر `X-Amz-Security-Token` حاوی توکن نشست را اضافه کنید.

--cacert <FILE>

پروندهٔ گواهی را برای اعتبارسنجی همتا (peer verification) مشخص می‌کند. پرونده ممکن است شامل چندین گواهی CA باشد و باید در قالب PEM باشد. معمولاً Hurl به‌گونه‌ای ساخته شده که از یک پروندهٔ پیش‌فرض برای این کار استفاده می‌کند، بنابراین این گزینه معمولاً برای تغییر آن پروندهٔ پیش‌فرض به کار می‌رود.

-E, --cert <CERTIFICATE[:PASSWORD]>

پروندهٔ گواهی کلاینت و گذرواژه.

همچنین ببینید: --key.

--compressed

درخواست یک پاسخ فشرده‌شده با استفاده از یکی از الگوریتم‌های br، gzip، deflate و باز کردن خودکار فشرده‌سازی محتوا.

متغیرهای محیطی: HURL_COMPRESSED

--connect-timeout <SECONDS>

حداکثر زمان بر حسب ثانیه که به برقراری اتصال Hurl اجازه داده می‌شود.

می‌توانید واحدهای زمانی را در عبارت مهلت زمانی اتصال مشخص کنید. Hurl را طوری تنظیم کنید که با `--connect-timeout 20s` از مهلت زمانی اتصال ۲۰ ثانیه استفاده کند یا با `--connect-timeout 35000ms` آن را روی ۳۵٬۰۰۰ میلی‌ثانیه تنظیم کنید. فاصله مجاز نیست.

همچنین ببینید: -m, --max-time.

متغیرهای محیطی: HURL_CONNECT_TIMEOUT

--connect-to <HOST1:PORT1:HOST2:PORT2>

برای درخواستی به جفت HOST1:PORT1 داده‌شده، در عوض به HOST2:PORT2 متصل شو. این گزینه می‌تواند چندین بار در یک خط فرمان استفاده شود.

همچنین ببینید: --resolve.

--digest

به Hurl می‌گوید از احراز هویت HTTP Digest استفاده کند.

-H, --header <NAME:VALUE>

افزودن یک هدر اضافی برای گنجاندن در اطلاعات ارسالی. می‌تواند چندین بار در یک دستور استفاده شود.

از افزودن خط جدید (newlines) یا کاراکتر بازگشت به ابتدای خط (carriage returns) خودداری کنید.

متغیرهای محیطی: HURL_HEADER='name1:value1|name2:value2' (هدرها با | از یکدیگر جدا می‌شوند)

-0, --http1.0

به Hurl می‌گوید به‌جای استفاده از نسخهٔ HTTP ترجیحی داخلی خود، از نسخهٔ HTTP 1.0 استفاده کند.

متغیرهای محیطی: HURL_HTTP10

--http1.1

به Hurl می‌گوید از HTTP نسخهٔ 1.1 استفاده کند.

متغیرهای محیطی: HURL_HTTP11

--http2

به Hurl می‌گوید از HTTP نسخهٔ 2 استفاده کند. برای HTTPS، این بدان معناست که Hurl در مصافحهٔ TLS برای HTTP/2 مذاکره می‌کند. Hurl این کار را به‌طور پیش‌فرض انجام می‌دهد. برای HTTP، این بدان معناست که Hurl تلاش می‌کند با استفاده از هدر درخواست Upgrade:، درخواست را به HTTP/2 ارتقا دهد.

متغیرهای محیطی: HURL_HTTP2

--http3

به Hurl می‌گوید نسخهٔ HTTP 3 را برای میزبانِ درون URL امتحان کند، اما در صورت ناموفق بودن برقراری ارتباط HTTP/3، به نسخه‌های قبلی HTTP بازگردد. HTTP/3 تنها برای HTTPS در دسترس است و برای نشانی‌های HTTP فعال نیست.

متغیرهای محیطی: HURL_HTTP3

-k, --insecure

این گزینه صراحتاً به Hurl اجازه می‌دهد اتصالات و انتقال‌های SSL «ناامن» را انجام دهد.

متغیرهای محیطی: HURL_INSECURE

-4, --ipv4

این گزینه به Hurl می‌گوید هنگام تحلیل نام‌های میزبان تنها از نشانی‌های IPv4 استفاده کند، و برای نمونه IPv6 را امتحان نکند.

متغیرهای محیطی: HURL_IPV4

-6, --ipv6

این گزینه به Hurl می‌گوید هنگام تحلیل نام‌های میزبان تنها از نشانی‌های IPv6 استفاده کند، و برای نمونه IPv4 را امتحان نکند.

متغیرهای محیطی: HURL_IPV6

--key <KEY>

نام پروندهٔ کلید خصوصی.

--limit-rate <SPEED>

حداکثر سرعت انتقالی را که می‌خواهید Hurl هم برای بارگیری‌ها و هم بارگذاری‌ها استفاده کند مشخص می‌کند. این ویژگی در صورتی مفید است که پهنای باند محدودی دارید و می‌خواهید انتقال شما از تمام پهنای باندتان استفاده نکند تا آن را کندتر از حالتی کند که در غیر این صورت می‌بود. سرعت داده‌شده بر حسب بایت بر ثانیه (bytes/second) سنجیده می‌شود.

متغیرهای محیطی: HURL_LIMIT_RATE

-L, --location

دنبال کردن تغییر مسیر (redirect). برای محدود کردن تعداد تغییر مسیرهای قابل پیگیری از گزینهٔ --max-redirs استفاده کنید.

متغیرهای محیطی: HURL_LOCATION

--location-trusted

مانند -L, --location، اما اجازهٔ ارسال نام کاربری + گذرواژه را به تمامی میزبان‌هایی که سایت ممکن است به آن‌ها تغییر مسیر دهد می‌دهد. اگر سایتی شما را به سایتی تغییر مسیر دهد که اطلاعات احراز هویت خود را به آن ارسال می‌کنید (که در صورت احراز هویت HTTP Basic متن ساده است)، این عمل ممکن است رخنهٔ امنیتی ایجاد کند یا نکند.

متغیرهای محیطی: HURL_LOCATION_TRUSTED.IP "--max-filesize <BYTES> "

تعیین بیشینه اندازه یک فایل برای بارگیری بر حسب بایت. اگر فایل درخواستی بزرگ‌تر از این مقدار باشد، فرایند انتقال آغاز نمی‌شود.

متغیرهای محیطی: HURL_MAX_FILESIZE

این گزینه تنها مخصوص خط فرمان است.

--max-redirs <NUM>

تنظیم بیشینه تعداد مجاز برای دنبال کردن تغییرمسیرها (redirection).

به‌طور پیش‌فرض، این محدودیت روی ۵۰ تغییرمسیر تنظیم شده است. برای نامحدود کردن آن، این گزینه را روی -1 تنظیم کنید.

متغیرهای محیطی: HURL_MAX_REDIRS

-m, --max-time <SECONDS>

بیشینه زمانی بر حسب ثانیه که به یک درخواست/پاسخ اجازه می‌دهید طول بکشد. این همان مهلت زمانی (timeout) استاندارد است.

می‌توانید واحدهای زمانی را در عبارت بیشینه زمان مشخص کنید. برای تنظیم Hurl جهت استفاده از بیشینه زمان ۲۰ ثانیه از ‎`--max-time 20s`‎ یا برای تنظیم آن روی ۳۵٬۰۰۰ میلی‌ثانیه از ‎`--max-time 35000ms`‎ استفاده کنید. فاصله مجاز نیست.

همچنین ببینید: --connect-timeout.

متغیرهای محیطی: HURL_MAX_TIME

--negotiate

به Hurl اعلام می‌کند که از احراز هویت Negotiate (SPNEGO) استفاده کند.

--no-cookie-store

عدم استفاده از ذخیره‌ساز کوکی برای درخواست‌ها/پاسخ‌ها در یک فایل. به‌طور پیش‌فرض، درخواست‌ها در یک فایل Hurl مشترک، از ذخیره‌ساز کوکی یکسانی استفاده می‌کنند؛ این گزینه موتور کوکی را غیرفعال می‌کند.

متغیرهای محیطی: HURL_NO_COOKIE_STORE

این گزینه تنها مخصوص خط فرمان است.

--no-proxy <HOST(S)>

فهرستی از میزبان‌ها که با ویرگول انگلیسی از یکدیگر جدا شده‌اند و نباید از پروکسی استفاده کنند.

متغیرهای محیطی: no_proxy

--ntlm

به Hurl اعلام می‌کند که از احراز هویت NTLM استفاده کند.

--path-as-is

به Hurl اعلام می‌کند که توالی‌های /../ یا /./ را در مسیر URL داده‌شده پردازش نکند. به‌طور معمول Hurl طبق استانداردها آن‌ها را ادغام یا فشرده می‌کند، اما با تنظیم این گزینه به آن اعلام می‌کنید که این کار را انجام ندهد.

--pinnedpubkey <HASHES>

هنگام مذاکره برای برقراری یک اتصال TLS یا SSL، کارساز گواهی‌نامه‌ای ارسال می‌کند که هویت آن را مشخص می‌سازد. کلید عمومی از این گواهی استخراج می‌شود و اگر دقیقاً با کلید عمومی ارائه‌شده به این گزینه مطابقت نداشته باشد، Hurl پیش از ارسال یا دریافت هرگونه داده، اتصال را لغو می‌کند.

-x, --proxy <[PROTOCOL://]HOST[:PORT]>

استفاده از پروکسی مشخص‌شده.

متغیرهای محیطی: http_proxy https_proxy all_proxy

--resolve <HOST:PORT:ADDR>

ارائه یک نشانی سفارشی برای یک جفت مشخص از میزبان و درگاه (port). با استفاده از این گزینه، می‌توانید کاری کنید که درخواست(های) Hurl از یک نشانی تعیین‌شده استفاده کنند و از به کار رفتن نشانی‌ای که در حالت عادی تحلیل (resolve) می‌شد، جلوگیری شود. این گزینه را نوعی جایگزین خط فرمانی برای /etc/hosts در نظر بگیرید.

--ssl-no-revoke

(Windows) این گزینه به Hurl اعلام می‌کند که بررسی‌های لغو گواهی‌نامه را غیرفعال کند. هشدار: این گزینه امنیت SSL را کاهش می‌دهد و با استفاده از این پرچم، دقیقاً همین مورد را درخواست می‌کنید.

این گزینه تنها مخصوص خط فرمان است.

--unix-socket <PATH>

(HTTP) اتصال از طریق این سوکت دامنه یونیکس (Unix domain socket)، به جای استفاده از شبکه.

-u, --user <USER:PASSWORD>

افزودن سرایند احراز هویت پایه‌ای (Basic Authentication) به هر درخواست.

متغیرهای محیطی: HURL_USER

-A, --user-agent <NAME>

تعیین رشته User-Agent برای ارسال به کارساز HTTP.

متغیرهای محیطی: HURL_USER_AGENT

این گزینه تنها مخصوص خط فرمان است..SS "گزینه‌های خروجی (Output options)"

--color

رنگ‌آمیزی خروجی استاندارد و خطای استاندارد.

به‌طور پیش‌فرض، Hurl پاسخ را به‌صورت آراسته و رنگی نمایش می‌دهد. هنگام هدایت از طریق لوله‌ها (pipes)، جریان‌های استاندارد رنگی نمی‌شوند و با این گزینه می‌توان رنگ‌آمیزی را اجباری کرد.

متغیرهای محیطی: HURL_COLOR