پرش به محتویات

دریافت داده از APIها (Query Data from APIs)

از Bricks 2.1 می‌توانید از Query Loop builder قدرتمند برای دریافت و نمایش داده از یک API endpoint استفاده کنید — بدون نوشتن PHP سفارشی.

این قابلیت آزمایشی برای نمایش محتوا از سرویس‌های third-party، APIهای عمومی‌یا حتی سایت وردپرس دیگر از طریق REST API ایده‌آل است.

YouTube
YouTube ↗

شروع کار

یک Query Type جدید به نام API به شما امکان می‌دهد به REST API متصل شوید و داده مصرف کنید. پس از پیکربندی، پاسخ API parse شده و با سیستم تگ داده پویای Bricks رندر می‌شود — درست مانند هر Query Loop دیگر.

برای شروع:

  1. هر المان nestable که Query Loop را پشتیبانی می‌کند انتخاب کنید (مثلاً Container، Block، Div).
  2. Query Loop را فعال کنید و Query Type را روی API بگذارید.
  3. روی دکمه API Settings کلیک کنید تا popup پیکربندی API باز شود.

نوع Query Loop — API

تنظیمات API

در popup تنظیمات API می‌توانید همه موارد لازم برای فراخوانی API را تعریف کنید — مانند URL endpoint، HTTP method، headerها، parameterها و بیشتر.

پس از پیکربندی می‌توانید داده پاسخ API را fetch کنید و در ستون سمت راست پیش‌نمایش دهید. همچنین می‌توانید تگ‌های داده پویای سفارشی را کپی یا تولید کنید تا داده API را داخل حلقه به‌راحتی رندر کنید.

تنظیمات API Query Loop

Name

برچسب داخلی برای شناسایی این اتصال API (مثلاً «Books API»، «Google Spreadsheet A»).

URL (Required)

URL کامل API بر اساس مستندات.

HTTP Method

تعیین کنید GET (پیش‌فرض) یا POST انجام دهید.

Authorization

API Key (header یا URL parameter)، Bearer Token و Basic Auth را پشتیبانی می‌کند.

برای امنیت بیشتر می‌توانید به‌جای وارد کردن مستقیم مقادیر حساس از ثابت PHP استفاده کنید. گزینه «Use PHP Constant» را تیک بزنید و Bricks نام ثابت را برای شما تولید می‌کند. سپس مقدار آن را در محیط (مثلاً wp-config.php) تعریف کنید و Bricks در درخواست API به آن ارجاع می‌دهد.

Headers

headerهای پیش‌فرض:

  • Content-Type: application/json
  • User-Agent: BricksBuilder/{CURRENT_VERSION}

می‌توانید header بیشتر اضافه کنید یا این پیش‌فرض‌ها را در UI override کنید. این headerها با هر درخواست API ارسال می‌شوند.

URL Parameters

می‌توانید جفت key-value اضافه کنید که به‌عنوان query parameter به URL API append می‌شوند.

مثال: افزودن URL parameter با key limit و value 5 وقتی URL API https://dummyjson.com/recipes است، URL نهایی https://dummyjson.com/recipes?limit=5 تولید می‌شود.

URL Parameters در API Query Loop

Request Body

اگر HTTP method روی POST باشد، می‌توانید request body را در یکی از فرمت‌های زیر ارائه دهید:

  • JSON
  • Form Data
  • x-www-form-urlencoded

برای ارسال payload هنگام تعامل با endpointهای POST-based از این استفاده کنید.

Response path

object path را برای استخراج داده از پاسخ مشخص کنید. برای استفاده از کل پاسخ سطح بالا خالی بگذارید.

مثال: data.results برای گرفتن results از {data: {results: […]}}

مهم

مهم: فقط داده آرایه‌ای قابل حلقه‌زدن است. response path باید آرایه برگرداند! اگر به object resolve شود، Query Loop چیزی رندر نمی‌کند.

Cache duration

برای غیرفعال کردن cache روی 0 بگذارید. پیش‌فرض 300 ثانیه (پنج دقیقه) است.

