نام (NAME)

https - کلاینت HTTP خط فرمانی مدرن و کاربرپسند برای عصر APIها

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

https [METHOD] URL [REQUEST_ITEM ...]

توضیحات (DESCRIPTION)

HTTPie: کلاینت HTTP خط فرمانی مدرن و کاربرپسند برای عصر APIها. https://httpie.io

آرگومان‌های ترتیبی (Positional arguments)

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

METHOD

متد HTTP مورد استفاده برای درخواست (GET، POST، PUT، DELETE، ...).

این آرگومان می‌تواند نادیده گرفته شود؛ در این صورت اگر داده‌ای برای ارسال وجود داشته باشد HTTPie از POST استفاده خواهد کرد، در غیر این صورت از GET:

$ http example.org # => GET
$ http example.org hello=world # => POST

URL

آدرس URL درخواست. در صورتی که URL فاقد طرحواره (scheme) باشد، پیش‌فرض آن 'http://' است. (می‌توانید با این گزینه آن را بازنویسی کنید: --default-scheme=http/https)

همچنین می‌توانید از کوته‌نوشت برای localhost استفاده کنید

$ http :3000 # => http://localhost:3000
$ http :/foo # => http://localhost/foo

REQUEST_ITEM

جفت‌های کلید-مقدار اختیاری برای گنجانده شدن در درخواست. جداکنندهٔ استفاده‌شده نوع را تعیین می‌کند:

':' سرآیندهای HTTP:

Referer:https://httpie.io Cookie:foo=bar User-Agent:bacon/1.0

'==' پارامترهای URL برای افزوده شدن به URI درخواست:

search==httpie

'=' فیلدهای داده برای سریال‌سازی به یک شیء JSON (با --json، -j)
یا داده‌های فرم (با --form، -f):

name=HTTPie language=Python description='CLI HTTP client'

':=' فیلدهای دادهٔ غیررشته‌ای JSON (تنها با --json، -j):

awesome:=true amount:=42 colors:='["red", "green", "blue"]'

'@' فیلدهای فایل فرم (تنها با --form یا --multipart):

cv@~/Documents/CV.pdf
cv@'~/Documents/CV.pdf;type=application/pdf'

'=@' یک فیلد داده مانند '='، اما یک مسیر فایل دریافت می‌کند و محتوای آن را درج می‌نماید:

essay=@Documents/essay.txt

':=@' یک فیلد خام JSON مانند ':='، اما یک مسیر فایل دریافت می‌کند و محتوای آن را درج می‌نماید:

package:=@./package.json

می‌توانید از یک بک‌اسلش برای گریز دادن (escape) جداکننده‌ای که با نام فیلد تداخل دارد استفاده کنید:

field-name-with\:colon=value

انواع محتوای از پیش تعریف‌شده (Predefined content types)

--json, -j

(پیش‌فرض) آیتم‌های داده از خط فرمان به عنوان یک شیء JSON سریال‌سازی می‌شوند. سرآیندهای Content-Type و Accept روی application/json تنظیم می‌شوند (در صورت عدم تعیین).

--form, -f

آیتم‌های داده از خط فرمان به عنوان فیلدهای فرم سریال‌سازی می‌شوند.

سرآیند Content-Type روی application/x-www-form-urlencoded تنظیم می‌شود (در صورت عدم تعیین). وجود هرگونه فیلد فایل منجر به یک درخواست multipart/form-data خواهد شد.

--multipart

مشابه --form، اما همیشه یک درخواست multipart/form-data ارسال می‌کند (یعنی حتی بدون فایل‌ها).

--boundary

تعیین یک رشته مرزبندی سفارشی برای درخواست‌های multipart/form-data. تنها همراه با --form اثرگذار است.

--raw

این گزینه به شما اجازه می‌دهد داده‌های خام درخواست را بدون پردازش اضافی ارسال کنید (برخلاف نحو ساختاریافتهٔ آیتم‌های درخواست):

