نام (NAME)

glab-api - برقراری یک درخواست احراز هویت‌شده به API گیت‌لب

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

glab api [flags]

توضیحات (DESCRIPTION)

یک درخواست HTTP احراز هویت‌شده به GitLab API ارسال کرده و پاسخ را چاپ می‌کند. یک مسیر به یکی از نقاط پایانی نسخه ۴ API گیت‌لب یا graphql را برای دسترسی به GitLab GraphQL API مشخص کنید.

برای کسب اطلاعات بیشتر، به موارد زیر مراجعه کنید:

مستندات GitLab REST API ⟨https://docs.gitlab.com/api⟩
مستندات GitLab GraphQL ⟨https://docs.gitlab.com/api/graphql⟩

اگر دایرکتوری جاری یک دایرکتوری گیت باشد، این دستور از میزبان احراز هویت‌شدهٔ گیت‌لب در دایرکتوری جاری استفاده می‌کند. در غیر این صورت، از gitlab.com استفاده می‌شود. برای تغییر نام میزبان گیت‌لب، از گزینه --hostname استفاده کنید.

هنگامی که این متغیرهای جایگزین در آرگومان نقطه پایانی (endpoint) به کار روند، با مقادیر مربوط به مخزن در دایرکتوری جاری جایگزین می‌شوند:

:branch
:fullpath
:group
:id
:namespace
:repo
:user
:username

متد پیش‌فرض درخواست HTTP در صورتی که پارامتری افزوده نشود GET و در غیر این صورت POST است. برای تغییر متد، از گزینه --method استفاده کنید.

یک یا چند مقدار --raw-field را در قالب key=value ارسال کنید تا پارامترهای رشته‌ای کدگذاری‌شده به‌صورت JSON به بدنه درخواست POST اضافه شوند.

گزینه --field مانند --raw-field عمل می‌کند اما مقادیر را بر اساس قالب آن‌ها تبدیل می‌نماید:

