# Abilities API áttekintés

> A WordPress Abilities API és a MainWP képességei: követelmények, hitelesítés, felderítés, futtatás, bemeneti formátumok, hibakódok.

A WordPress Abilities API a WordPress magjának része (WordPress 6.9-től), és egységes nyilvántartást ad a bővítmények képességeihez. Minden bővítmény külön „képességként” (ability) regisztrálhat egy-egy műveletet, megadott bemeneti és kimeneti szerkezettel. Így az AI-ügynökök, az automatizáló platformok és a külső eszközök maguktól megtudhatják, mit tud a bővítmény, és egységes felületen futtathatják.

A MainWP vezérlőpult 102 képességet regisztrál hét kategóriában. A régebbi vezérlőpult-kiadások kisebb katalógust adnak.

## Hogyan működik

Az Abilities API egy felderítő réteget ad a WordPresshez. A kliens a `/wp-abilities/v1/abilities` címet lekérdezve megkapja az összes elérhető műveletet, azok bemeneti és kimeneti szerkezetét és a viselkedésüket leíró jelöléseket. Ebből a bemenetek automatikusan ellenőrizhetők, és a lehetséges műveletek dinamikusan felfedezhetők.

Ha AI-asszisztenst (Claude, VS Code Copilot, Cursor) szeretnél a vezérlőpulthoz kötni, ezt a MainWP MCP-szerver végzi: a MainWP képességeit eszközként adja át az asszisztensnek. Lásd az **AI** menüről szóló fejezetet.

## Követelmények

- WordPress 6.9 vagy újabb
- MainWP vezérlőpult 6.0 vagy újabb
- Olyan WordPress-felhasználó, akinek van `manage_options` jogosultsága
- WordPress-alkalmazásjelszó vagy más, a WordPress REST API-jában használható hitelesítés

## Alap URL

Minden végpont a WordPress képességeinek névterében van:

```text
https://a-te-vezerlopultod.hu/wp-json/wp-abilities/v1/
```

## Hitelesítés

Az Abilities API a WordPress REST API bármelyik hitelesítési módját elfogadja.

### MainWP API-kulcsok

A MainWP REST API-kulcsai a MainWP saját REST-névtereit hitelesítik (például `mainwp/v2`). Az Abilities-útvonalakat (`wp-abilities/v1`) **nem** hitelesítik, akkor sem, ha a képesség neve `mainwp/`-pal kezdődik. Az Abilities API-hoz használj alkalmazásjelszót.

### Alkalmazásjelszavak

Hozz létre alkalmazásjelszót az **API-hozzáférés → Alkalmazásjelszavak** oldalon (a lépéseit az Alkalmazásjelszavak fejezet írja le), majd használd így:

```bash
curl -u "FELHASZNALONEV:ALKALMAZASJELSZO" \
  "https://a-te-vezerlopultod.hu/wp-json/wp-abilities/v1/abilities"
```

A vezérlőpult 6.3-tól a **MainWP → AI → MainWP MCP** és a **MainWP → AI → MainWP Control** oldalon is tud helyben jelszót létrehozni.

### Webhelyhozzáférés és műveleti jogosultságok

A hitelesítés nem írja felül a felhasználó webhelyhozzáférését és a Team Control jogosultságokat. A vezérlőpult ellenőrzi a kért webhelyeket és a művelethez szükséges jogot. Például:

- a bővítmények frissítéséhez frissítési jog kell a bővítményekre,
- a webhely törléséhez webhelytörlési jog,
- az ügyfelek módosításához ügyfélkezelési jog,
- a címkék módosításához csoportkezelési jog.

Ha egy hívás több frissítéstípust érint, mindegyikhez kell jogosultság. A háttérben futó feladatok a végrehajtáskor újra ellenőrzik tulajdonosuk jogait és webhelyhozzáférését, ezért a sorba állított feladat nem garantálja, hogy az eredetileg kijelölt webhelyeken és műveleteken végig engedélyezett marad. A kiegészítők képességeihez külön kiegészítő- és műveleti jogosultság is kellhet.