$ http --raw='data' pie.dev/post

می‌توانید با هدایت داده از طریق stdin نیز به همین نتیجه برسید:

$ echo data | http pie.dev/post

یا ترتیبی دهید که HTTPie داده‌های خام را از یک فایل بارگذاری کند:

$ http pie.dev/post @data.txt

--compress, -x

محتوا با الگوریتم Deflate فشرده‌سازی (کدگذاری) می‌شود. سرآیند Content-Encoding بر روی deflate تنظیم می‌گردد.

اگر به نظر برسد که نسبت فشرده‌سازی منفی است، از فشرده‌سازی صرف‌نظر می‌شود. با تکرار این آرگومان می‌توان فشرده‌سازی را اجباری کرد.

پردازش خروجی (OUTPUT PROCESSING)

--pretty

پردازش خروجی را کنترل می‌کند. مقدار می‌تواند "none" برای زیباسازی نکردن خروجی (پیش‌فرض برای خروجی تغییرمسیرداده‌شده)، "all" برای اعمال هم‌زمان رنگ‌ها و قالب‌بندی (پیش‌فرض برای خروجی ترمینال)، "colors" یا "format" باشد.

--style, -s STYLE

سبک رنگ‌آمیزی خروجی (پیش‌فرض "auto" است). می‌تواند یکی از موارد زیر باشد:

auto, pie, pie-dark, pie-light, solarized

برای مشاهده تمام سبک‌های موجود در سیستم خود، این دستور را امتحان کنید:

$ http --style

