Facebook API

A Graph API a Meta platformjainak elsődleges programozási felülete: HTTP alapú API, amellyel alkalmazások adatot kérdeznek le, tartalmat tesznek közzé, médiát töltenek fel és objektumokat kezelnek. A név a közösségi gráfra utal, a modell pedig csomópontokból (node), élekből (edge) és mezőkből (field) áll. Egy csomópont egy egyedi azonosítójú objektum, például egy oldal vagy egy bejegyzés; az él egy csomópont alatti gyűjtemény; a mező pedig egyetlen tulajdonság. A dokumentáció a csomópontot és az élt egyaránt végpontnak nevezi.

A forgalom HTTP/1.1 felett, HTTPS-en megy, és a kérések a graph.facebook.com hosztra érkeznek; egyetlen kivétel a videófeltöltés, amely a graph-video.facebook.com címet használja. A hívásokat verziójelölővel érdemes indítani: a kérési útvonal elején egy v betű és egy verziószám áll. A verzió nélküli hívás az alkalmazás irányítópultján beállított verziót használja, ezért a dokumentáció azt javasolja, hogy a verziót mindig adjuk meg.

Hozzáférés és tokenek

Az access token egy átlátszatlan karakterlánc, amely azonosít egy felhasználót, egy alkalmazást vagy egy oldalt, és tartalmazza a lejárat idejét meg a kibocsátó alkalmazást. A tokenek OAuth 2.0 szerint működnek, és az alkalmazás- meg a felhasználó-azonosító magában a tokenben van kódolva, ezért a token értékes adat.

• Felhasználói token (user access token): bejelentkezési dialóguson keresztül jön létre, miután a felhasználó megadta az engedélyt.
• Oldal-token (page access token): először felhasználói token kell, majd azt a Graph API-n keresztül kell becserélni oldal-tokenre. A /{user-id}/accounts végpont visszaadja azokat az oldalakat, amelyeken a felhasználó feladatot tud végezni (CREATE_CONTENT, MANAGE, MODERATE), és mindegyikhez egy rövid életű oldal-tokent.
• Alkalmazás-token (app access token): szerver-szerver hívásban, az alkalmazás titkos kulcsával generáljuk. Kliensoldali kódba vagy binárisba beégetni nem szabad, mert azzal az app titka is kikerül.
• System user token: hirdetési objektumokon vagy oldalakon végzett, emberi beavatkozás nélküli műveletekhez.

A hosszú életű tokenekre külön szabály vonatkozik: a Standard hozzáféréssel rendelkező Marketing API alkalmazások idő alapján nem lejáró tokent kapnak, ez a System user tokenekre is igaz, más okból viszont továbbra is érvényteleníthetők. Biztonságos hívásoknál a nyers tokenlánc helyett az SDK tokenkezelő osztályát használjuk.

Jogosultságok és alkalmazás-ellenőrzés

Az oldalak kezeléséhez a dokumentáció a pages_manage_posts, pages_manage_engagement, pages_manage_metadata, pages_read_engagement, pages_read_user_engagement és pages_show_list jogosultságokat sorolja fel, videóhoz a publish_video jogosultságot, business system user használatakor pedig a business_management jogosultságot.

• Ha az alkalmazást olyan is használja, aki nem szerepkörrel rendelkezik az alkalmazáson vagy az appot igénylő üzleti portfólióban, előbb át kell esnie alkalmazás-ellenőrzésen (App Review).
• A Marketing API használatához szintén App Review kell, néhány kivétellel, például a Server-Side API és az Offline Conversions esetében. A két fő hirdetési jogosultság az ads_management és az ads_read.
• A hozzáférést a Platform Terms és a Developer Policies együtt szabályozza, beleértve a Meta Advertising Standards és a Community Standards betartását. A feltételek megszegése esetén a Meta az alkalmazást vagy a fiókot felfüggesztheti.

Verziók és életciklus

A Graph API negyedévente kap új verziót. Minden verzió legalább két évig működik, pontosabban addig, amíg az azt követő verzió kiadásától számított két év el nem telik. Ha egy verzió már nem használható, a rá irányuló hívások a következő legrégebbi, még működő verzióra esnek vissza, ami némán más viselkedést jelenthet. Ezért érdemes a verziót a kódban egy helyen tartani, és a változáslistát követni.

Sebességkorlátok és hibák

• A Graph API kéréseire platform szintű limitek vonatkoznak, a Marketing API és az Instagram Platform kéréseire viszont Business Use Case (BUC) limitek. A Pages API tokenfüggő: alkalmazás- vagy felhasználói tokennel platform limitek, system user vagy oldal-tokennel BUC limitek érvényesek. Ha mindkettő alkalmazható lenne, a BUC él.
• Alkalmazás szinten a dokumentált képlet szerint egy órán belül 200 szorozva az alkalmazás napi aktív felhasználóinak számával hívás engedett. A limit elérése után a további kérések hibát adnak, amíg a számláló a limit alá nem esik.
• A használatot fejlécek jelzik: X-App-Usage, X-Ad-Account-Usage és X-Business-Use-Case-Usage, benne a call_count, a total_cputime és a total_time százalékos értéke.
• A hibaválasz egy error objektum: message, type, code, error_subcode, error_user_msg, error_user_title és fbtrace_id. Az fbtrace_id belső azonosító, hibajegyhez kell, de rövid idő után lejár.
• Gyakori kódok: 190 lejárt vagy visszavont token, 10 megtagadott jogosultság, 4, 17 és 341 átmeneti throttle, 368 ideiglenes blokk szabálysértés miatt, 506 egymás után ismételt bejegyzés. A token lejáratát alkódok is jelzik (463, 467).

Tovább olvasás

• Graph API overview
• Versioning
• Rate Limits

A CyberElectrónál a Graph API az a felület, amelyhez a közzétételi folyamatainkat kötjük: az n8n munkafolyamatai és a Postiz oldal-tokenekkel dolgoznak, és ugyanezt a hozzáférést használja a Hermes Agent is, amikor hirdetési vagy oldaladatot kér le.