## Felderítő végpontok

### Az összes képesség listája

```text
GET /wp-json/wp-abilities/v1/abilities
```

Lapozva adja vissza a regisztrált képességeket.

| Paraméter | Típus | Alapérték | Leírás |
|---|---|---|---|
| `page` | egész | 1 | Oldalszám |
| `per_page` | egész | 50 | Elemek száma oldalanként (legfeljebb 100) |
| `category` | szöveg | | Szűrés a kategória azonosítójára |

```bash
curl -u "admin:xxxx" \
  "https://a-te-vezerlopultod.hu/wp-json/wp-abilities/v1/abilities?category=mainwp-sites"
```

### Egy képesség lekérdezése

```text
GET /wp-json/wp-abilities/v1/abilities/{név}
```

Egy képesség teljes leírását adja, a bemeneti és kimeneti szerkezettel együtt:

```bash
curl -u "admin:xxxx" \
  "https://a-te-vezerlopultod.hu/wp-json/wp-abilities/v1/abilities/mainwp/list-sites-v1"
```

### Kategóriák

```text
GET /wp-json/wp-abilities/v1/categories
```

A MainWP ezeket a kategóriákat regisztrálja:

| Kategória | Képességek száma | Tartalom |
|---|---|---|
| `mainwp-sites` | 30 | Webhelyek kezelése és figyelése |
| `mainwp-updates` | 14 | Frissítések felderítése, előnézettel végzett végrehajtás, webhelyszintű tiltások eltávolítása |
| `mainwp-clients` | 11 | Ügyfélkezelés |
| `mainwp-tags` | 7 | Címkék (csoportok) kezelése |
| `mainwp-batch` | 1 | Kötegelt műveletek figyelése |
| `mainwp-knowledge` | 7 | Ügynökségi, ügyfél- és webhely-Knowledge olvasása, rekordok kezelése |
| `mainwp-backups` | 32 | Beépített mentési feladatok, pillanatképek, visszaállítások, tárolók és beállítások |

A kategóriák részleteit a következő fejezetek írják le: webhelyek, frissítések, ügyfelek, címkék, kötegelt műveletek és biztonsági mentések.

## Kiegészítők képességei

A MainWP kiegészítői további képességeket regisztrálhatnak a 102 vezérlőpult-képesség mellé. Ezek csak akkor jelennek meg, ha az adott kiegészítő aktív. Mind a `mainwp/` névtérben vannak.

| Kiegészítő | Kategória | Képességek |
|---|---|---|
| Advanced Uptime Monitor (képességtámogatással) | `mainwp-advanced-uptime-monitor` | 7 |
| Cache Control 5.3 vagy újabb | `mainwp-cache-control` | 8 |
| Clone 5.1 vagy újabb | `mainwp-clone` | 3 |
| Custom Dashboard 5.2 vagy újabb | `mainwp-custom-dashboard` | 4 |
| Google Search Console 6.3 vagy újabb | `mainwp-google-search-console` | 10 |
| Matomo 5.2 vagy újabb | `mainwp-matomo` | 12 |
| WooCommerce Shortcuts 5.1 vagy újabb | `mainwp-woocommerce-shortcuts` | 1 |

Mire jók ezek:

- **Cache Control:** gyorsítótár-állapot olvasása, törlési szabályok módosítása, Cloudflare-hitelesítő adatok ellenőrzése, egy webhely gyorsítótárának törlése. Külön fejezet írja le.
- **Clone:** a tárolt szabály állapota, a globális engedélyezés és a webhelyenkénti részvétel beállítása.
- **Custom Dashboard:** kódrészletek metaadatai, PHP-ellenőrzés, előnézettel végzett csere és eltávolítás.
- **Google Search Console:** kapcsolat- és tulajdonságolvasás, webhely-hozzárendelések, gyorsítótárazott teljesítményösszesítők, frissítési beállítások és háttérfrissítő feladatok.
- **Matomo:** kapcsolatkezelés, előnézettel végzett webhely-hozzárendelés, gyorsítótárazott elemzések és trendek, ütemezett frissítések állapottal és megszakítással.
- **WooCommerce Shortcuts:** egy engedélyezett webhely gyorsítótárazott WooCommerce-állapotának olvasása.
- **Advanced Uptime Monitor:** gyorsítótárazott monitorok és események, élő uptime-összesítők, monitor létrehozása, állapotváltása és törlése, a nyilvántartás szinkronizálása. Ezekhez a képességekhez a kiegészítő képességtámogatást tartalmazó kiadása kell, a korábbi csomagokban nincsenek meg.

