API-lekérdezések

A lekérdezési ciklus külső API-ból is le tud kérni JSON-adatot, és a visszakapott tömb elemeit cikluselemként jeleníti meg. API-lekérdezést akkor használj, ha az adat nem a WordPressben van:

• egy külső készletnyilvántartó rendszer termékei,
• egy nyilvános API receptjei, könyvei, eseményei vagy állásai,
• egy másik WordPress-oldal REST API-ja,
• egy egyedi háttérrendszer strukturált adata,
• egy táblázat vagy no-code eszköz, amely JSON-t ad egy végponton.

Hogyan működik?

Az API-lekérdezési ciklus ebben a sorrendben dolgozik:

1. A ciklus elem lekérdezéstípusa API.
2. Az API-beállítások ablakban beállítod a kérést.
3. A Bricks a legtöbb API-beállításban feldolgozza a dinamikus adatot.
4. A Bricks összeállítja a kérés URL-jét, fejléceit, engedélyezését, törzsét és lapozási paramétereit.
5. Ha a gyorsítótár be van kapcsolva, ellenőrzi azt.
6. A kérést a WordPressen keresztül elküldi.
7. A JSON-választ dekódolja.
8. Kinyeri a beállított válaszútvonalat.
9. A kinyert tömb lesz a lekérdezés eredménye.
10. A ciklus a tömb minden elemét egyszer jeleníti meg.

Csak tömbadat járható be. Ha a válaszútvonal objektumra, szövegre, számra vagy nem létező útvonalra mutat, a ciklus nem tudja megjeleníteni a kívánt eredményhalmazt.

API-lekérdezési ciklus létrehozása

1. Adj hozzá egy támogatott ciklus elemet: Tároló, Blokk vagy Div.
2. Kapcsold be a Lekérdezési ciklus kapcsolót.
3. A Lekérdezés vezérlőben a Típus legyen API.
4. Kattints az API-beállítások gombra.
5. Add meg az API URL-jét és a kérés beállításait.
6. Kattints az Adatok lekérése gombra az előnézeti panelen.
7. Állítsd be a válaszútvonalat úgy, hogy a bejárni kívánt tömbre mutasson.
8. Mentsd az API-beállításokat.
9. Adj hozzá gyermekelemeket a cikluson belül.
10. Az egyes elemek mezőit a {query_api} dinamikus címkékkel jelenítsd meg.

https://minta-bolt.hu/lekerdezes-teszt/?bricks=run

A képen az API-beállítások ablak látszik: bal oldalon az API: kérelem beállításai (név, URL, HTTP metódus, engedélyezés, headerek), jobb oldalon az API: Válasz előnézet az Adatok lekérése gombbal. Az ablak tetején a felirat figyelmeztet: ez kísérleti funkció, és API-kéréseknél a lekérdezési szűrők és az összetevők nem támogatottak.

Az API-beállítások ablak

Az ablak bal oldalán a beállítások, jobb oldalán a válasz előnézete van. Építés előtt érdemes az előnézettel ellenőrizni a kérést: ha a Bricks nem tudja lekérni vagy értelmezni a választ, először a kérést javítsd.

Kérésbeállítások

Név

Az API-beállítás belső elnevezése, nem kötelező. Ha egy oldalon több API-lekérdezés van, segít megkülönböztetni őket. Például: Books API, Events endpoint, Remote WP posts.

URL

Kötelező. Annak a végpontnak a teljes URL-je, amely JSON-t ad vissza. Például:

https://example.com/wp-json/wp/v2/posts

Az URL-ben a dinamikus adat támogatott. A név és a válaszútvonal nem kapja meg a dinamikus adat feldolgozást.

HTTP metódus

Két metódus választható: GET és POST. A szokásos, csak olvasó listákhoz GET kell. POST-ot akkor használj, ha az API törzset vár.

Headerek

A Bricks alapból ezeket a fejléceket küldi:

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

A Hozzáadás header gombbal további fejléceket adhatsz meg, vagy felülírhatod az alapértelmezetteket.

