.TH "hub-api" "1" "12 Jul 2024" "hub version 2.14.2" "hub manual"
.nh
.ad l
.SH "نام (NAME)"
hub\-api \- رابط سطح پایین برای درخواست‌های GitHub API
.SH "خلاصه دستور (SYNOPSIS)"
.P
\fB\fChub api\fR [\-it] [\-X \fIMETHOD\fP] [\-H \fIHEADER\fP] [\-\-cache \fITTL\fP] \fIENDPOINT\fP [\-F \fIFIELD\fP|\-\-input \fIFILE\fP]
.SH "گزینه‌ها (OPTIONS)"
.PP
\-X, \-\-method \fIMETHOD\fP
.RS 4
متد HTTP مورد استفاده برای درخواست (پیش‌فرض: "GET"). در صورت استفاده از \fB\fC\-\-field\fR، \fB\fC\-\-raw\-field\fR، یا \fB\fC\-\-input\fR، متد به‌طور خودکار روی "POST" تنظیم می‌شود.
.sp
از \fB\fC\-XGET\fR برای اجبار به سریال‌سازی فیلدها درون رشته پرس‌وجو (query string) برای درخواست GET به جای بدنه JSON درخواست POST استفاده کنید.
.RE
.PP
\-F, \-\-field \fIKEY\fP=\fIVALUE\fP
.RS 4
داده‌ای که باید به همراه درخواست سریال‌سازی شود. \fIVALUE\fP پردازش ویژه‌ای دارد؛ برای ارسال مقادیر رشته‌ای دلخواه از \fB\fC\-\-raw\-field\fR استفاده کنید.
.sp
اگر \fIVALUE\fP با "@" شروع شود، باقی مقدار به عنوان نام فایلی که مقدار باید از آن خوانده شود تفسیر می‌گردد. برای خواندن از ورودی استاندارد از "@\-" استفاده کنید.
.sp
اگر \fIVALUE\fP برابر با "true"، "false"، "null" باشد یا شبیه به عدد باشد، نوع داده مناسب JSON به جای رشته استفاده می‌شود.
.sp
سریال‌سازی \fIVALUE\fP به عنوان آرایه یا هش (hash) تودرتوی JSON امکان‌پذیر نیست. در عوض، محموله (payload) درخواست را به صورت خارجی ساخته و آن را از طریق \fB\fC\-\-input\fR ارسال کنید.
.sp
مگر در صورتی که از \fB\fC\-XGET\fR استفاده شده باشد، تمام فیلدها به صورت سریال‌شده در قالب JSON درون بدنه درخواست ارسال می‌شوند. هنگامی که \fIENDPOINT\fP برابر با "graphql" باشد، تمام فیلدها به جز "query" زیرمجموعه "variables" گروه‌بندی می‌شوند. ببینید:
\[la]https://graphql.org/learn/queries/#variables\[ra]
.RE
.PP
\-f, \-\-raw\-field \fIKEY\fP=\fIVALUE\fP
.RS 4
مشابه \fB\fC\-\-field\fR، با این تفاوت که مقادیری که با "@" شروع می‌شوند، رشته‌های صریح "true"، "false" و "null"، و همچنین رشته‌هایی که شبیه عدد هستند را می‌پذیرد.
.RE
.PP
\-\-input \fIFILE\fP
.RS 4
نام فایلی که بدنه خام درخواست از آن خوانده می‌شود. برای خواندن از ورودی استاندارد از "\-" استفاده کنید. زمانی از این گزینه استفاده کنید که می‌خواهید بار داده درخواست را به صورت دستی بسازید.
.RE
.PP
\-H, \-\-header \fIKEY\fP:\fIVALUE\fP
.RS 4
تنظیم یک هدر درخواست HTTP.
.RE
.PP
\-i, \-\-include
.RS 4
گنجاندن هدرهای پاسخ HTTP در خروجی.
.RE
.PP
\-t, \-\-flat
.RS 4
تجزیه JSON پاسخ و نمایش داده‌ها در قالب خط‌به‌خط کلید\-مقدار مناسب برای استفاده در اسکریپت‌های شل.
.RE
.PP
\-\-paginate
.RS 4
درخواست و نمایش خودکار صفحه بعدی نتایج تا زمانی که تمام منابع فهرست شوند. برای درخواست‌های GET، این گزینه منبع \fB\fC<next\>\fR را همان‌گونه که در هدر پاسخ "Link" مشخص شده دنبال می‌کند. برای پرس‌وجوهای GraphQL، از \fB\fCpageInfo\fR که باید در پرس‌وجو وجود داشته باشد استفاده می‌کند؛ مثال‌ها را ببینید.
.sp
توجه داشته باشید که در نتیجه چندین سند JSON خروجی داده خواهد شد. اگر محدودیت نرخ (rate limit) رابط برنامه‌نویسی فرا رسیده باشد، آخرین سند خروجی، اعلان HTTP 403 خواهد بود و فرایند با وضعیتی غیر صفر خارج خواهد شد. یکی از راه‌های جلوگیری از این موضوع، فعال کردن \fB\fC\-\-obey\-ratelimit\fR است.
.RE
.PP
\-\-color[=\fIWHEN\fP]
.RS 4
فعال کردن خروجی رنگی حتی اگر stdout یک ترمینال نباشد. \fIWHEN\fP می‌تواند یکی از مقادیر "always" (پیش‌فرض برای \fB\fC\-\-color\fR)، "never"، یا "auto" (پیش‌فرض) باشد.
.RE
.PP
\-\-cache \fITTL\fP
.RS 4
ذخیره موقت (کَش) پاسخ‌های معتبر به درخواست‌های GET به مدت \fITTL\fP ثانیه.
.sp
هنگام استفاده از "graphql" به عنوان \fIENDPOINT\fP، کَش کردن برای پاسخ‌های درخواست‌های POST نیز اعمال خواهد شد. فقط مطمئن شوید که از \fB\fC\-\-cache\fR برای هیچ‌یک از جهش‌های (mutations) در GraphQL استفاده نکنید.
.RE
.PP
\-\-obey\-ratelimit
.RS 4
پس از فراتر رفتن از محدودیت نرخ (rate limit) رابط برنامه‌نویسی، فرایند را تا زمان بازنشانی پنجره محدودیت نرخ متوقف کرده و درخواست را مجدداً ارسال می‌کند. توجه داشته باشید که این عمل ممکن است باعث توقف طولانی‌مدت فرایند شود (حداکثر ۱ ساعت).
.RE
.PP
\fIENDPOINT\fP
.RS 4
نقطه پایانی (endpoint) در GitHub API برای ارسال درخواست HTTP به آن (پیش‌فرض: "/").
.sp
برای آشنایی با نقاط پایانی موجود، ببینید: \[la]https://developer.github.com/v3\[ra].
برای اجرای پرس‌وجوهای GraphQL، از "graphql" به عنوان \fIENDPOINT\fP استفاده کرده و \fB\fC\-F query=QUERY\fR را ارسال کنید.
.sp
اگر رشته‌های متنی صریح "{owner}" یا "{repo}" در \fIENDPOINT\fP یا در فیلد "query" مربوط به GraphQL ظاهر شوند، این متغیرهای جایگزین با مقادیر خوانده‌شده از پیکربندی ریموت گیت مخزن فعلی پر می‌شوند.
.RE
.br
.SH "مثال‌ها (EXAMPLES)"
.PP
.RS 4
.nf
# دریافت اطلاعات کاربر احراز هویت شده فعلی به صورت JSON
$ hub api user

# فهرست کردن مخازن کاربر به صورت خروجی خط‌به‌خط
$ hub api \-\-flat users/octocat/repos

# ارسال یک نظر به issue شماره ۲۳ از مخزن فعلی
$ hub api repos/{owner}/{repo}/issues/23/comments \-\-raw\-field \'body=Nice job!\'

# اجرای یک پرس‌وجوی GraphQL خوانده‌شده از فایل
$ hub api graphql \-F query=@path/to/myquery.graphql

# انجام صفحه‌بندی با GraphQL
$ hub api \-\-paginate graphql \-f query=\'
  query($endCursor: String) {
    repositoryOwner(login: "USER") {
      repositories(first: 100, after: $endCursor) {
        nodes {
          nameWithOwner
        }
        pageInfo {
          hasNextPage
          endCursor
        }
      }
    }
  }
\'
.fi
.RE
.SH "همچنین ببینید (SEE ALSO)"
.P
hub(1)