سبک "auto" از سبک‌های رنگ ANSI ترمینال شما پیروی می‌کند. برای اینکه سبک‌های غیر از auto به درستی کار کنند، لطفاً مطمئن شوید که متغیر محیطی $TERM روی "xterm-256color" یا مشابه آن تنظیم شده باشد (برای نمونه، از طریق `export TERM=xterm-256color' در ~/.bashrc خود).

--unsorted

غیرفعال کردن تمام مرتب‌سازی‌ها هنگام قالب‌بندی خروجی. این گزینه یک میان‌بر است برای:

--format-options=headers.sort:false,json.sort_keys:false

--sorted

فعال‌سازی مجدد تمام گزینه‌های مرتب‌سازی هنگام قالب‌بندی خروجی. این گزینه یک میان‌بر است برای:

--format-options=headers.sort:true,json.sort_keys:true

--response-charset ENCODING

بازنویسی انکودینگ پاسخ برای اهداف نمایش در ترمینال، برای نمونه:

--response-charset=utf8
--response-charset=big5

--response-mime MIME_TYPE

بازنویسی نوع چندرسانه‌ای (MIME type) پاسخ برای رنگ‌آمیزی و قالب‌بندی در ترمینال، برای نمونه:

--response-mime=application/json
--response-mime=text/xml

--format-options

قالب‌بندی خروجی را کنترل می‌کند. تنها زمانی مرتبط است که قالب‌بندی از طریق --pretty=all یا --pretty=format (صریح یا ضمنی) فعال شده باشد. موارد زیر گزینه‌های پیش‌فرض هستند:

headers.sort:true
json.format:true
json.indent:4
json.sort_keys:true
xml.format:true
xml.indent:2

می‌توانید از این گزینه چندین بار استفاده کنید و همچنین چند گزینه را به‌طور هم‌زمان با کاما از هم جدا نمایید. برای نمونه، دستور زیر تنظیمات را طوری تغییر می‌دهد که مرتب‌سازی کلیدهای JSON غیرفعال شده و اندازه تورفتگی روی ۲ تنظیم شود:

--format-options json.sort_keys:false,json.indent:2

این تنظیمی است که معمولاً در فایل پیکربندی خود قرار می‌دهید.

گزینه‌های خروجی (OUTPUT OPTIONS)

--print, -p WHAT

رشته‌ای که مشخص می‌کند خروجی باید شامل چه مواردی باشد:

'H' سرآیندهای درخواست
'B' بدنه درخواست
'h' سرآیندهای پاسخ
'b' بدنه پاسخ
'm' فراداده‌های پاسخ

اگر خروجی استاندارد تغییرمسیر داده نشده باشد، رفتار پیش‌فرض 'hb' است (یعنی سرآیندها و بدنه پاسخ چاپ می‌شوند). اگر خروجی به برنامه دیگری پایپ شود یا درون یک فایل هدایت گردد، به‌طور پیش‌فرض تنها بدنه پاسخ چاپ می‌شود.

--headers, -h

تنها سرآیندهای پاسخ چاپ شوند. میان‌بری برای --print=h.

--meta, -m

تنها فراداده‌های پاسخ چاپ شوند. میان‌بری برای --print=m.

--body, -b

تنها بدنه پاسخ چاپ شود. میان‌بری برای --print=b.

--verbose, -v

خروجی با جزئیات بیشتر (پُرگو). در سطح یک (با یک بار درج `-v`/`--verbose`)، کل درخواست و همچنین پاسخ چاپ می‌شود. همچنین تمام درخواست‌ها/پاسخ‌های واسط (مانند تغییرمسیرها) نیز چاپ می‌شوند. برای سطح دو و بالاتر، علاوه بر این موارد، فراداده‌های پاسخ نیز چاپ خواهند شد.

سطح یک میان‌بری است برای: --all --print=BHbh سطح دو میان‌بری است برای: --all --print=BHbhm

--all

به‌طور پیش‌فرض، تنها درخواست/پاسخ نهایی نمایش داده می‌شود. از این پرچم برای نمایش تمام درخواست‌ها/پاسخ‌های واسط نیز استفاده کنید. درخواست‌های واسط شامل تغییرمسیرهای دنبال‌شده (با --follow)، اولین درخواست غیرمجاز هنگام استفاده از احراز هویت دایجِست (--auth=digest)، و غیره هستند.

--stream, -S

همیشه بدنه پاسخ به‌صورت خط‌به‌خط استریم (جریان‌سازی) شود، یعنی رفتاری مانند `tail -f' داشته باشد.

بدون --stream و همراه با --pretty (چه صریح تنظیم شده باشد چه ضمنی)، ابزار HTTPie پیش از ارائه خروجی داده‌های پردازش‌شده، کل پاسخ را واکشی می‌کند.

این گزینه را زمانی تنظیم کنید که می‌خواهید یک پاسخ طولانی‌مدت زیباسازی‌شده را به‌طور مداوم نمایش دهید، مانند پاسخ‌های دریافتی از Twitter streaming API.

این گزینه بدون --pretty نیز سودمند است: تضمین می‌کند که خروجی در فواصل زمانی بیشتر و در قطعات کوچک‌تری تخلیه (flush) شود.

--output, -o FILE

ذخیره خروجی در FILE به جای stdout. اگر --download نیز تنظیم شده باشد، تنها بدنه پاسخ در FILE ذخیره می‌شود. سایر بخش‌های تبادل HTTP در stderr چاپ می‌شوند.

--download, -d

بدنه پاسخ را در stdout چاپ نمی‌کند؛ در عوض، آن را بارگیری کرده و در یک فایل ذخیره می‌کند. نام فایل حدس زده می‌شود مگر اینکه با --output [filename] مشخص شده باشد. این عمل مشابه رفتار پیش‌فرض wget است.

--continue, -c

ادامه یک بارگیری متوقف‌شده. توجه داشته باشید که گزینه --output نیز باید مشخص شده باشد..IP "--quiet, -q"

در صورت مشخص شدن یک‌باره، چیزی در stdout یا stderr چاپ نمی‌شود، مگر برای خطاها و هشدارها. برای فرونشاندن هشدارها نیز، آن را دو بار مشخص کنید. اگر --output مشخص شده باشد، stdout همچنان تغییر مسیر می‌یابد. این پرچم بر رفتار بارگیری تأثیری فراتر از چاپ نکردن روی ترمینال نمی‌گذارد.

نشست‌ها (SESSIONS)

--session SESSION_NAME_OR_PATH

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

فایل‌های نشست در این مسیر ذخیره می‌شوند:

[HTTPIE_CONFIG_DIR]/<HOST>/<SESSION_NAME>.json.

برای آگاهی از HTTPIE_CONFIG_DIR پیش‌فرض خود به صفحه زیر مراجعه کنید:

https://httpie.io/docs/cli/config-file-directory

--session-read-only SESSION_NAME_OR_PATH

ایجاد یا خواندن یک نشست بدون به‌روزرسانی آن از طریق تبادل درخواست/پاسخ.

احراز هویت (AUTHENTICATION)

--auth, -a USER[:PASS] | TOKEN

برای سازوکارهای احراز هویت مبتنی بر نام‌کاربری/گذرواژه (مانند basic auth یا digest auth) اگر فقط نام‌کاربری وارد شود (-a username)، ابزار HTTPie گذرواژه را از شما درخواست خواهد کرد.

--auth-type, -A

سازوکار احراز هویت مورد استفاده. پیش‌فرض بر روی "basic" است.

"basic": احراز هویتِ Basic HTTP

"digest": احراز هویتِ Digest HTTP

"bearer": احراز هویتِ Bearer HTTP

برای مشاهده تمامی انواع احراز هویت موجود در سیستم خود، شامل مواردی که با افزونه‌ها نصب شده‌اند، دستور زیر را اجرا کنید:

$ http --auth-type

--ignore-netrc

نادیده گرفتن اعتبارنامه‌ها از .netrc.

شبکه (NETWORK)

--offline

ساخت درخواست و چاپ آن، اما ارسال نکردنِ واقعی آن.

--proxy PROTOCOL:PROXY_URL

رشته‌ای برای نگاشت پروتکل به نشانی URL پروکسی (مانند http:http://foo.bar:3128). می‌توانید چندین پروکسی را با پروتکل‌های مختلف مشخص کنید. متغیرهای محیطی $ALL_PROXY، $HTTP_PROXY و $HTTPS_proxy نیز پشتیبانی می‌شوند.

--follow, -F

دنبال کردن تغییرمسیرهای 30x سرآیند Location.

--max-redirects

به‌طور پیش‌فرض، درخواست‌ها دارای محدودیت 30 تغییرمسیر هستند (با --follow کار می‌کند).

--max-headers

حداکثر تعداد سرآیندهای پاسخ که باید پیش از صرف‌نظر کردن خوانده شوند (پیش‌فرض 0، به معنای بدون محدودیت).

--timeout SECONDS

مهلت زمانی (timeout) اتصال درخواست بر حسب ثانیه. مقدار پیش‌فرض 0 است، یعنی هیچ محدودیت زمانی وجود ندارد. این محدودیت زمانی برای کل فرایند بارگیری پاسخ نیست؛ بلکه اگر سرور به مدت timeout ثانیه پاسخی ارسال نکند، خطایی گزارش می‌شود (دقیق‌تر، اگر به مدت timeout ثانیه هیچ بایتی روی سوکت پایه دریافت نشود).

--check-status

به‌طور پیش‌فرض، اگر هیچ خطای شبکه یا خطای مهلک دیگری رخ ندهد، HTTPie با وضعیت 0 خارج می‌شود. این پرچم به HTTPie دستور می‌دهد تا کد وضعیت HTTP را نیز بررسی کند و در صورتی که وضعیت نشان‌دهنده خطا باشد، با یک خطا خارج شود.

هنگامی که سرور با یک کد وضعیت 4xx (خطای کلاینت) یا 5xx (خطای سرور) پاسخ می‌دهد، HTTPie به ترتیب با وضعیت 4 یا 5 خارج می‌شود. اگر پاسخ 3xx (تغییرمسیر) باشد و --follow تنظیم نشده باشد، وضعیت خروج 3 خواهد بود. همچنین اگر stdout تغییر مسیر داده شده باشد، یک پیام خطا در stderr نوشته می‌شود.

--path-as-is

دور زدن فشرده‌سازی بخش‌های نقطه‌ای (/../ یا /./) در URL.

--chunked

فعال‌سازی جریان داده (streaming) از طریق کدگذاری انتقال تکه‌تکه (chunked transfer encoding). سرآیند Transfer-Encoding بر روی chunked تنظیم می‌شود.

--verify

برای صرف‌نظر از بررسی گواهی SSL میزبان، روی "no" (یا "false") تنظیم کنید. پیش‌فرض آن "yes" ("true") است. همچنین می‌توانید مسیر یک فایل CA_BUNDLE را برای گواهی‌های خصوصی مشخص کنید. (یا می‌توانید به‌جای آن متغیر محیطی REQUESTS_CA_BUNDLE را مقداردهی کنید.)

--ssl

نسخهٔ پروتکل مورد نظر برای استفاده. مقدار پیش‌فرض آن SSL v2.3 خواهد بود که بالاترین پروتکل پشتیبانی‌شده توسط هر دو سرور و نسخهٔ OpenSSL نصب‌شده شما را مذاکره می‌کند. پروتکل‌های موجود ممکن است بسته به OpenSSL نصب‌شده متفاوت باشند (تنها موارد پشتیبانی‌شده در اینجا نمایش داده شده‌اند).

--ciphers

رشته‌ای در قالب فهرست رمزهای (ciphers) OpenSSL.

برای دیدن فهرست پیش‌فرض رمزها در سیستم خود، `http --help` را بررسی کنید.

--cert

می‌توانید یک گواهی محلی را برای استفاده به‌عنوان گواهی SSL سمت کلاینت مشخص کنید. این فایل می‌تواند شامل هر دو کلید خصوصی و گواهی باشد یا می‌توانید --cert-key را به‌طور جداگانه مشخص کنید.

--cert-key

کلید خصوصی برای استفاده با SSL. تنها در صورتی نیاز است که --cert داده شده باشد و فایل گواهی حاوی کلید خصوصی نباشد.

--cert-key-pass

عبارت‌عبور مورد استفاده برای کلید خصوصی داده‌شده. تنها در صورتی نیاز است که --cert-key مشخص شده باشد و فایل کلید به یک عبارت‌عبور نیاز داشته باشد. در صورت ارائه نشدن، به‌صورت تعاملی از شما پرسیده خواهد شد.

عیب‌یابی (Troubleshooting)

--ignore-stdin, -I

برای خواندن stdin تلاش نکنید.

--help

نمایش این پیام راهنما و خروج.

--manual

نمایش کتابچه راهنمای کامل.

--version

نمایش نسخه و خروج.

--traceback

در صورت بروز استثنا، ردپای پشته (traceback) را چاپ می‌کند.

--default-scheme

طرح (scheme) پیش‌فرض برای استفاده در صورتی که در URL مشخص نشده باشد.

--debug

در صورت وقوع استثنا، ردپای پشته (traceback) را چاپ می‌کند، همچنین اطلاعات دیگر که برای اشکال‌زدایی خود HTTPie و گزارش باگ‌ها مفید هستند.

همچنین ببینید (SEE ALSO)

به‌ازای هر --OPTION یک --no-OPTION نیز وجود دارد که OPTION را به مقدار پیش‌فرض آن بازمی‌گرداند.

از پیشنهادها و گزارش‌های باگ بسیار استقبال می‌شود: https://github.com/httpie/cli/issues