Bricks پاسخ را با WordPress transients ذخیره می‌کند که به کاهش فراخوانی‌های غیرضروری API هنگام ساخت صفحه یا بازدیدهای مکرر کمک می‌کند.

صفحه‌بندی (Pagination)

Query Loop API در Bricks از pagination پشتیبانی می‌کند — به شرطی که API هدف از طریق شماره صفحه یا offset قابل پیمایش باشد.

برای فعال‌سازی pagination:

  • checkbox «Has pagination» را در تنظیمات API فعال کنید.
  • المان Pagination Bricks را به صفحه اضافه کنید و target query را روی API query loop بگذارید.
  • «Total items path» را تعریف کنید تا Bricks بداند چند صفحه تولید کند.
  • روش pagination «Page number» یا «Offset» را انتخاب کنید و پیکربندی را کامل کنید.

این تضمین می‌کند Bricks pagination را به‌صورت پویا رندر کند و هنگام پیمایش صفحات داده صحیح را بارگذاری کند.

روش pagination: Page number

وقتی API با مشخص کردن شماره صفحه (مثلاً page=3) پشتیبانی می‌کند از این روش استفاده کنید.

مثال: WordPress REST API

  • page را به‌عنوان URL parameter اضافه کنید
  • per_page را برای تعداد آیتم در هر صفحه تنظیم کنید (مثلاً per_page=3)
  • Has pagination را فعال کنید
  • Page parameter را روی page بگذارید

Bricks هنگام تعامل کاربر با المان pagination مقدار page=n را به‌طور خودکار به‌روز می‌کند.

مثال pagination با WordPress REST API

Total Items Path

WordPress REST API x-wp-totalpages را در header پاسخ شامل می‌شود، بنابراین می‌توانید header.x-wp-totalpages را برای فیلد «Total items path» بگذارید.

این به Bricks می‌گوید چند صفحه وجود دارد و ساختار pagination صحیح تولید می‌شود.

روش pagination: Offset

وقتی API به پیمایش مبتنی بر offset نیاز دارد از این استفاده کنید.

مثال: DummyJSON Products API

بر اساس مستندات، برای گرفتن داده صفحه ۳ وقتی limit (آیتم در هر صفحه) 5 است، باید limit=5&skip=10 در درخواست API پاس دهید. در Bricks طبق تصویر زیر تنظیم کنید.

مثال pagination با Offset

با این کار، کلیک روی شماره صفحه «3» در المان pagination پارامتر limit=5&skip=10 هنگام درخواست تولید می‌کند.

توجه کنید body.total را هم در فیلد «Total items path» مشخص کرده‌ایم.

پاسخ API

داده پاسخ API fetch شده در پنل API response سمت راست نمایش داده می‌شود.

این پنل به شما امکان می‌دهد داده پاسخ را در نمای tree (پیش‌فرض) بررسی کنید. روی دکمه «RAW JSON» کلیک کنید تا پاسخ را در فرمت JSON خام ببینید.

استفاده از داده پاسخ API در حلقه

Bricks تگ داده پویای جدید query_api را برای رندر هر بخش از پاسخ API تعریف‌شده از طریق فیلتر @key معرفی می‌کند.

پاسخ API Query Loop

در پاسخ API بالا، برای رندر name دستور، از {query_api:raw @key:name} داخل Query Loop استفاده کنید.

برای خروجی داده تودرتو، مانند عنوان پست در پاسخ WordPress REST API، از delimiter | (pipe) استفاده کنید: {query_api:raw @key:title|rendered}.

همچنین می‌توانید تگ داده پویای را کپی کنید با hover روی dataset موردنظر و کلیک روی آیکون clipboard برای کپی تگ آماده.

سوم، روی آیکون + کنار آیکون clipboard کلیک کنید تا تگ داده پویای سفارشی تولید شود که داخل DD picker در دسترس باشد.

تگ داده پویا در localStorage

یادداشت

یادداشت: تگ داده پویای ایجادشده در localStorage مرورگر ذخیره می‌شود نه پایگاه داده. بنابراین فقط شما در مرورگر خود به آن دسترسی دارید.