http(1) HTTPie Manual http(1) نام (NAME) http - کلاینت خط فرمانی مدرن و کاربرپسند HTTP برای عصر API خلاصه دستور (SYNOPSIS) http [METHOD] URL [REQUEST_ITEM ...] توضیحات (DESCRIPTION) HTTPie: کلاینت خط فرمانی مدرن و کاربرپسند HTTP برای عصر API. آرگومان‌های موضعی (POSITIONAL ARGUMENTS) این آرگومان‌ها پس از گزینه‌ها و به ترتیبی که در اینجا فهرست شده‌اند می‌آیند. تنها وارد کردن URL الزامی است. METHOD متد HTTP مورد استفاده برای درخواست (GET, POST, PUT, DELETE, ...). این آرگومان می‌تواند حذف شود که در این صورت اگر داده‌ای برای ارسال وجود داشته باشد، HTTPie از متد POST استفاده خواهد کرد، در غیر این صورت از GET: $ http example.org # => GET $ http example.org hello=world # => POST URL نشانی اینترنتی (URL) درخواست. اگر طرحواره در نشانی قید نشود، پیش‌فرض '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 می‌توانید از یک بک‌اسلش برای اسکیپ کردن جداکننده‌های تداخل‌دار در نام فیلد استفاده کنید: 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 تعیین رشته مرزبندی (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 گزینه‌های پردازش محتوا (CONTENT PROCESSING OPTIONS) --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 پاسخ را برای رنگ‌آمیزی و قالب‌بندی در ترمینال بازنویسی می‌کند، مثلاً: --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 کل پاسخ را پیش از خروجی دادن داده‌های پردازش‌شده دریافت می‌کند. این گزینه را زمانی تنظیم کنید که می‌خواهید پاسخی طولانی‌مدت و پیوسته را به شکلی خوانا و زیبا نمایش دهید، مانند استریم‌های API توییتر. همچنین بدون --pretty نیز کاربرد دارد: تضمین می‌کند که خروجی با دفعات بیشتر و در تکه‌های کوچکتری تخلیه (flush) شود. --output, -o FILE ذخیره خروجی در FILE به جای خروجی استاندارد (stdout). اگر --download نیز تنظیم شده باشد، تنها بدنه پاسخ در FILE ذخیره می‌شود. سایر بخش‌های تبادل HTTP در خروجی خطا (stderr) چاپ می‌شوند. --download, -d بدنه پاسخ را در خروجی استاندارد چاپ نمی‌کند، بلکه آن را دانلود کرده و در یک فایل ذخیره می‌نماید. نام فایل حدس زده می‌شود مگر اینکه با --output [filename] مشخص گردد. این عمل مشابه رفتار پیش‌فرض wget است. --continue, -c از سرگیری دانلود متوقف‌شده. توجه داشته باشید که گزینه --output نیز باید مشخص شده باشد. --quiet, -q هیچ پیامی در stdout یا stderr چاپ نمی‌کند، به جز خطاها و هشدارها در صورتی که این گزینه یک بار مشخص شده باشد. مشخص کردن آن برای دو بار، هشدارها را نیز غیرفعال می‌کند. اگر --output مشخص شده باشد، خروجی استاندارد همچنان تغییر مسیر می‌یابد. این پرچم تأثیری بر روند دانلود به جز عدم چاپ در ترمینال ندارد. نشست‌ها (SESSIONS) --session SESSION_NAME_OR_PATH ایجاد یا استفاده مجدد و به‌روزرسانی یک نشست. درون یک نشست، هدرهای سفارشی، اطلاعات احراز هویت و همچنین تمامی کوکی‌های ارسالی سرور میان درخواست‌ها حفظ می‌شوند. فایل‌های نشست در مسیر زیر ذخیره می‌شوند: [HTTPIE_CONFIG_DIR]//.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 یا digest) اگر تنها نام کاربری ارائه شود (-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 به طور پیش‌فرض، درخواست‌ها حداکثر تا ۳۰ تغییر مسیر دارند (همراه با --follow عمل می‌کند). --max-headers حداکثر تعداد هدرهای پاسخ برای خواندن پیش از صرف‌نظر کردن (پیش‌فرض ۰، به معنی نامحدود). --timeout SECONDS مهلت زمانی (تایم‌اوت) اتصال درخواست بر حسب ثانیه. مقدار پیش‌فرض ۰ است، یعنی هیچ محدودیتی برای تایم‌اوت وجود ندارد. این محدودیت زمانی برای کل دانلود پاسخ نیست؛ بلکه اگر سرور به مدت ثانیه‌های تعیین‌شده پاسخی ارسال نکند، خطا گزارش می‌شود (دقیق‌تر بگوییم، اگر به مدت این ثانیه‌ها هیچ بایتی در سوکت دریافت نشود). --check-status به طور پیش‌فرض، HTTPie هنگامی که خطای شبکه یا خطای مهلک دیگری رخ ندهد با کد ۰ خارج می‌شود. این فلگ به HTTPie دستور می‌دهد تا کد وضعیت HTTP را نیز بررسی کرده و در صورت وجود خطا در کد وضعیت، با خطا خارج شود. هنگامی که سرور با کدهای وضعیت 4xx (خطای کلاینت) یا 5xx (خطای سرور) پاسخ دهد، HTTPie به ترتیب با کدهای ۴ یا ۵ خارج می‌شود. اگر پاسخ 3xx (تغییر مسیر) باشد و --follow تنظیم نشده باشد، وضعیت خروج ۳ خواهد بود. همچنین در صورتی که خروجی استاندارد تغییر مسیر داده شده باشد، پیامی در خروجی خطا (stderr) نوشته می‌شود. --path-as-is دور زدن ادغام قطعات نقطه‌ای (/../ یا /./) در URL. --chunked فعال‌سازی استریمینگ از طریق کدگذاری انتقال تکه‌ای (chunked transfer encoding). هدر Transfer-Encoding روی chunked تنظیم می‌شود. گواهی امنیتی SSL (SSL) --verify تنظیم روی "no" (یا "false") برای نادیده گرفتن بررسی گواهی SSL هاست. پیش‌فرض "yes" (یا "true") است. همچنین می‌توانید مسیر فایل CA_BUNDLE را برای گواهی‌های خصوصی ارسال کنید. (یا متغیر محیطی REQUESTS_CA_BUNDLE را تنظیم نمایید). --ssl نسخه پروتکل مورد نظر برای استفاده. پیش‌فرض SSL v2.3 خواهد بود که بالاترین پروتکل مورد پشتیبانی سرور و نصب OpenSSL شما را مذاکره می‌کند. پروتکل‌های موجود ممکن است بسته به نصب OpenSSL متفاوت باشند (در اینجا فقط پروتکل‌های پشتیبانی‌شده نشان داده شده‌اند). --ciphers رشته‌ای با قالب فهرست رمزهای OpenSSL. برای مشاهده فهرست پیش‌فرض رمزها در سیستم خود، راهنمای `http --help` را ببینید. --cert می‌توانید یک گواهی محلی برای استفاده به عنوان گواهی SSL کلاینت تعیین کنید. این فایل ممکن است هم شامل کلید خصوصی و هم گواهی باشد، یا می‌توانید --cert-key را جداگانه مشخص کنید. --cert-key کلید خصوصی برای استفاده در SSL. تنها در صورتی لازم است که --cert داده شده باشد و فایل گواهی شامل کلید خصوصی نباشد. --cert-key-pass عبارت عبور (passphrase) کلید خصوصی داده‌شده. تنها در صورتی لازم است که --cert-key داده شده باشد و فایل کلید نیازمند عبارت عبور باشد. در صورت مشخص نشدن، به صورت تعاملی درخواست خواهد شد. عیب‌یابی (TROUBLESHOOTING) --ignore-stdin, -I تلاش نکردن برای خواندن از stdin. --help نمایش این پیام راهنما و خروج. --manual نمایش راهنمای کامل. --version نمایش نسخه و خروج. --traceback در صورت بروز استثنا (exception)، ردگیری کامل پشته خطا را چاپ می‌کند. --default-scheme طرحواره پیش‌فرض برای استفاده در صورتی که در نشانی URL مشخص نشده باشد. --debug در صورت بروز استثنا، ردگیری پشته و همچنین اطلاعات دیگر مفید برای دیباگ کردن HTTPie و گزارش باگ‌ها را چاپ می‌کند. همچنین ببینید (SEE ALSO) به ازای هر گزینه --OPTION یک گزینه --no-OPTION نیز وجود دارد که مقدار OPTION را به حالت پیش‌فرض بازمی‌گرداند. پیشنهادات و گزارش باگ‌ها مورد استقبال قرار می‌گیرند: HTTPie 3.2.4 2024-07-10 http(1)