Az UpdraftPlus kiegészítő 5.2-es kiadása előkészíti a jövőbeli mentési képességeket, de ezek alapértelmezés szerint ki vannak kapcsolva, amíg nincs hozzájuk kompatibilis MainWP Child. A kiegészítő aktiválása nem teszi elérhetővé őket az Abilities API-n és a MainWP AI-asszisztensen át, a MainWP Child 6.3-ra frissítése sem. Ebben a kiadásban az UpdraftPlus mentéseit a vezérlőpult felületén kezeld.

## Képességek futtatása

### Végpont

```text
GET|POST|DELETE /wp-json/wp-abilities/v1/abilities/{név}/run
```

### HTTP-metódus

A metódust a képesség `meta.annotations` jelölései döntik el:

- **GET:** csak olvasó képességek (`readonly: true`), azok is, amelyek bemenetet kérnek.
- **DELETE:** nem csak olvasó képességek, ha a `destructive` és az `idempotent` is `true`.
- **POST:** minden más írási képesség, a `destructive: true`, de `idempotent: false` jelölésűek is.

Például a `mainwp/delete-tag-v1` DELETE-et használ, a `mainwp/delete-site-v1` és a `mainwp/delete-client-v1` POST-ot. Rossz metódusra a válasz `rest_ability_invalid_method` hiba, HTTP 405-tel.

### Bemenet átadása

**GET kérés:** ha a képesség sémája ad megfelelő alapértékeket, bemenet nélkül is hívhatod. Szűrőkhöz és kötelező értékekhez a bemeneti objektumot JSON-ként add át az `input_json` lekérdezési paraméterben. A helyes kódoláshoz használd a `curl -G` mellé a `--data-urlencode` kapcsolót:

```bash
curl -G -u "admin:xxxx" \
  --data-urlencode 'input_json={"site_id_or_domain":1,"include_stats":true}' \
  "https://a-te-vezerlopultod.hu/wp-json/wp-abilities/v1/abilities/mainwp/get-site-v1/run"
```

Az `input_json` megőrzi a JSON-típusokat (logikai érték, tömb, `null`), így a séma szerinti ellenőrzés pontos. Az értéknek objektumnak kell lennie, és legfeljebb 8 KiB (8192 bájt) lehet. Az `input` és az `input_json` paramétert ne küldd együtt. A régi, szögletes zárójeles lekérdezési paraméterek továbbra is működnek, de az egyszerű `input` paraméterben átadott JSON-szöveget az illesztő nem fejti vissza. A hitelesítő adatokat ne tedd a lekérdezési szövegbe.

**POST kérés:** az `input` objektumot a JSON-törzsben add át:

```bash
curl -X POST -u "admin:xxxx" \
  -H "Content-Type: application/json" \
  -d '{"input":{"site_ids_or_domains":[1]}}' \
  "https://a-te-vezerlopultod.hu/wp-json/wp-abilities/v1/abilities/mainwp/sync-sites-v1/run"
```

**DELETE kérés:** `application/json` törzset használj, amely csak az `input` objektumot tartalmazza, így a bemenet nem kerül az URL-be. Például egy címke törlésének előnézete:

```bash
curl -X DELETE -u "admin:xxxx" \
  -H "Content-Type: application/json" \
  -d '{"input":{"tag_id":1,"dry_run":true}}' \
  "https://a-te-vezerlopultod.hu/wp-json/wp-abilities/v1/abilities/mainwp/delete-tag-v1/run"
```

