hub-api(1) hub manual hub-api(1)

hub-api - رابط سطح پایین برای درخواست‌های GitHub API

hub api [-it] [-X METHOD] [-H HEADER] [--cache TTL] ENDPOINT [-F FIELD|--input FILE]

-X, --method METHOD

متد HTTP مورد استفاده برای درخواست (پیش‌فرض: "GET"). در صورت استفاده از --field، --raw-field، یا --input، متد به‌طور خودکار روی "POST" تنظیم می‌شود.

از -XGET برای اجبار به سریال‌سازی فیلدها درون رشته پرس‌وجو (query string) برای درخواست GET به جای بدنه JSON درخواست POST استفاده کنید.

-F, --field KEY=VALUE

داده‌ای که باید به همراه درخواست سریال‌سازی شود. VALUE پردازش ویژه‌ای دارد؛ برای ارسال مقادیر رشته‌ای دلخواه از --raw-field استفاده کنید.

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

اگر VALUE برابر با "true"، "false"، "null" باشد یا شبیه به عدد باشد، نوع داده مناسب JSON به جای رشته استفاده می‌شود.

سریال‌سازی VALUE به عنوان آرایه یا هش (hash) تودرتوی JSON امکان‌پذیر نیست. در عوض، محموله (payload) درخواست را به صورت خارجی ساخته و آن را از طریق --input ارسال کنید.

مگر در صورتی که از -XGET استفاده شده باشد، تمام فیلدها به صورت سریال‌شده در قالب JSON درون بدنه درخواست ارسال می‌شوند. هنگامی که ENDPOINT برابر با "graphql" باشد، تمام فیلدها به جز "query" زیرمجموعه "variables" گروه‌بندی می‌شوند. ببینید: ⟨https://graphql.org/learn/queries/#variables⟩

-f, --raw-field KEY=VALUE

مشابه --field، با این تفاوت که مقادیری که با "@" شروع می‌شوند، رشته‌های صریح "true"، "false" و "null"، و همچنین رشته‌هایی که شبیه عدد هستند را می‌پذیرد.

--input FILE

نام فایلی که بدنه خام درخواست از آن خوانده می‌شود. برای خواندن از ورودی استاندارد از "-" استفاده کنید. زمانی از این گزینه استفاده کنید که می‌خواهید بار داده درخواست را به صورت دستی بسازید.

-H, --header KEY:VALUE

تنظیم یک هدر درخواست HTTP.

-i, --include

گنجاندن هدرهای پاسخ HTTP در خروجی.

-t, --flat

تجزیه JSON پاسخ و نمایش داده‌ها در قالب خط‌به‌خط کلید-مقدار مناسب برای استفاده در اسکریپت‌های شل.

--paginate

درخواست و نمایش خودکار صفحه بعدی نتایج تا زمانی که تمام منابع فهرست شوند. برای درخواست‌های GET، این گزینه منبع <next> را همان‌گونه که در هدر پاسخ "Link" مشخص شده دنبال می‌کند. برای پرس‌وجوهای GraphQL، از pageInfo که باید در پرس‌وجو وجود داشته باشد استفاده می‌کند؛ مثال‌ها را ببینید.

توجه داشته باشید که در نتیجه چندین سند JSON خروجی داده خواهد شد. اگر محدودیت نرخ (rate limit) رابط برنامه‌نویسی فرا رسیده باشد، آخرین سند خروجی، اعلان HTTP 403 خواهد بود و فرایند با وضعیتی غیر صفر خارج خواهد شد. یکی از راه‌های جلوگیری از این موضوع، فعال کردن --obey-ratelimit است.

--color[=WHEN]

فعال کردن خروجی رنگی حتی اگر stdout یک ترمینال نباشد. WHEN می‌تواند یکی از مقادیر "always" (پیش‌فرض برای --color)، "never"، یا "auto" (پیش‌فرض) باشد.

--cache TTL

ذخیره موقت (کَش) پاسخ‌های معتبر به درخواست‌های GET به مدت TTL ثانیه.

هنگام استفاده از "graphql" به عنوان ENDPOINT، کَش کردن برای پاسخ‌های درخواست‌های POST نیز اعمال خواهد شد. فقط مطمئن شوید که از --cache برای هیچ‌یک از جهش‌های (mutations) در GraphQL استفاده نکنید.

--obey-ratelimit

پس از فراتر رفتن از محدودیت نرخ (rate limit) رابط برنامه‌نویسی، فرایند را تا زمان بازنشانی پنجره محدودیت نرخ متوقف کرده و درخواست را مجدداً ارسال می‌کند. توجه داشته باشید که این عمل ممکن است باعث توقف طولانی‌مدت فرایند شود (حداکثر ۱ ساعت).

ENDPOINT

نقطه پایانی (endpoint) در GitHub API برای ارسال درخواست HTTP به آن (پیش‌فرض: "/").

برای آشنایی با نقاط پایانی موجود، ببینید: ⟨https://developer.github.com/v3⟩. برای اجرای پرس‌وجوهای GraphQL، از "graphql" به عنوان ENDPOINT استفاده کرده و -F query=QUERY را ارسال کنید.

اگر رشته‌های متنی صریح "{owner}" یا "{repo}" در ENDPOINT یا در فیلد "query" مربوط به GraphQL ظاهر شوند، این متغیرهای جایگزین با مقادیر خوانده‌شده از پیکربندی ریموت گیت مخزن فعلی پر می‌شوند.

# دریافت اطلاعات کاربر احراز هویت شده فعلی به صورت 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
        }
      }
    }
  }
´

hub(1)

12 Jul 2024 hub version 2.14.2