URL-paraméterek

Az URL-paraméterek a végpont lekérdezési karakterláncához adódnak. Példa:

Kulcs	Érték
limit	5
category	news

Ha az URL már tartalmaz lekérdezési paramétereket, a Bricks egyesíti a meglévőket a beállítottakkal.

Kérés törzse

A kérés törzsének beállításai POST kérésnél jelennek meg. Három törzstípus támogatott:

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

JSON esetén a nyers JSON-törzset írd be. Űrlap módokban kulcs-érték sorokat adj meg. A lapozási paraméterek is a törzsbe kerülhetnek, ha a lapozás a törzs helyét használja.

Engedélyezés

A Bricks ezeket támogatja:

• API-kulcs,
• Bearer token,
• Basic Auth.

Az API-kulcsot a fejlécben vagy az URL-paraméterekben is elküldheted. A Bearer token és a Basic Auth az Authorization fejlécet használja.

Érzékeny értékeknél kapcsold be az engedélyezésnél a PHP-konstans használatát. Ilyenkor a Bricks a titkos adatot egy PHP-konstansból olvassa, nem a szerkesztőben tárolja. A konstansok nevei a lekérdezés elemének azonosítójából épülnek fel:

define( 'BRX_QUERY_API_KEY_ABC123', 'your-api-key' );
define( 'BRX_QUERY_BEARER_TOKEN_ABC123', 'your-token' );
define( 'BRX_QUERY_BASIC_AUTH_USERNAME_ABC123', 'username' );
define( 'BRX_QUERY_BASIC_AUTH_PASSWORD_ABC123', 'password' );

Az ABC123 helyére a lekérdezés elemének azonosítója kerül nagybetűvel. Éles hitelesítő adatokhoz használj konstansokat: a szerkesztőben tárolt titkos adatok könnyebben kiszivároghatnak exportban, képernyőképen vagy a csapattagok hozzáférésén keresztül.

Dinamikus adat az API-beállításokban

Az API-beállítások legtöbb szöveges mezőjében használhatsz Bricks dinamikus adatot. Ide tartozik az URL, a fejlécek, a paraméterek, a törzs értékei és az engedélyezési értékek, ha közvetlenül a beállításokban vannak tárolva.

Szándékosan nem dolgozza fel a dinamikus adatot:

• az API neve,
• a válaszútvonal.

A dinamikus API-beállítások a kérés pillanatában, az aktuális oldal környezete szerint oldódnak fel. Ez olyan végpontoknál hasznos, amelyek az aktuális bejegyzéstől, felhasználótól, kifejezéstől vagy az URL állapotától függenek. Példák:

https://example.com/api/events?city={acf_city}

{
  "postId": "{post_id}"
}

Válasz előnézete

Az Adatok lekérése gombbal előnézetet kapsz a válaszról. Az előnézetben láthatod:

• a teljes válaszfát,
• a kinyert válaszútvonalat,
• a nyers JSON nézetet,
• az utolsó lekérés idejét,
• a hibaállapotot.

Ha az utolsó lekérés óta módosítottad a beállításokat, a Bricks kéri, hogy az előnézet használata előtt kérd le újra az adatokat. Nagy kinyert tömböknél előfordulhat, hogy az előnézet csak az első részt mutatja, de a mentett API-lekérdezés rendereléskor a beállított választ használja.

Válaszútvonal

A Válasz elérési útja megmondja, hogy a JSON-válasz melyik része legyen a ciklus eredménye. Hagyd üresen, ha a válasz legfelső szintje már maga a bejárni kívánt tömb. Beágyazott adatnál pontos jelölést használj:

data.results

Példaválasz:

{
  "data": {
    "results": [
      { "name": "Recipe A" },
      { "name": "Recipe B" }
    ]
  }
}

Ehhez a válaszhoz az útvonal: data.results.

API-mezők megjelenítése

A ciklusban a query_api dinamikus címkét használd.