Az előnézet átnézése után futtasd le a műveletet `confirm: true` és `dry_run: false` értékekkel. A DELETE törzse legfeljebb 1 MiB (1 048 576 bájt) lehet. A törzset ne kombináld `input` vagy `input_json` lekérdezési paraméterrel. A szögletes zárójeles `input` lekérdezési paraméterek törzs nélkül még működnek, de a JSON-törzs az ajánlott. Az `input_json` csak GET-hez használható.

Hibás JSON, egymásnak ellentmondó bemeneti források, nem támogatott DELETE-törzs és az átviteli korlátot meghaladó méret esetén a válasz `mainwp_abilities_invalid_input_transport` hiba, HTTP 400-zal. Az érvényes átvitelnek még át kell mennie az adott képesség bemeneti sémáján és jogosultsági ellenőrzésén.

## Válaszformátum

### Sikeres válasz

A képességek közvetlenül a kimeneti sémájuk szerinti adatot adják vissza:

```json
{
  "items": [
    {
      "id": 1,
      "url": "https://example.com",
      "name": "Az én webhelyem",
      "status": "connected"
    }
  ],
  "page": 1,
  "per_page": 20,
  "total": 150
}
```

### Hibák

A hibaválaszok a WordPress REST API szokásos formáját követik:

```json
{
  "code": "ability_invalid_input",
  "message": "Invalid parameter: site_id_or_domain is required",
  "data": {
    "status": 400
  }
}
```

## Képességjelölések

Minden képességhez tartozik egy metaadat-blokk, amely a viselkedését írja le:

| Jelölés | Típus | Jelentés |
|---|---|---|
| `readonly` | logikai | `true`, ha a képesség csak olvas |
| `destructive` | logikai | `true` védett változtatásnál: törlésnél, a 6.3-tól pedig a frissítések végrehajtásánál és a tiltások eltávolításánál is |
| `idempotent` | logikai | `true`, ha az ismételt hívás nem okoz további hatást |
| `instructions` | szöveg | Egyedi használati útmutató |

A jelölések segítenek az AI-ügynököknek eldönteni, melyik képességet milyen sorrendben hívják.

## Hibakódok

### Az Abilities API hibái

| Kód | HTTP | Jelentés |
|---|---|---|
| `ability_invalid_input` | 400 | A bemenet nem felel meg a JSON-sémának |
| `ability_missing_input_schema` | 400 | A kötelező bemenet hiányzik |
| `ability_invalid_permissions` | 403 | A jogosultsági ellenőrzés elutasította a hívást |
| `ability_invalid_output` | 500 | A kimenet nem felel meg a sémának |
| `rest_ability_not_found` | 404 | A képesség nincs regisztrálva |
| `rest_ability_invalid_method` | 405 | Rossz HTTP-metódus a képesség típusához |

### MainWP-specifikus hibák

| Kód | HTTP | Jelentés |
|---|---|---|
| `mainwp_abilities_invalid_input_transport` | 400 | Érvénytelen JSON, ütköző bemeneti források vagy túllépett méretkorlát |
| `mainwp_site_not_found` | 404 | A webhelyazonosító vagy a tartomány nem található |
| `mainwp_client_not_found` | 404 | Az ügyfélazonosító vagy az e-mail-cím nem található |
| `mainwp_tag_not_found` | 404 | A címkeazonosító nem található |
| `mainwp_job_not_found` | 404 | A kötegelt feladat lejárt vagy nem található |
| `mainwp_confirmation_required` | 400 | A romboló művelet nem kapta meg a `confirm: true` értéket |
| `mainwp_site_offline` | 503 | A webhely nem érhető el |
| `mainwp_module_not_available` | 501 | A szükséges modul nem aktív |

## Opcionális modulokhoz kötött képességek

Néhány képességhez választható MainWP-modul kell:

| Modul | Érintett képességek |
|---|---|
| Cost Tracker (költségkövető) | `get-site-costs-v1`, `get-client-costs-v1` |
| Logs (naplók) | `get-site-changes-v1` |

Ha a szükséges modul nem aktív, a képesség `mainwp_module_not_available` hibát ad.