مقادیر صریح true، false، null و اعداد صحیح به انواع متناظر در JSON تبدیل می‌شوند.
مقادیری که با [ یا { شروع شوند، به عنوان آرایه‌ها یا اشیاء JSON تجزیه می‌شوند (مانند -F 'topics=["my-topic","GitLab"]'). ساختار نامعتبر JSON یک خطا برمی‌گرداند. مقدار باید حتماً با قلاب یا آکولاد آغاز شود: فاصله ابتدایی مانند -F 'topics= ["a"]' بخشی از مقدار در نظر گرفته شده و به صورت رشته متنی ارسال می‌شود.
مقادیر جایگزین :namespace، :repo و :branch با مقادیر مربوط به مخزن در دایرکتوری جاری جایگزین می‌شوند، حتی در داخل آرایه‌ها و اشیاء JSON (مانند -F 'input={"projectPath":":fullpath"}').
اگر مقدار با @ شروع شود، باقی‌مانده مقدار به عنوان نام فایلی برای خواندن داده‌ها تفسیر می‌شود. برای خواندن از ورودی استاندارد (stdin)، مقدار - را بفرستید.

گزینه --raw-field آرایه‌ها یا اشیاء JSON را تجزیه نمی‌کند؛ این مقادیر به صورت رشته ارسال می‌شوند. برای ارسال مستقیم بدنه JSON، از گزینه --input استفاده کنید.

یک مقدار درون قلاب برای --raw-field مانند -f 'scopes=[api,read_api]' به عنوان رشته متنی مستقیم "[api,read_api]" ارسال می‌شود. در نسخه‌های قبلی این ساختار در بدنه درخواست به یک آرایه تبدیل می‌شد که هرگز در مستندات --raw-field ذکر نشده بود. برای ایجاد آرایه از -F 'scopes=["api","read_api"]' استفاده کنید.

برای درخواست‌های GraphQL، تمام فیلدها به جز query و operationName به عنوان متغیرهای GraphQL تفسیر می‌شوند.

برای ارسال داده‌ها به صورت multipart/form-data به جای JSON، از گزینه --form استفاده کنید. این گزینه برای نقاط پایانی API که بارگذاری فایل را می‌پذیرند، مانند پیوست‌های ویکی، الزامی است. یک یا چند مقدار --form را در قالب key=value مشخص کنید. برای بارگذاری فایل، در ابتدای مقدار از @ و به دنبال آن مسیر فایل استفاده کنید. برای خواندن از ورودی استاندارد، - را ارسال کنید. گزینه --form را با --field، --raw-field یا --input ترکیب نکنید.

برای ارسال بدنه خام یک درخواست، از گزینه --input همراه با مسیر فایل استفاده کنید. برای خواندن از ورودی استاندارد، - را بفرستید. در این حالت، پارامترهای مشخص‌شده با گزینه‌های --field به صورت پارامترهای پرسمان (query parameters) در URL قرار می‌گیرند.

در حالت --paginate، تمام صفحات نتایج به صورت متوالی درخواست می‌شوند تا زمانی که صفحه‌ای باقی نماند. برای درخواست‌های GraphQL:

پرسمان اولیه باید یک متغیر $endCursor: String را بپذیرد.
پرسمان باید مجموعه فیلدهای pageInfo{ hasNextPage, endCursor } را از یک مجموعه (collection) دریافت کند.

گزینه --output قالب خروجی را کنترل می‌کند:

json (پیش‌فرض): ساختار JSON خوانا و قالب‌بندی‌شده (Pretty-printed). آرایه‌ها به صورت یک آرایه واحد JSON چاپ می‌شوند.
ndjson: ساختار JSON جداشده با خطوط جدید (Newline-delimited JSON)، مشهور به JSON Lines. هر عنصر آرایه یا شیء در یک خط مجزا چاپ می‌شود. این قالب برای مجموعه‌داده‌های بزرگ از نظر مصرف حافظه بهینه‌تر بوده و به خوبی با ابزارهایی مانند jq سازگار است.

برای مشاهده مشخصات قالب ndjson، به مستندات ndjson در ⟨https://github.com/ndjson/ndjson-spec⟩ و JSON Lines در ⟨https://jsonlines.org⟩ مراجعه فرمایید.

گزینه‌ها (OPTIONS)

-F, --field=[] افزودن پارامتری با نوع استنباط‌شده. استفاده از این سوییچ، متد پیش‌فرض HTTP را به POST تغییر می‌دهد.

--form=[] افزودن فیلد چندبخشی فرم (multipart form). برای بارگذاری یک فایل، در ابتدای مقدار از علامت @ و در پی آن مسیر فایل استفاده کنید. برای خواندن از ورودی استاندارد، از @- استفاده نمایید (حداکثر یک بار). استفاده از این سوییچ، متد پیش‌فرض HTTP را به POST تغییر می‌دهد.

-H, --header=[] افزودن یک هدر اضافی به درخواست HTTP.

--hostname="" نام میزبان گیت‌لب برای درخواست. پیش‌فرض gitlab.com، یا میزبان احراز هویت‌شده در دایرکتوری گیت جاری است.

-i, --include[=false] گنجاندن هدرهای پاسخ HTTP در خروجی.

--input="" فایلی که به عنوان بدنه درخواست HTTP استفاده می‌شود.

-X, --method="GET" متد HTTP برای ارسال درخواست.

--output="json" قالب‌بندی خروجی به صورت: json, ndjson.

--paginate[=false] ارسال درخواست‌های HTTP مکرر برای دریافت همه صفحات نتایج.

-f, --raw-field=[] افزودن یک پارامتر رشته‌ای متنی.

--silent[=false] جلوگیری از چاپ بدنه پاسخ در خروجی.

گزینه‌های به ارث رسیده از دستورات والد (OPTIONS INHERITED FROM PARENT COMMANDS)

-h, --help[=false] نمایش راهنما برای این دستور.

مثال‌ها (EXAMPLES)

# فهرست کردن نسخه‌های منتشرشده پروژه جاری، با بسط متغیر جایگزین :fullpath
glab api projects/:fullpath/releases
# فهرست کردن مشکلات (issues) یک پروژه با مسیر کدگذاری‌شده در URL
glab api projects/gitlab-com%2Fwww-gitlab-com/issues
# بارگذاری یک فایل در ویکی پروژه
glab api --method POST projects/:fullpath/wikis/attachments --form "file=@./image.png" --form "branch=main"
# اشکال‌زدایی درخواست و پاسخ HTTP، شامل هدرها و بدنه.
# استفاده از --input برای ارسال بدنه کامل درخواست JSON از ورودی استاندارد (stdin).
echo '{"allowed_to_push":[{"user_id":1}]}' | GLAB_DEBUG_HTTP=1 glab api -X PATCH "projects/:fullpath/protected_branches/main" --input -
# دریافت تمام صفحات مسائل (issues)
glab api issues --paginate
# دریافت تمام صفحات مسائل به صورت ndjson
glab api issues --paginate --output ndjson
# هدایت خروجی صفحه‌بندی‌شده به jq برای فیلتر کردن مسائل باز
glab api issues --paginate --output ndjson | jq 'select(.state == "opened")'
# اجرای یک پرسمان ساده GraphQL
glab api graphql -f query="query { currentUser { username } }"
# اجرای یک پرسمان چندخطی GraphQL برای دریافت متادیتای پروژه
glab api graphql -f query='
  query {
    project(fullPath: "gitlab-org/gitlab-docs") {
      name
      forksCount
      statistics {
        wikiSize
      }
      issuesEnabled
      boards {
        nodes {
          id
          name
        }
      }
    }
  }
'
# اجرای یک پرسمان صفحه‌بندی‌شده GraphQL با استفاده از متغیر endCursor
glab api graphql --paginate -f query='
  query($endCursor: String) {
    project(fullPath: "gitlab-org/graphql-sandbox") {
      name
      issues(first: 2, after: $endCursor) {
        edges {
          node {
            title
          }
        }
        pageInfo {
          endCursor
          hasNextPage
        }
      }
    }
  }'

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

glab(1)