Alapmező:

{query_api @key:'name'}

Beágyazott mező:

{query_api @key:'title|rendered'}

A függőleges vonal (|) választja el a beágyazott kulcsokat az aktuális tömbelemen belül.

Az API-válasz előnézetében egy mező fölé víve a kurzort kimásolhatod a kész dinamikus adatcímkét. Parancsikont is létrehozhatsz, ami megjelenik a dinamikus adatok választójában.

Lapozás

Az API-lekérdezési ciklusok támogatják a lapozást, ha az API fogadhat oldal- vagy eltolás-paramétert, és a válasz oldalszámot vagy elemszámot is megad. A lapozás bekapcsolása:

1. Kapcsold be az API-beállításokban a Van lapozás lehetőséget.
2. Adj hozzá egy Lapozás elemet az oldalhoz.
3. Állítsd a Lapozás elemet az API-lekérdezés célzására.
4. Válaszd ki a lapozási módszert.
5. Állítsd be, hová küldje a Bricks a lapozási paramétert.
6. Állítsd be a teljes elem-/oldalszám útvonalát.

A paraméter helye lehet: URL-paraméter, fejléc vagy a kérés törzse.

Oldalszám alapú lapozás

Akkor használd, ha az API oldalszámot vár, például page=3. A WordPress REST API-hoz:

Beállítás	Példa
URL-paraméter	page
Oldalankénti elemek paramétere	per_page=10
Teljes szám útvonala	header.x-wp-totalpages

Oldalszám alapú lapozásnál a Bricks a kinyert teljes értéket az oldalak teljes számának tekinti.

Eltolás alapú lapozás

Akkor használd, ha az API eltolást vagy kihagyási értéket (offset, skip) vár, például limit=5&skip=10.

• Az oldalparaméter legyen az az eltolás- vagy kihagyási paraméter, amelyet a Bricks frissít.
• Az eltolás kulcsa az a paraméter vagy fejléc, amely az oldalankénti elemszámot tartalmazza.
• Az oldalankénti elemszám URL-paraméterben vagy fejlécben maradjon, hogy a Bricks ki tudja számolni az oldalak számát.
• A teljes szám útvonala numerikus teljes elemszámra mutasson.

Eltolás alapú lapozásnál a Bricks a teljes elemszámot elosztja az oldalankénti elemszámmal, így kapja meg az oldalak számát.

Gyorsítótár időtartama

Az API-válaszokat a Bricks WordPress átmeneti adatokkal (transient) gyorsítótárazza, ha a Gyorsítótár időtartama (sec) nagyobb, mint 0. Az alapértelmezett érték 300 másodperc (öt perc).

• A 0 kikapcsolja a gyorsítótárazást.
• Fejlesztés közben állíts be rövid értéket.
• Lassú vagy kérésszámra korlátozott API-nál állíts be hosszabbat.

A gyorsítótár kulcsa a kérés részleteiből épül fel: végpont, metódus, fejlécek, URL-paraméterek és törzs. A különböző kérésparaméterek különböző gyorsítótár-bejegyzéseket hoznak létre. Ha az API-válasz nem a várt módon frissül, csökkentsd a gyorsítótár időtartamát, ideiglenesen állítsd 0-ra, vagy kattints az Adatok lekérése gombra az API-beállítások ablakban: ez törli az adott elem API-gyorsítótárát.

Hibaállapotok

A Bricks hibát jeleníthet meg vagy adhat vissza:

• hiányzó vagy érvénytelen API-végpont,
• WordPress-kérési hiba,
• HTTP-hiba (például 401, 403, 404 vagy 500),
• üres választörzs,
• JSON-dekódolási hiba,
• érvénytelen lapozásbeállítás,
• hiányzó teljes szám útvonal lapozáshoz,
• olyan válaszútvonal, amely nem a várt adatra mutat.

Gyakori megoldások:

• Teszteld a végpontot böngészőben vagy API-kliensben.
• Ellenőrizd, hogy az API JSON-t ad vissza, nem HTML-t.
• Ellenőrizd a hitelesítő adatokat vagy a PHP-konstansokat.
• A CORS-t csak akkor ellenőrizd, ha egyéni frontend szkriptek hívják közvetlenül az API-t. A Bricks szerveroldali kéréseket indít a WordPressen keresztül.
• A válaszútvonal a tömbre mutasson, ne egyetlen objektumra.
• Hibakeresés közben állítsd ideiglenesen 0-ra a gyorsítótár időtartamát.

Korlátok

Az API-lekérdezési ciklusok szándékosan szűkebbek a bejegyzés-, kifejezés- és felhasználó-lekérdezéseknél:

• nincsenek lekérdezési szűrők,
• nincs élő keresés,
• nincsenek Bricks komponensek,
• csak JSON-válasz használható,
• a válasznak tömbre kell feloldódnia,
• a query_api dinamikus címkéken kívül nincs beépített sémaleképezés,
• távoli URL-ekről nincs automatikus médiaimport,
• korlátozott kérésszámú API-knál nincs automatikus újrapróbálkozás vagy késleltetés,
• a titkos adatokat gondosan, PHP-konstansokon keresztül kezeld.

Ha szűrésre, keresésre, rendezésre vagy összetett adatösszekapcsolásra van szükséged, fontold meg a külső adat WordPressbe szinkronizálását vagy egyéni integráció építését.

Gyakorlati példák

WordPress REST API bejegyzések

• URL: https://example.com/wp-json/wp/v2/posts
• URL-paraméter: per_page = 6
• Válaszútvonal: hagyd üresen, mert a WordPress REST API legfelső szinten tömböt ad vissza.
• Megjelenítendő mezők:

{query_api @key:'title|rendered'}
{query_api @key:'excerpt|rendered'}

DummyJSON termékek

• URL: https://dummyjson.com/products
• URL-paraméter: limit = 8
• Válaszútvonal: products
• Megjelenítendő mezők:

{query_api @key:'title'}
{query_api @key:'price'}
{query_api @key:'thumbnail'}

Hibaelhárítás

A ciklus nem jelenít meg semmit. Ellenőrizd, hogy a válaszútvonal tömbre mutat-e. Ha az API objektumot ad vissza, benne a tömbbel, a válaszútvonalat a beágyazott tömbre állítsd.

Az előnézet működik, de a frontend kimenete elavult. Ellenőrizd a gyorsítótár időtartamát. Az előnézet és a frontend is használhat gyorsítótárazott választ, amíg a gyorsítótár be van kapcsolva.

A hitelesítés egy felhasználónál működik, a másiknál nem. Hitelesítő adatokhoz PHP-konstansokat használj a szerkesztőben tárolt titkos adatok helyett. Ellenőrizd, hogy a konstansok nevei a lekérdezés elemének nagybetűs azonosítóját használják.

A lapozás mindig csak egy oldalt mutat. Ellenőrizd a teljes elemszám útvonalát. Oldalszám alapú lapozásnál az oldalak teljes számára kell feloldódnia, eltolás alapúnál a teljes elemszámra, és a Bricksnek meg kell tudnia állapítani az oldalankénti elemszámot.

Az eltolás alapú lapozás rossz oldalt ad. Az eltolás kulcsa az a paraméter legyen, amely a kiszámított eltolást kapja. A limit=5&skip=10 esetén az eltolás kulcsa a skip, a limit pedig az oldalankénti elemszám.

A dinamikus címkék hiányoznak egy másik böngészőben. Az API-ablakban létrehozott parancsikonok a böngésző helyi tárolójában (localStorage) vannak. Hozd létre újra a parancsikont abban a böngészőben, vagy írd be kézzel a query_api címkét.

A lekérdezési szűrők nem jelennek meg az API-lekérdezés beállításaiban. Ez a normális működés: az API-lekérdezési ciklusok nem támogatják a lekérdezési szűrőket és az élő keresést.