# API-lekérdezések

> Külső JSON API adatainak megjelenítése lekérdezési ciklussal: kérés, engedélyezés, válaszútvonal, lapozás, gyorsítótár, hibák és korlátok.

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.

![A Lekérdezés vezérlő API típussal és az API-beállítások gombbal](./kepek/dinamikus-tartalom-api-beallitasok.webp)

*A Lekérdezés vezérlő API típussal és az API-beállítások gombbal* (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:

```php
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}
```

```json
{
  "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:

```json
{
  "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.