Termék eszközök

Áttekintés

Két eszköz fedi le egy márka termékkatalógusát: a manage_product_source beköti és karbantartja azokat a helyeket, ahonnan a termékek érkeznek, a manage_product_rules pedig megírja a szöveget, amit az AI-nak követnie kell, valahányszor említ egyet.

Ezek az eszközök ugyanabba a Vex AI eszközkategóriába tartoznak, mint a chatbot eszközök, tehát egy kategóriákat mutató MCP kliensben ott találod meg őket. Amit viszont szabályoz, az a Tartalomforrások jogosultság, nem a Vex AI.

Hogy mindez mit jelent a termékben, arról az irányítópulti dokumentáció szól: termékszabályok és termékforrások.

manage_product_rules

Termékszabályokat hoz létre, szerkeszt, hagy jóvá és töröl. Egy szabály kulcsok listájából (a szavak, amik közösek a szabályban és a termékben, jellemzően egy összetevő neve) és a szövegből áll, amit az AI szó szerint elolvas.

Paraméterek

Hogyan működik

Az illesztés pontos, soha nem közelítő. Egy szabály akkor vonatkozik egy termékre, ha közös kulcsuk van, normalizálás után összevetve — kisbetűsítve, ékezetek nélkül, összevont írásjelekkel. Tedd ugyanannak a dolognak minden írásmódját egyetlen szabály keys mezőjébe; a szinonimákat és a fordításokat nem illesztjük helyetted.

always kontra when_relevant. Egy always szabály minden egyes alkalommal átmegy, amikor egy illeszkedő termék szóba kerül — ezt használd feltételekre, korlátozásokra és kötelező figyelmeztetésekre. Egy when_relevant szabályt a látogató kérdéséhez mérten szűrünk — ezt használd az egyes engedélyezett állításokra, hogy egy hosszú lista ne érkezzen meg egyszerre.

Tömeges jóváhagyás és törlés. Az approve és a delete is elfogad vagy egy kifejezett ids listát, vagy az allDrafts: true értéket egy brandId mellé, opcionálisan importId-vel leszűkítve. Csak a piszkozat sorokat hagyjuk jóvá. Egy szabály nem aktiválható legalább egy kulcs nélkül — a kulcs nélküli szabályokat tartalmazó köteg hibára fut, és megnevezi őket.

A bulk_create mindent vagy semmit. Legfeljebb 200 szabály kerül be egyetlen utasításban; ha a szervezet 20 000 szabályos korlátja beleszól, semmi nem kerül be.

manage_product_source

Beköti és kezeli a katalógusokat, ahonnan a termékek érkeznek.

Paraméterek

Hogyan működik

Egyedül a create válasza mutatja meg a titkot. Visszaadja a forrást, a secret értékét, a push_url címet, ahová a webshopod postázhat, és egy emlékeztetőt arról, hogy a webshop a szervezet API kulcsával hitelesít a Y-API-Key fejlécben. Minden más válasz elhagyja a titkot, és csak a has_secret értéket, valamint az egyedi fejlécek nevét adja vissza.

Csak az api forrás hordozhat szabályokat. A CSV folyam egyszerű termékek Google Shopping fájlja — nincs kulcsa, nincs szabálya, nincsenek változatai, nincs küldési végpontja, és megengedett hozzá a http.

Az api forrás által szolgáltatott JSON egyetlen, egymásba ágyazott alak. Egy termék hordozza az id, title, link mezőt, és opcionálisan a description, image, category, brand, priority, attributes, search_terms, rule_keys, rules és variants mezőt. A variants minden eleme egy megvásárolható változat, saját id, options ({"Íz": "Pisztácia", "Kiszerelés": "1 kg"}), price, sale_price, availability, link, image, attributes, priority, search_terms, rule_keys és rules mezőkkel. Egy variants nélküli termék egyszerű termék, ami a saját árát és készletét hordozza — ezért érvényes ma is egy olyan feed, ami a változatok bevezetése előtt készült. A category útvonal: "Fehérje > Tejsavó" vagy ["Fehérje", "Tejsavó"], legfeljebb hat szint, szintenként 100 karakterrel, és egy CSV product_type oszlopa ugyanígy bomlik szét. Teljes leírás: A Termék API.

A keyFields azonnal életbe lép, a termékeken és a változataikon is. A módosítása újraszámolja a forrás minden termékének kulcsait — a megnevezett mezőket a terméken és mindegyik változatán beolvasva —, újbóli beolvasás és újraindexelés nélkül.

A fetch_now forrásonként ötperces várakozási időt tart. Ezen belül az eszköz { started: false } választ ad a hátralévő idővel — ez válasz, nem hiba. Egyébként run_id értéket ad vissza; a befejeződést a product_sources erőforráson futtatott get_record hívással követheted.

Termékek, források és szabályok olvasása

Három erőforrás érhető el az Adathozzáférési eszközökön keresztül, ugyanazzal a Tartalomforrások jogosultsággal:

Mindhárom elfogadja a brandId paramétert. A products emellett a sourceId, a product_rules pedig a ruleStatus, a ruleMode és az importId paramétert is. A product_rules és a products egyaránt elfogadja a key paramétert — ez a normalizált kulcs, amin a kettő illeszkedik, tehát az ékezetek és az írásjelek nem számítanak —, valamint a search paramétert, ami a szabály szövegére vagy a termék címére illeszkedik.

A get_record hívásnál egy szabály ezen felül jelenti a matched_products_count értéket (hány termékhez jut el ma), egy termék pedig a matched_rules mezőt (minden rá vonatkozó szabályt, a piszkozatokkal együtt) — a kettő együtt a leggyorsabb módja annak, hogy jóváhagyás előtt ellenőrizz egy szabálykészletet.

Példa utasítások

Create a product API source called "Shop feed" on brand <id>, reading https://shop.example.com/yaplet/products every day, and turn the Ingredients field into keys.

Bulk-create these permitted claims as draft rules on brand <id>, one Always rule per substance — consolidate all of that substance's permitted claims into one rule — keyed on the substance name and its common synonyms.

Show me every product on brand <id> that has no keys, so I know which ones no rule can reach.

How many products does the rule with id <id> currently apply to?