Univerza v Ljubljani
Fakulteta za raˇ cunalniˇ stvo in informatiko
Gregor Gabrovˇsek
Izdelava sistema za avtomatizirano nalaganje medijskih vsebin na
oglaˇ sevalske platforme
DIPLOMSKO DELO
UNIVERZITETNI ˇSTUDIJSKI PROGRAM PRVE STOPNJE
RA ˇCUNALNIˇSTVO IN INFORMATIKA
Mentor : prof. dr. Borut Robiˇ c
Ljubljana, 2022
tatov diplomske naloge je potrebno pisno privoljenje avtorja, fakultete ter mentorja.
Besedilo je oblikovano z urejevalnikom besedil LATEX.
Kandidat: Gregor Gabrovˇsek
Naslov: Izdelava sistema za avtomatizirano nalaganje medijskih vsebin na oglaˇsevalske platforme
Vrsta naloge: Diplomska naloga na univerzitetnem programu prve stopnje Raˇcunalniˇstvo in informatika
Mentor: prof. dr. Borut Robiˇc Opis:
Implementirajte sistem, ki bo skrbel za avtomatizirano nalaganje medijskih vsebin na glavne spletne oglaˇsevalske platforme, kot npr. Facebook in You- tube. Sistem naj omogoˇca tudi hitro in uˇcinkovito prilagoditev interakcije z morebitnimi prihodnjimi oglaˇsevalskimi platformami. Opiˇsite glavne zah- teve, morebitne omejitve in predlagane reˇsitve. Implementacijo opiˇsite, kakor tudi glavne probleme in njihove reˇsitve ter ugotovitve, do katerih ste priˇsli med razvojem sistema.
Title: The design of a system for automatized uploading of media content to advertising platforms
Description:
Implement a system capable of automatic uploading of media content to the main online advertising platforms such as Facebook and Youtube. The system should allow for quick and efficient adaptation of its interaction with potential future advertising platforms. Analyze the requirements, potential limitations, and the suggested solutions. Describe the implementation of the system, highlight the main problems and solutions, as well as the findings during the development of the system.
Zahvaljujem se mentorju prof. dr. Borutu Robiˇcu za njegovo pomoˇc, podjetju Bending Spoons S.p.A. iz Milana ter ˇse posebej Valentini Rho za podporo med izdelavo diplomskega dela, navsezadnje pa se zahvaljujem tudi starˇsema, bratu Petru ter Barbari za vztrajno spodbujanje, podporo in dobrovoljnost!
Kazalo
Povzetek Abstract
1 Uvod 1
1.1 Opis ozadja in problema ter motiv . . . 1 1.2 Podrobnejˇsi opis omejitev in zahtev . . . 2
2 Pregled podroˇcja 5
3 Uporabljena tehnologija 7
4 Naˇcrt sistema 9
4.1 Pregled komponent . . . 9 4.2 Kontejniziranje ter postavitev na GCP . . . 12
5 Implementacija 13
5.1 Povezava z ˇcelnim delom sistema . . . 13 5.2 Prejemanje in usmerjanje Pub/Sub sporoˇcil v glavni komponenti 15 5.3 Nalaganje medijskih datotek . . . 18 5.4 Podrobnosti integracije s platformami . . . 23 5.5 Odpornost na napake . . . 35
6 Zanesljivost in hitrost programa 45
7 Zakljuˇcek 47
Seznam uporabljenih kratic
kratica angleˇsko slovensko API application programming in-
terface
aplikacijski programski vme- snik
SDK software development kit orodje za razvijanje program- ske opreme
GCP Google Cloud Platform Google Cloud Platform (Goo- glova platforma za oblaˇcne sto- ritve)
Povzetek
Naslov: Izdelava sistema za avtomatizirano nalaganje medijskih vsebin na oglaˇsevalske platforme
Avtor: Gregor Gabrovˇsek
V velikih podjetjih, ki v velikih koliˇcinah oglaˇsujejo na spletnih platformah, je veliko ˇcasa porabljenega za roˇcno nalaganje promocijskih slik in videov na nadzorne ploˇsˇce platform. Obstajajo knjiˇznjice za poenostavitev postopka za posamezno platformo. Manjka pa sistem, ki bi avtomatiziral postopke za hkratno nalaganje na veˇc platform.
Glavni cilj te diplomske naloge je implenentacija robustnega in uˇcinkovi- tega sistema, ki bo zdruˇzeval programske knjiˇznice ter aplikacijske vmesnike posameznih platform v en sam sistem, ki bo trˇznikom omogoˇcal enostavno nalaganje oglaˇsevalskih vsebin.
Rezultat je sistem, ki podpira tri glavne oglaˇsevalske platforme, poleg tega pa je implementiran na naˇcin, ki olajˇsa podporo za morebitne prihodnje platforme. Poleg tega opazno olajˇsa proces nalaganja medijev oddelku, ki se ukvarja s trˇzenjem.
Kljuˇcne besede: avtomatizirano nalaganje, oglaˇsevalske platforme, pod- pora oglaˇsevanju.
Abstract
Title: Creating a system for automatized uploading of media content to advertising platforms
Author: Gregor Gabrovˇsek
Big companies, which put emphasis on advertising on various web platforms, often spend large amounts of time for manual uploading of promotional im- ages and videos to each marketing platform separately. There are libraries that simplify the procedure for each specific platform, but there is a lack of a system which would automatize the procedure for concurrent uploading to multiple platforms.
The main topic of this thesis is implementing a single robust and effective system that will combine libraries and programming interfaces of various platforms into a single system, capable of providing marketers with an easy procedure for uploading media content.
This system will support three main marketing platforms along with being implemented in a way that allows easy support for future platforms. This way, it will considerably reduce the effort to upload media content to various marketing platforms by marketing teams.
Keywords: automatized uploading, advertising platforms, advertising sup- port.
Poglavje 1 Uvod
1.1 Opis ozadja in problema ter motiv
Diplomska naloga se bo osredotoˇcala na specifiˇcen problem italijanskega pod- jetja Bending Spoons. Podjetje se ukvarja z izdelavo raznovrstnih mobilnih aplikacij. Poleg razvijalske ekipe se v podjetju nahaja tudi velika ekipa za trˇzenje, katere naloga je besedo o izdelanih aplikacijah ponesti ˇcim ˇsirˇse v svet.
Najpomembnejˇse delo ekipe marketinga je seveda oglaˇsevanje, veˇcina tega pa se dogaja na platformah, kot sta Facebook in TikTok, do neke mere pa tudi YouTube, Snapchat in ostale.
Po tem, ko oblikovalci izdelajo promocijske slike ter videe, je naloga trˇznika, da te medije objavi kot oglas na eni ali veˇc platformah. Ta oseba mora vsako sliko posebej naloˇziti na vsako platformo, nato pa jo uporabiti v oglasu. Glede na ogromno koliˇcino oglaˇsevanja, ki se dogaja v podjetju, je hitro jasno, da je tudi roˇcnega nalaganja medijskih vsebin ogromno. To porabi veliko ˇcasa, ki bi bil lahko bolje porabljen drugje.
Da bi proces nalaganja pospeˇsili, se je podjetje odloˇcilo za izdelavo sistema Media Center, ki bo poskrbel za avtomatiˇcno nalaganje vsebin na ˇzelene platforme. Cilj je, da bi trˇznik v uporabniˇskem vmesniku preprosto izbral medijske vsebine, ki jih ˇzeli uporabiti v oglasu, ter platforme, na katerih bo
1
medijske vsebine uporabljal. Uporabniˇski vmesnik bi nato zahtevo posredoval zalednemu delu, ki bi sam poskrbel za nalaganje na platforme.
Tak sistem bi sodelavcem v marketingu prihranil veliko ˇcasa, truda, ne nazadnje pa tudi ˇzivcev.
1.2 Podrobnejˇ si opis omejitev in zahtev
Zgoraj opisan sistem mora ustrezati doloˇcenim omejitvam in zahtevam, da bo lahko v produkciji karseda uˇcinkovit.
Med najpomembnejˇsimi zahtevami je gotovo zanesljivost. V podjetju trenutno ˇze obstaja delna reˇsitev, ˇzal pa podpira le platformo Facebook.
Poleg tega je ta reˇsitev precej nezanesljiva (sistem vzdrˇzevalcem javlja napake veˇckrat dnevno!) in zahteva veliko pozornosti, da se vzpostavi vsaj nekoliko zadovoljiva raven delovanja. Tudi to je eden od povodov za izdelavo novega sistema - nadgradnja starega bi bil namreˇc nesmiseln podvig zaradi teˇzavne nadgradnje kode.
Naslednja zelo pomembna zahteva je hitrost. Dnevno bo moral sistem na platforme naloˇziti med sto in tisoˇc medijskih vsebin v ˇstevilnih jezikih.
Komponenta za nalaganje mora svojo nalogo opravljati uˇcinkovito, poleg tega pa je pomembno tudi to, da se v primeru napake postopek nalaganja ˇcim prej zaˇzene znova.
Sistem mora biti zgrajen tudi na naˇcin, ki omogoˇca enostavno podporo prihodnjim platformam. ˇCe marketinˇska ekipa ugotovi, da se zadnje ˇcase uveljavlja neka do sedaj manj znana ali pa ˇcisto nova platforma, mora biti sistem implementiran na naˇcin, da integracija novega programskega vmesnika terja ˇcim manj ˇcasa in truda. To zagotovi tudi konkurenˇcno prednost, saj bo podjetje tako lahko med prvimi, ki bodo na platformi mnoˇziˇcno lansirali oglaˇsevalske kampanje.
Med glavnimi omejitvami je izbira orodij za izdelavo sistema. Celotna inˇzenirska ekipa za zaledne tehnologije v podjetju je vajena programskega jezika Python, zato je za zagotavljanje vzdrˇzevanja to najbolj smiselna izbira.
Diplomska naloga 3 Enako velja za Google Cloud Platform, kjer bomo v okviru diplomske naloge postavili zaledni del sistema, ter Google Cloud Pub/Sub, ki bo skrbel za komunikacijo med komponentami.
Poglavje 2
Pregled podroˇ cja
Na podroˇcju, ki ga bomo pokrili v okviru diplomske naloge, je javno do- stopnega zelo malo materiala. Tu seveda ne govorimo o interakcijah s po- sameznimi platformami, temveˇc o takem sistemu, ki bi uspeˇsno vkljuˇceval knjiˇznice in aplikacijske vmesnike.
Ceprav je dostopnega malo gradiva, ki bi govorilo o arhitekturi, ki biˇ na tak naˇcin zdruˇzevalo veˇc platform, pa je na voljo ogromno materiala za integracijo s posameznimi platformami.
Za platformo Facebook sta dostopna knjiˇznica za programski jezik Python ter obˇsirna dokumentacija [1]. Dokumentacija opisuje vse moˇznosti, ki jih ima razvijalec, ko ˇzeli na njihovo platformo naloˇziti nek oglaˇsevalski ma- terial. ˇZal pa je znano, da je Facebookova dokumentacija za vmesnike do marketinˇskih storitev na trenutke zastarela, zaradi ˇcesar lahko priˇcakujemo obˇcasne teˇzave pri implementaciji.
Prosto dostopne so tudi dokumentacije za platforme, kot sta TikTok [2]
in Google [3].
Precej dela bo seveda potrebnega tudi na podroˇcju arhitekture kompo- nent, njihove medsebojne komunikacije ter postavitve na oblaˇcni platformi Google Cloud Platform. Tu pridejo v pomoˇc tako pretekle izkuˇsnje kot tudi zelo kakovostna dokumentacija [4, 5] in znanje celotne ekipe.
5
Poglavje 3
Uporabljena tehnologija
Sistem bo implementiran v programskem jeziku Python. Ta ne omogoˇca le preprostega programiranja, temveˇc ga odlikuje tudi ˇsiroka paleta prosto do- stopnih knjiˇznic. To je za to diplomsko delo izjemnega pomena, saj nekatere platforme, s katerimi ˇzelimo sistem integrirati, ponujajo tudi ˇze obstojeˇce knjiˇznice. Posluˇzili se bomo tudi nekaterih drugih pogostih knjiˇznic, kot je tenacity (ta nam omogoˇca, lahko dele kode v primeru napak ponovimo). Da bo programiranje karseda uˇcinkovito, bomo uporabljali integrirano razvijal- sko okolje PyCharm Professional, ki je uveljavljen kot izvrstno orodje za razvoj v jeziku Python.
Omeniti velja, da bodo vse navedene funkcije in metode definirale tudi tipe argumentov ter rezultata. To je v kodi, napisani v programskem jeziku Python, nekoliko neobiˇcajno. Prva razliˇcica Pythona, ki namige tipov pod- pira, je Python 3.5. Za tak zapis smo se odloˇcili, saj nam prepreˇcuje, da bi priˇslo do napaˇcne uporabe funkcij, prav tako pa se poveˇca berljivost in enostavnost razhroˇsˇcevanja.
Nekatere podatke o medijih, uspeˇsnem nalaganju ter o uporabnikih naˇsega programa ˇzelimo tudi shraniti v podatkovno bazo. Kar se tiˇce strukture po- datkov, je naˇs konˇcni program dokaj preprost, zato bomo uporabili ˇsiroko uporabljeno relacijsko bazo PostgreSQL, s katero je tudi enostavno upra- vljati s programskim jezikom Python.
7
Ker ˇzelimo implementirani sistem postaviti tudi na oblaˇcno platformo GCP, ga bo potrebno tudikontejnerizirati. Najbolj standardno orodje, ki ga bomo zato seveda uporabili, je Docker. Take kontejnerje bomo lahko nato uporabili na Googlovi oblaˇcni platformi GCP, natanˇcneje na njihovi storitvi Compute Engine, ki ima tudi dobro podporo za hitro in preprosto postavitev kontejnerjev.
Ker bodo morale komponente komunicirati med sabo, morajo uporabljati kakˇsno izmed storitev za prenaˇsanje sporoˇcil. Ker bomo uporabljali Compute Engine na Googlovi platformi, se kot smiselna izbira izkaˇze storitev Cloud Pub/Sub, ki je prav tako Googlova. S tem se zagotovi visok nivo zdruˇzljivosti uporabljenih sistemov ter hitra komunikacija.
Naposled bo potrebno ovrednotiti tudi hitrost in zanesljivost sistema. To bomo storili tako, da bomo sledili ˇstevilu napak, do katerih je priˇslo, merili pa bomo tudi hitrost delovanja.
Poglavje 4
Naˇ crt sistema
4.1 Pregled komponent
Celoten sistem je sestavljen iz dveh komponent.
Prva komponenta, ki je tudi osrednja tema te diplomske naloge, je glavni zaledni sistem, ki skrbi za usmerjanje zahtevkov na razrede, prilagojene na vsako oglaˇsevalsko platformo, od koder poteka tudi nalaganje medijskih vse- bin. Prav tako skrbi za nekatere ostale naloge, npr. za povezovanje s podat- kovno bazo.
Druga komponenta bo skrbela za prejemanje zahtevkov iz grafiˇcnega vme- snika in njihovo posredovanje v zgoraj opisano komponento. Ti zahtevki bodo vsebovali informacije o medijih, ki so jih uporabniki izbrali za nalaganje.
4.1.1 Povezovanje s ˇ celnim delom
Skozi drugo komponento bodo iz ˇcelnega dela v zaledni priˇsli zahtevki za nalaganje medijev. Glavna naloga komponente je izpostavljanje endpointa1 za prejemanje zahtevkov za nalaganje. Temu sledi pregled zahtevka (ali ima uporabnik pravico za nalaganje medijev), nato pa posredovanje zahtevka glavni komponenti za nalaganje.
1sl.konˇcna toˇcka
9
Slika 4.1: Shema sistema
4.1.2 Glavna komponenta za nalaganje
Naloga prve komponente je prejemanje zahtevkov iz komponente, opisane v poglavju 4.1.1, nato pa se glede na vsebino odloˇciti, na katero oglaˇsevalsko platformo se zahtevek nanaˇsa.
Za namene nalaganja bo ustvarjen razred, ki bo vseboval nekatere sku- pne metode (npr. za shranjevanje rezultata nalaganja), definiral pa bo tudi nekatere abstraktne metode (npr. metoda za nalaganje oz. interakcijo s plat- formo), ki jih bo moral implementirati podrazred vsake posamezne oglaˇse- valske platforme.
Metode, ki bodo specifiˇcne za platforme, bodo v glavnem striktno osre- dotoˇcene na bodisi samo uporabo SDK-jev oziroma API-jev platforme, ali pa na izkazovanje doloˇcenih lastnosti razreda, specifiˇcnega za platformo - te lastnosti potem lahko uporabimo v metodah v nadrazredu pri kakˇsnih
Diplomska naloga 11 odloˇcitvah (npr. ali SDK podpira nalaganje iz lokalne datoteke ali pa kar iz spletnega naslova, na podlagi tega pa izvedemo en ali drug kos kode).
Izbira podprtih platform za oglaˇsevanje
Oglaˇsevalske platforme, ki jih bo Media Center podpiral, smo izbrali glede na trenutne potrebe marketinˇske ekipe ter na predvidevanje, kaj bomo vsaj v prihodnjem letu najbolj potrebovali.
Izbrali smo tri platforme: Facebook, TikTok in YouTube.
Facebook smo izbrali, ker je podjetje v preteklosti pri njih najveˇc ogla- ˇsevalo. ˇCeprav koliˇcina novih oglasov pri njih trenutno upada, so ˇse vedno pomembna platforma, ki jo velja podpreti z naˇsim programom.
TikTok smo izbrali, ker priljubljenost platforme skokovito naraˇsˇca, ˇse sploh v zadnjem letu. Ekipa marketinga je ugotovila, da je oglaˇsevanje tam zelo dobra naloˇzba, saj je deleˇz ljudi, ki na oglas kliknejo, zelo visok. Poleg tega pa smo ocenili, da je integracija TikToka v Media Center dobra naloˇzba za potrebe v prihodnjih letih.
YouTube za nas sicer ni tako pomembna platforma za oglaˇsevanje, kljub temu pa obˇcasno pri njih ustvarimo nekaj oglaˇsevalskih kampanj. Integracija njihovega SDK-ja ni bila videti zapletena, zato smo se odloˇcili, da ga vendarle vkljuˇcimo, saj je nalaganje videov tja ˇse posebej zamudno in bo v podjetju integracija prihranila kar nekaj ˇcasa.
V mislih smo imeli tudi nekaj drugih platform, najbolj omembe vredna med njimi je Snapchat, a smo se odloˇcili, da jih zaradi skromne uˇcinkovitosti oglasov za zdaj ne bomo vkljuˇcili v naˇso reˇsitev.
Podatkovna baza
Pomemben del sistema bo tudi podatkovna baza, ki bo hranila vse podatke o medijih. Kljuˇcne bodo tri tabele:
• media: tabela bo vsebovala kljuˇcne podatke o medijskih datotekah.
Primarni kljuˇc bo poimenovangstorage path, ki bo obenem nakazal pot
do datoteke na storitvi za hranjenje datotek GStorage, od koder bomo medij tudi prenesli, preden ga bomo naloˇzili na platformo. Ostali atri- buti bodo product name (na kateri izdelek podjetja se medij nanaˇsa), kind (tip medija, ki lahko zavzema vrednostvideoaliimage), ter nekaj atributov, ki za nas niso tako pomembni, kot je npr.creation date (ˇcas, ko je bil medij vstavljen v bazo).
• media upload: tabela bo vsebovala zapise o uspeˇsnih nalaganjih me- dijev na platforme. Tuji kljuˇc bo seveda gstorage path, saj se vsako nalaganje nanaˇsa na neki medij, ostali atributi pa bodo platform (ime platforme, kamor smo medij naloˇzili), ad account id (identifikator og- laˇsevalskega raˇcuna, kamor smo medij naloˇzili) ter uploaded media id (enoliˇcni identifikator medija na platformi, ki ga dobimo od njihovega streˇznika po zahtevi za nalaganje).
• user: tabela uporabnikov, kjer bo imel vsak uporabnik (user) imel tudi dodeljene vloge (roles), na podlagi ˇcesar bomo ugotovili, ali ima pravice za nalaganje datotek.
4.2 Kontejniziranje ter postavitev na GCP
Nastali program bomo nato s pomoˇcjo storitve Docker kontejnerizirali. To pomeni, da ga bomo zapakirali na naˇcin, da bo lahko pravilno tekel na vsakem sistemu, saj so vse knjiˇznice in odvisnosti, ki jih naˇs program potrebuje, zapakirane skupaj z njim. Temu zapakiranemu programu reˇcemo slika.
To sliko bomo nato naloˇzili na platformo Google Container Registry (Goo- glova zbirka Docker slik), saj lahko le tja naloˇzene slike potem uporabimo v virtualnih strojih na Google Compute Engine.
Podatkovno bazo postavimo na Googlovi storitvi Cloud SQL, ki podpira tudi naˇso izbrano vrsto baze PostreSQL.
Ker so vsi deli naˇsega sistema na platformi GCP, jih je tudi zelo prepro- sto povezati med sabo, saj so vsi deli drug drugemu lahko dostopni preko internega IP-naslova.
Poglavje 5
Implementacija
5.1 Povezava z ˇ celnim delom sistema
Zaledni del prejme zahtevke za nalaganje iz ˇcelnega dela sistema. Zahtevek vsebuje naslednje informacije:
• Poti do medijskih datotek na storitvi GStorage (ki sluˇzijo kot enoliˇcni identifikatorji),
• naziv ciljne platforme za nalaganje in
• identifikatorje oglaˇsevalskih raˇcunov na izbrani platformi, na katere se morajo izbrani mediji naloˇziti.
V zalednem delu sistema te zahtevke prejme endpoint. Po prejetem zah- tevku v bazi preverimo, ali ima poˇsiljatelj zahtevka ustrezne pravice za na- laganje medijskih datotek. ˇCe jih ima, preko sistema Google Pub/Sub kom- ponenti za nalaganje medijskih datotek posredujemo zahtevek.
Izsek kode
1 c l a s s MediaUploadMessage ( BaseModel ) : 2 g d r i v e p a t h s : tuple[str, . . . ]
3 p l a t f o r m : L i t e r a l [ ” f a c e b o o k ” , ” t i k t o k ” , ” youtube ” ]
13
4 a d a c c o u n t s : tuple[str, . . . ] 5
6 @ r o u t e r . p o s t ( ” ” )
7 a s y n c def u p l o a d m e d i a ( 8 r e q u e s t : Request ,
9 u p l o a d r e q u e s t : MediaUploadMessage ,
10 p u b l i s h e r : PubSubPublisher = Depends ( g e t p u b s u b p u b l i s h e r ) , 11 ) −> JSONResponse :
12 ”””
13 Upload a media u s i n g t h e g i v e n GDrive p a t h , p l a t f o r m
14 and AdAccounts .
15 ”””
16
17 i f not r e q u e s t . u s e r . h a s p l a t f o r m m a n a g e r p e r m i s s i o n :
18 return JSONResponse (
19 s t a t u s c o d e=s t a t u s . HTTP 403 FORBIDDEN ,
20 c o n t e n t ={
21 ” d e t a i l ” : ” User has i n s u f f i c i e n t p e r m i s s i o n s . ”
22 },
23 )
24
25 p u b l i s h e r . p u b l i s h (
26 d a t a=u p l o a d r e q u e s t . j s o n ( ) , 27 type=MediaUploadWorkflow .type( ) , 28 r e q u e s t e d b y=r e q u e s t . s t a t e . u s e r . mail ,
29 )
30
31 return JSONResponse (
32 s t a t u s c o d e=s t a t u s . HTTP 200 OK ,
33 c o n t e n t ={
34 ” d e t a i l ” : ”The r e q u e s t w i l l be e x e c u t e d s o o n . ”
35 },
36 )
Obrazloˇzitev kode
V kodi je prikazana koda endpointa, ki preko HTTP metode POST v te- lesu zahtevka prejme podatek formata JSON. Knjiˇznici FastAPI, ki jo upo-
Diplomska naloga 15 rabljamo za poenostavitev dela z endpointi, lahko z argumenti v funkciji upload media specificiramo, kako naj dele zahtevka uporabi, da pokliˇce to funkcijo.
V naˇsem primeru telo formata JSON samodejno uporabi za argument upload request, saj iz ˇcelnega dela naˇsega programa pridejo podatki, ki so enake oblike kot podatki v razreduM ediaU ploadM essage(definiran v vrstici 1).
Kot argument requestnamFastAPI poˇslje praktiˇcno vse podatke o zah- tevku (ki med drugim vsebuje tudi podatke o sodelavcu, ki je preko sple- tne strani poslal zahtevek). Iz teh podatkov lahko izvemo, ali ima avtor zahtevka pravice za izvedbo nalaganja, kar tudi storimo v telesu funkcije upload media.
Tretji argument (publisher) pa FastAPI vstavi po principu injiciranja odvisnosti (ang. dependency injection). Ta argument predstavlja izdajatelja sporoˇcil na sistem Pub/Sub. Preko tega izdajatelja pa v vrstici 25 glavni komponenti poˇsljemo zahtevo za nalaganje.
5.2 Prejemanje in usmerjanje Pub/Sub sporoˇ cil v glavni komponenti
Glavni razred, ki skrbi za usmerjanje prejetih sporoˇcil in nato tudi njihovo izvajanje, smo poimenovali W orker. Sledi po delih razloˇzena koda razreda:
1 from d a t a c l a s s e s import d a t a c l a s s 2 from g o o g l e . c l o u d import pubsub v1 3 import l o g g i n g
4
5 LOGGER = l o g g i n g . g e t L o g g e r ( n a m e ) 6
7 @ d a t a c l a s s ( f r o z e n=True ) 8 c l a s s P u b S u b C o n f i g u r a t i o n : 9 s u b s c r i p t i o n p a t h : s t r 10 m a x l e a s e s e c o n d s : i n t
11
12 c l a s s Worker :
13 ”””
14 The w o r k e r w i l l l i s t e n o v e r t h e q u e u e o f p e n d i n g t a s k s and p r o c e s s e a c h r e q u e s t coming on t h a t q u e u e by e x e c u t i n g t h e a p p r o p r i a t e h a n d l e r .
15 ”””
16
17 def i n i t (
18 s e l f ,
19 h a n d l e r s : C o l l e c t i o n [ G e n e r i c H a n d l e r ] , 20 p u b s u b c o n f i g : P u b S u b C o n f i g u r a t i o n , 21 ) −> None :
22 s e l f . h a n d l e r s = {h a n d l e r .type( ) : h a n d l e r f o r h a n d l e r in h a n d l e r s}
23
24 s e l f . s u b s c r i b e r = pubsub v1 . S u b s c r i b e r C l i e n t ( ) 25 s e l f . s u b s c r i b e r . s u b s c r i b e (
26 s u b s c r i p t i o n=p u b s u b c o n f i g . s u b s c r i p t i o n p a t h , 27 c a l l b a c k= s e l f . h a n d l e m e s s a g e ,
28 )
Najprej definiramo inicializacijsko metodo razreda Worker. Prejmemo vse t. i. handlerje, torej razrede, ki znajo sprocesirati sporoˇcila iz sistema Pub/Sub. V naˇsem primeru so to seveda razredi posamezne platforme za na- laganje datotek. V spremenljivkiself. handlers si shranimo slovar, ki nam bo omogoˇcal, da do posameznega handlerja dostopamo preko njegovega imena (slovar ustvarimo v vrstici 22).
Inicializiramo tudi instanco razredapubsub.SubscriberClient, ki nam omo- goˇca, da iz sistema Pub/Sub prejemamo sporoˇcila. Shranimo ga v spremen- ljivko self. subscriber. Na tej instanci nato pokliˇcemo ˇse metodo subscribe (vrstica 25), v kateri navedemo, iz katere naroˇcniˇske poti (ang. subscription path) naj bere sporoˇcila in katero funkcijo naj ob prejemu pokliˇce ter ji preda sporoˇcilo.
30 def h a n d l e m e s s a g e ( s e l f , message : Message ) −> None :
31 ”””
Diplomska naloga 17
32 Handle a message from t h e s u b s c r i p t i o n q u e u e . 33
34 : param message : t h e message t o h a n d l e
35 ”””
36 try:
37 h a n d l e r = s e l f . h a n d l e r s [ message . m e s s a g e t y p e ] 38 h a n d l e r . h a n d l e r a w m e s s a g e ( message=message )
39 except ( MalformedMessageError , V a l i d a t i o n E r r o r ) a s e x c :
40 LOGGER . e r r o r (
41 ” t h e r e c e i v e d message i s malformed : %s , e r r o r : %
s ” , message , exc , e x c i n f o=True
42 )
43 return
44 except KeyError :
45 LOGGER . e r r o r ( ” t h e h a n d l e r d o e s n o t e x i s t : %s ” , message . m e s s a g e t y p e , e x c i n f o=True )
46 return
Kot je bilo omenjeno zgoraj, to metodo pokliˇceSubscriberClient, ko prejme sporoˇcilo. V metodi najprej glede na tip sporoˇcila doloˇcimo, kateri handler lahko sporoˇcilo sprocesira. Tahandler glede na ime pridobimo iz slovarja, ki smo ga shranili ob inicializaciji razredaWorker, na njem pa potem pokliˇcemo metodo handle raw message, ki bo izvedla nalaganje (podrobneje opisano v poglavju 5.3).
48 def run ( s e l f ) −> None : 49 w i t h s e l f . s u b s c r i b e r :
50 s e l f . s u b s c r i b e r . r u n f o r e v e r ( )
Nazadnje definiramo ˇse metodo run, ki instanci SubscriberClient naroˇci, naj teˇce v nedogled. Tako je naˇs program vedno pripravljen na sprejema- nje sporoˇcil. To metodo pokliˇcemo na instanci razreda Worker po njegovi inicializaciji.
5.3 Nalaganje medijskih datotek
Kot je bilo omenjeno v poglavju 5.1, se po prejemu zahtevka iz ˇcelnega dela v komponentiAPI ta zahtevek potem posreduje v glavno komponento. Tam se posreduje v razred PlatformUploadTask, ki definira celo vrsto metod, ne- katere med njimi tudi abstraktne, katerih implementacija bo specifiˇcna za vsako platformo.
Poglejmo si implementacijo razreda po kosih:
1 import l o g g i n g 2 import t e m p f i l e
3 from abc import ABC, a b s t r a c t m e t h o d 4 from enum import Enum
5
6 from m e d i a c e n t e r . common . g s t o r a g e import GStorageManager 7 from m e d i a c e n t e r . common . models . a s s e t s import (
8 AssetsManager ,
9 CreateMediaUploadParameters ,
10 Media ,
11 M e d i a U p l o a d F i l t e r , 12 P l a t f o r m I d e n t i f i e r , 13 )
14 from m e d i a c e n t e r . w o r ke r . h a n d l e r import H a n d l e r C r i t i c a l E r r o r 15
16 LOGGER = l o g g i n g . g e t L o g g e r ( n a m e ) 17
18 c l a s s P l a t f o r m U p l o a d M e s s a g e : 19 g d r i v e p a t h : s t r
20 a d a c c o u n t : s t r 21 f o r c e : bool = F a l s e 22
23 c l a s s PlatformUploadTask (ABC) :
24 ”””
25 The g e n e r i c h a n d l e r f o r t h e media u p l o a d t a s k .
26 ”””
27
28 def i n i t (
Diplomska naloga 19
29 s e l f , m e d i a s t o r a g e m a n a g e r : GStorageManager , a s s e t s m a n a g e r : AssetsManager
30 ) :
31 s e l f . m e d i a s t o r a g e m a n a g e r = m e d i a s t o r a g e m a n a g e r 32 s e l f . a s s e t s m a n a g e r = a s s e t s m a n a g e r
33
34 @classmethod
35 @abstractmethod
36 def p l a t f o r m ( c l s ) −> P l a t f o r m I d e n t i f i e r :
37 ”””
38 Return t h e i d e n t i f i e r o f t h e p l a t f o r m t h i s c l i e n t i s r e f e r r i n g t o .
39 ”””
40 r a i s e NotImplementedError ( )
Tu definiramo osnovne stvari, kot sta inicializacijska metoda razreda, kjer v spremenljivke shranimo media storage manager (ta nam omogoˇca, da iz storitve GStorage prenesemo medijske datoteke), terassets manager (z njim lahko dostopamo do podatkovne baze). Razred vsebuje tudi abstraktno me- todo platform, ki jo vsak podrazred platforme implementira tako, da vrne ime platforme. To je pomembno, saj glede na rezultat te metode doloˇcimo, kateremu handlerju posredujemo sporoˇcilo iz razreda Worker.
V naslednjem odseku je implementirana metoda, ki sprejme sporoˇcilo, nato pa z njegovo vsebino pokliˇce metodo upload:
1 def h a n d l e m e s s a g e ( s e l f , message : P l a t f o r m U p l o a d M e s s a g e ) −>
None :
2 s e l f . u p l o a d (
3 g d r i v e p a t h=message . g d r i v e p a t h , 4 a d a c c o u n t i d=message . a d a c c o u n t ,
5 f o r c e=message . f o r c e ,
6 )
Sledi zgoraj poklicana metoda upload, ki je med bolj pomembnimi me- todami v programu. Metoda najprej uporabi upravljavca s podatkovno bazo self. assets manager, da pridobi podatke o mediju iz baze, potem pa poi- zve o primernem naˇcinu nalaganja iz metode self. upload method (obstajata
dva naˇcina: nalaganje iz lokalnega diska ali pa nalaganje iz spletnega na- slova). Glede na pridobljeni naˇcin nalaganja medija pa potem pokliˇce bodisi metodo za nalaganje iz lokalne datoteke, bodisi metodo za nalaganje iz sple- tnega naslova. V primeru uspeˇsnega nalaganja pa nato pokliˇce ˇse metodo za shranjevanje pridobljenega identifikatorja datoteke na platformi v bazo.
1 def u p l o a d ( s e l f , g d r i v e p a t h : str, a d a c c o u n t i d : str, f o r c e : bool) −> None :
2 ”””
3 Upload d a t a t o t h e a p p r o p r i a t e p l a t f o r m from t h e g i v e n media p a t h .
4
5 : param g d r i v e p a t h : g d r i v e p a t h o f t h e media t o u p l o a d 6 : param a d a c c o u n t i d : t h e i d o f t h e ad a c c o u n t t o u p l o a d
media t o
7 : param f o r c e : True i f we want t o f o r c e t h e u p l o a d , F a l s e o t h e r w i s e
8 ”””
9 media = s e l f . a s s e t s m a n a g e r . g e t m e d i a ( g d r i v e p a t h=
g d r i v e p a t h ) 10
11 i f not f o r c e and not s e l f . s h o u l d u p l o a d (
12 g d r i v e p a t h=media . g d r i v e p a t h , a d a c c o u n t i d=
a d a c c o u n t i d
13 ) :
14 LOGGER . i n f o ( ” media a l r e a d y u p l o a d e d : %s ” , g d r i v e p a t h )
15 return
16
17 method = s e l f . u p l o a d m e t h o d ( )
18 i f method == UploadMethod . LOCAL FILE :
19 u p l o a d e d m e d i a i d = s e l f .
d o w n l o a d l o c a l f i l e a n d u p l o a d (
20 media=media , a d a c c o u n t i d=a d a c c o u n t i d
21 )
22 e l i f method == UploadMethod . PRESIGNED URL : 23 u p l o a d e d m e d i a i d = s e l f .
c r e a t e p r e s i g n e d u r l a n d u p l o a d (
Diplomska naloga 21
24 media=media , a d a c c o u n t i d=a d a c c o u n t i d
25 )
26 e l s e:
27 r a i s e H a n d l e r C r i t i c a l E r r o r (
28 f ” u n s u p p o r t e d u p l o a d method : {method} f o r p l a t f o r m : {s e l f . p l a t f o r m ( )}”
29 )
30
31 s e l f . s t o r e u p l o a d s u c c e s s ( 32 g d r i v e p a t h=g d r i v e p a t h , 33 a d a c c o u n t i d=a d a c c o u n t i d ,
34 u p l o a d e d m e d i a i d=u p l o a d e d m e d i a i d ,
35 )
V naslednjem izseku so opisane tri metode. Prva je abstraktna metoda upload method, ki jo implementira vsak razred. Pove, ali je SDK oz. API, ki ga platforma uporablja, prilagojen na nalaganje lokalne datoteke ali pa sprejme tudi datoteko prek spletne povezave.
Druga metoda je download local file and upload, ki ustvari zaˇcasno mapo na disku in tja iz storitve GStorage prenese datoteko. Nato pokliˇce abstrak- tno metodo upload media on platform from file.
Tretja metoda je generate presigned url and upload, ki sprva ustvari t. i.
predpodpisan spletni naslov [6] (ang.presigned URL). Tak URL lahko zgene- rira le nekdo, ki ima dostop do datoteke, prek tega naslova pa lahko vsakdo lahko dostopi do medija, tudi streˇznik oglaˇsevalske platforme. S tem naslo- vom nato pokliˇcemo abstraktno metodo upload media on platform from url.
1 @abstractmethod
2 def u p l o a d m e t h o d ( s e l f ) −> UploadMethod : 3 r a i s e NotImplementedError ( )
4
5 def d o w n l o a d l o c a l f i l e a n d u p l o a d ( s e l f , media : Media , a d a c c o u n t i d : s t r) −> s t r:
6 w i t h t e m p f i l e . T e m p o r a r y D i r e c t o r y ( ) a s t e m p d i r : 7 l o c a l p a t h = f ”{t e m p d i r}/{media . f i l e n a m e}” 8 s e l f . m e d i a s t o r a g e m a n a g e r . d o w n l o a d f i l e ( 9 r e m o t e p a t h=media . s t o r a g e p a t h , l o c a l p a t h=
l o c a l p a t h
10 )
11 return s e l f . u p l o a d m e d i a o n p l a t f o r m f r o m f i l e ( 12 l o c a l f i l e p a t h =l o c a l p a t h , media=media ,
a d a c c o u n t i d=a d a c c o u n t i d
13 )
14
15 def c r e a t e p r e s i g n e d u r l a n d u p l o a d ( s e l f , media : Media , a d a c c o u n t i d : s t r) −> s t r:
16 p r e s i g n e d u r l = s e l f . m e d i a s t o r a g e m a n a g e r . g e t s i g n e d u r l ( path=media . s t o r a g e p a t h ) 17 return s e l f . u p l o a d m e d i a o n p l a t f o r m f r o m u r l ( 18 u r l=p r e s i g n e d u r l , media=media , a d a c c o u n t i d=
a d a c c o u n t i d
19 )
V metodi upload smo omenili ˇse metodo store upload success. Metoda je zelo preprosta - prejme naˇs identifikator datoteke (primarni kljuˇc v bazi), ID oglaˇsevalskega raˇcuna na platformi ter identifikator naloˇzenega medija na platformi. Te podatke shrani kot vrstico v tabeli media upload s pomoˇcjo upravljavca z bazo self. assets manager.
1 def s t o r e u p l o a d s u c c e s s (
2 s e l f , g d r i v e p a t h : str, a d a c c o u n t i d : str, u p l o a d e d m e d i a i d : s t r
3 ) −> None :
4 ”””
5 S t o r e s u c c e s s f u l u p l o a d i n t h e d a t a b a s e . 6
7 : param g d r i v e p a t h : t h e p a t h o f t h e f i l e i n g d r i v e
8 : param a d a c c o u n t i d : t h e i d o f t h e ad a c c o u n t t h e media was u p l o a d e d t o
9 : param u p l o a d e d m e d i a i d : t h e media i d r e t u r n e d t o us by t h e a d v e r t i s i n g p l a t f o r m
10 ”””
11 s e l f . a s s e t s m a n a g e r . c r e a t e m e d i a u p l o a d ( 12 m e d i a u p l o a d=C r e a t e M e d i a U p l o a d P a r a m e t e r s (
13 g d r i v e p a t h=g d r i v e p a t h ,
Diplomska naloga 23
14 p l a t f o r m= s e l f . p l a t f o r m ( ) ,
15 a d a c c o u n t i d=a d a c c o u n t i d ,
16 u p l o a d e d m e d i a i d=u p l o a d e d m e d i a i d ,
17 )
18 )
Manjka ˇse izsek kode z definicijo zgoraj omenjenih abstraktnih metod upload media on platform from file ter upload media on platform from url, saj so implementacije v vsakem od podrazredov platform zelo preproste - glede na tip medija (slika ali video) le pokliˇcemo metode upload image ali upload video, ki bodo za vsako platformo podrobneje opisane v poglavju 5.4.
5.4 Podrobnosti integracije s platformami
Za vsako od treh platform, ki so bile izbrane za implementacijo, moramo torej implementirati metodi za nalaganje videov in nalaganje slik (tu izvzamemo YouTube). Veˇcinoma sta metodi z izjemo nekaj podrobnosti v veˇcji meri enaki, zato bomo za vsako platformo podrobneje razloˇzili le eno.
Opisani bodo koraki, ki so potrebni za nalaganje medija na platformo skupaj z relevantnim delom kode, nato pa bodo navedene tudi zanimivosti interakcije s platformo, ki smo jih odkrili med implementacijo.
Pri prvih dveh platformah bo omenjeno tudi, ˇce in kako platforma spre- jema datoteke formata GIF (ki se v raˇcunalniˇskem svetu najveˇckrat tretira kot slika, a lahko vsebuje veˇc sliˇcic, da daje vtis premikanja). To je po- membno, saj se take datoteke pogosto uporabljajo, da slike oglasa napravijo bolj”ˇzive“, podpora oglaˇsevalskih platform takim datotekam pa ˇzal ni samo- umevna.
5.4.1 Facebook
Podrobnosti integracije
Facebook za namene komunikacije z njihovimi streˇzniki nudi lastni SDK za programski jezik Python [7]. Cilj naˇsega programa je seveda, da najprej iz-
bere pravi oglaˇsevalski raˇcun na Facebooku, potem pa v pripadajoˇco medijsko knjiˇznico naloˇzi izbrane medijske vsebine.
Zgornji proces je v praksi sestavljen iz ˇstirih korakov (spodaj omenjena objekta F acebookAdsApi, AdAccount ter pripadajoˇce metode so del SDK- ja):
• Inicializacija objekta FacebookAdsApi: ta objekt pri inicializaciji prejme API kljuˇc in zaˇcasni ˇzeton za dostop do Facebookovega API-ja.
ObjektF acebookAdsApinam lahko nato na zahtevo izvaja avtorizirane klice na Facebookove streˇznike.
• Ustvarjanje instance razreda AdAccount: Z uporabo prej ustvar- jenega objekta FacebookAdsApi ter identifikacijske ˇstevilke oglaˇseval- skega raˇcuna lahko ustvarimo objekt AdAccount. Ta ima definirane metode, ki jih potrebujemo za nalaganje slik ter video posnetkov na ˇzeleni oglaˇsevalski raˇcun.
• Dodajanje datoteke in izvrˇsevanje nalaganja: Na ustvarjenem objektu AdAccount lahko kliˇcemo metodo create ad image ali metodo create ad video, odvisno od tipa medija, ki ga nalagamo. Metoda vrne objekt, na katerem lahko kliˇcemo metodo add file, parameter klica pa mora biti pot do medija na sistemskem disku. Nazadnje lahko na istem objektu kliˇcemo tudi metodo execute, ki nalaganje tudi izvrˇsi.
• Pridobivanje identifikatorja naloˇzenega medija: Metoda execute iz prejˇsnjega koraka kot rezultat vrne enega od objektov AdImage ali AdVideo, odvisno od tipa medija. Ta objekta vsebujeta celo vrsto in- formacij o naloˇzeni datoteki (na primer velikost in ime), nas pa najbolj zanima unikatni identifikator medija v Facebookovi knjiˇznici medijev.
Ta identifikator se v vrnjenem objektu imenujehash (ˇceprav je ta naziv nekoliko zavajajoˇc, kar je podrobneje pojasnjeno v poglavju Omejitve ter pasti). Tega pridobimo iz omenjenega objekta in ga vrnemo kot rezultat metode za nalaganje.
Diplomska naloga 25 Primer kode za nalaganje slik
1 def u p l o a d i m a g e (
2 s e l f ,
3 a d a c c o u n t i d : str, 4 i m a g e f i l e p a t h : str, 5 f i l e n a m e : s t r
6 ) −> s t r:
7 ”””
8 Upload image i n t h e Facebook AdAccount media l i b r a r y . 9 : param a d a c c o u n t i d : ID o f t h e ad a c c o u n t , t o w h i c h t h e
image s h o u l d b e u p l o a d e d
10 : param i m a g e f i l e p a t h : l o c a l f i l e p a t h o f t h e image 11 : param f i l e n a m e : name o f t h e image
12 : r e t u r n : t h e new AdImage h a s h
13 ”””
14 a d a c c o u n t = AdAccount ( f b i d=a d a c c o u n t i d , a p i= s e l f . a p i ) 15
16 u p l o a d r e q u e s t = a d a c c o u n t . c r e a t e a d i m a g e (
17 p e n d i n g=True , params={AdImage . F i e l d . name : f i l e n a m e}
18 )
19
20 try:
21 u p l o a d r e q u e s t . a d d f i l e ( f i l e p a t h=i m a g e f i l e p a t h ) 22 except FacebookBadParameterError a s e r r :
23 r a i s e F a c e b o o k M a n a g e r C r i t i c a l E r r o r (
24 f ” f i l e : {i m a g e f i l e p a t h} was n o t found ”
25 ) from e r r
26
27 a d i m a g e : AdImage = s e l f . p e r f o r m s t r u c t u r e c r e a t i o n ( 28 c r e a t i o n f u n c t i o n=u p l o a d r e q u e s t . e x e c u t e ,
29 method=ApiMethods . CREATE AD IMAGE,
30 )
31 i m a g e h a s h : s t r = a d i m a g e [ AdImage . F i e l d .hash] 32 return i m a g e h a s h
Omejitve ter pasti
• Datoteke GIF: med najveˇcjimi posebnostmi je Facebookov odnos do datotek GIF. Naloˇzimo jih lahko tako z metodo za nalaganje slik kot tudi z metodo za nalaganje videov, Facebook pa v obeh primerih datoteko sprejme. ˇZal Facebookova dokumentacija ne omeni, kaj se zgodi, ˇce skuˇsamo datoteko GIF naloˇziti v sliko. V tem primeru njihov streˇznik po prejemu medija iz sprva premikajoˇcega se GIF-a shrani le prvo sliˇcico (GIF torej postane statiˇcen).
• Velikost datotek: Najveˇcja velikost slike, ki jo lahko naloˇzimo na streˇznik, je 50 MB. Za video posneteke dokumentacija API-ja ne na- vaja nikakrˇsnih omejitev; v praksi pa smo s poskuˇsanjem ugotovili, da streˇznik zavrne datoteke, veˇcje od 26,7 GB. Za slike pa velja tudi, da se mora nalaganje izvrˇsiti v maksimalno eni minuti, ne glede na velikost.
• Moˇzno nalaganje istega medija veˇckrat: ˇSe najbolj nenavadna posebnost Facebookovega API-ja za nalaganje slik je to, da lahko isto medijsko datoteko sprejme najveˇc dvakrat. To pomeni, da ko sproˇzimo nalaganje prviˇc in drugiˇc, nam streˇznik vrne dve razliˇcni zgoˇsˇceni vre- dnosti, ob naslednjih poskusih nalaganja pa nam nemudoma vrne eno od prejˇsnjih zgoˇsˇcenih vrednosti.
5.4.2 TikTok
Podrobnosti integracije
V grobem je platforma TikTok kar se tiˇce oglaˇsevanja podobna Facebooku - ravno tako ima podjetje lahko veˇc oglaˇsevalskih raˇcunov, datoteke oglasnih medijev pa je treba naloˇziti v medijsko knjiˇznico.
Za TikTok je postopek nalaganja videov in slik preko njihovega API-ja dovolj podoben, da ju lahko pokrijemo z eno skupno metodo api helper, ki jo nato le pokliˇcemo z nekoliko razliˇcnimi argumenti.
Diplomska naloga 27 Metoda api helper (koda se nahaja v spodnjem podpoglavju 5.4.2) sprej- me URL, kamor mora zahtevek poslati, ter parametre nalaganja (ID ogla- ˇsevalskega raˇcuna ter spletno povezavo, na kateri je dostopen medij). Ome- njena metoda deluje takole:
• Najprej v vrstici 14 poˇsljemo zahtevek na podani URL s podanimi parametri o mediju. Instanca razreda, ki jo dobimo kot odgovor na zahtevek, nam omogoˇca klic metode raise for status, ki jo pokliˇcemo v vrstici 22. Metoda v primeru, da statusna koda HTTP v odgovoru nakazuje na napako, sproˇzi izjemo (to informacijo lahko uporabi me- hanizem za ponovno poskuˇsanje v poglavju 5.5.1).
• Informacijo iz telesa odgovora TikTokovega streˇznika v vrstici 28 pre- tvorimo v t. i.BaseModel razred. Tak razred omogoˇca, da vanj uvozimo informacijo formata JSON, nato pa dostopamo do vseh polj, ki smo jih dobili v odgovoru.
• V vrstici 30 pogledamo poljecode v odgovoru in v primeru, da vrednost ni enaka 0, sproˇzimo izjemo, saj to pomeni, da je pri zahtevku priˇslo do napake. V nasprotnem primeru pa vrnemo polje data v odgovoru, ki vsebuje vse informacije o naloˇzeni datoteki, tam pa nas najbolj zanima identifikator medija.
Koda metode api helper
1 import j s o n 2 import r e q u e s t s 3
4 def a p i h e l p e r (
5 s e l f , u r l : str , params : d i c t[str, s t r] 6 ) −> ReturnType :
7 ”””
8 Send a POST r e q u e s t t o TikTok API u s i n g t h e g i v e n URL and p a r a m e t e r s .
9
10 : param u r l : URL o f t h e r e q u e s t
11 : param params : d i c t i o n a r y o f r e q u e s t p a r a m e t e r s 12 : r e t u r n : TikTok ’ s r e s p o n s e i n form o f a d i c t i o n a r y
13 ”””
14 r e s p o n s e = s e l f . s e s s i o n . p o s t (
15 u r l=u r l ,
16 t i m e o u t= s e l f . c o n f i g u r a t i o n . t i m e o u t s e c o n d s ,
17 params=params ,
18 a l l o w r e d i r e c t s=True ,
19 )
20
21 try:
22 r e s p o n s e . r a i s e f o r s t a t u s ( ) 23 except r e q u e s t s . HTTPError a s e x c : 24 r a i s e F a i l e d R e q u e s t E x c e p t i o n (
25 h t t p e r r o r c o d e=r e s p o n s e . s t a t u s c o d e , msg=r e s p o n s e . t e x t , u r l=u r l , params=s t r( params )
26 ) from e x c
27
28 p a r s e d r e s p o n s e = TikTokAPIResponse (∗∗r e s p o n s e . j s o n ( ) ) 29
30 i f p a r s e d r e s p o n s e . c o d e != ApiResponseCode . SUCCESS : 31 r a i s e F a i l e d R e q u e s t E x c e p t i o n (
32 t i k t o k e r r o r c o d e=i n t( p a r s e d r e s p o n s e . c o d e ) , 33 msg=p a r s e d r e s p o n s e . message ,
34 u r l=u r l ,
35 params=s t r( params ) ,
36 )
37
38 return p a r s e d r e s p o n s e . d a t a
V kodi in opisu postopka smo omenili tudi BaseClass TikTokAPIRe- sponse, ki vsebuje odgovor TikTokovega streˇznika. Razred je definiran tako:
1 c l a s s TikTokAPIResponse ( BaseModel ) : 2 c o d e : i n t
3 message : s t r
4 d a t a : d a t a [str, Any ]
Diplomska naloga 29 Omeniti je treba tudi razlike pri nalaganju slik in videov. Prva razlika je razliˇcen URL, kamor moramo poslati medij. Zgornji metodi api helper kot argumenturl posredujemo primerno vrednost iz naslednjega razreda:
1 c l a s s TikTokApiURL (Enum) :
2 ”””
3 P o s s i b l e u p l o a d URLs f o r TikTok .
4 ”””
5
6 UPLOAD IMAGE = ” h t t p s : / / b u s i n e s s−a p i . t i k t o k . com/ o p e n a p i / v1 . 2 / f i l e / image / ad / u p l o a d / ”
7 UPLOAD VIDEO = ” h t t p s : / / b u s i n e s s−a p i . t i k t o k . com/ o p e n a p i / v1 . 2 / f i l e / v i d e o / ad / u p l o a d / ”
Razlika obstaja tudi pri procesiranju odgovora: v primeru nalaganja slike moramo za pridobitev identifikatorja vzeti podatek iz polja id, v primeru nalaganja videa pa iz poljavideo id.
Omejitve in pasti
• Statusni kodi: Ko prejmemo odgovor streˇznika na naˇs zahtevek, pre- verimo njegovi statusni kodi, ki bi lahko nakazovali na napako. Pregle- dati moramo tako statusno kodo HTTP kakor tudi
”kodo TikTok“, ki je vsebovana v telesu odgovora. ˇCetudi prva koda nakazuje na uspeˇsen klic, lahko slednja nakazuje na napako (npr. da smo enak medij ˇze naloˇzili).
• Datoteke GIF: Platforma TikTok datotek GIF ˇzal ne podpira. V primeru, da jih skuˇsamo tja naloˇziti, v odgovor dobimo le kodo 40904 (kar pomeni, da streˇznik v datoteki zazna napako).
5.4.3 YouTube
Pri implementaciji integracije s platformo YouTube smo se seveda lahko osre- dotoˇcili le na nalaganje videov, saj slik platforma ne podpira.
Podobno kot pri Facebooku tudi Google za nalaganje na YouTube nudi lastno knjiˇznico za jezik Python. Knjiˇznica googleapiclient je sicer name-
njena vsakrˇsnemu upravljanju z API-ji pod Googlovim okriljem, YouTube pa je na sreˇco med podprtimi vmesniki.
V naˇsem primeru ˇzelimo vse video vsebine naloˇziti na za to namenjen YouTube kanal. To storimo na naslednji naˇcin:
• Inicializacija objektagoogleapiclient.discovery.Resource: Prek tega objekta lahko ustvarimo nekakˇsen
”zametek“ datoteke na YouTubovem streˇzniku, kamor potem lahko tudi naloˇzimo medij. Da objekt instan- ciramo, mu moramo med drugim podati OAuth poverilnice (veˇc o njih v podpoglavju o posebnostih pri nalaganju na YouTube). V naslednjih korakih bo ta objekt imenovan client.
• Doloˇcanje atributov oz. metapodatkov o videu: Da lahko po- kliˇcemo metodo za nalaganje videa, moramo prej doloˇciti vse potrebne metapodatke. Med te spadajo naslov videa, morebiten opis videa, ter t. i.
”vidnost“ videa (ta doloˇca, ali lahko uporabniki video najdejo prek iskalne funkcije na YouTubu).
• Dodajanje datoteke in izvrˇsevanje nalaganja: Ko doloˇcimo vse atribute videoposnetka, lahko pokliˇcemo metodo za ustvarjanje zah- tevka za nalaganje (client.videos().insert()), ki ji kot argumente po- damo metapodatke iz prejˇsnjega koraka in poseben objekt, ki predsta- vlja lokacijo videa na disku, ter na kakˇsen naˇcin naj knjiˇznica video poˇslje (npr. ali naj samodejno ponovi nalaganje v primeru napake). Ta zahtevek za nalaganje nato ˇse
”izvrˇsimo“, tako da na njem pokliˇcemo metodo execute.
• Pridobivanje identifikatorja naloˇzenega medija: Metodaexecute iz prejˇsnjega koraka v primeru uspeha kot rezultat vrne odgovor for- mata JSON, ki vsebuje razne podatke o naloˇzenem videu. Med to spadajo metapodatki, ki smo jih sami doloˇcili, ˇse pomembnejˇsi pa je enoliˇcni identifikator naloˇzenega videoposnetka. Tega lahko nato upo- rabimo pri postopkih oglaˇsevanja. Kot zanimivost - ta enoliˇcni identi-
Diplomska naloga 31 fikator je toˇcno tisti, ki ga vidimo v naslovni vrstici brskalnika, ˇce si na YouTubu ogledamo naloˇzeni video.
Primer kode za inicializacijo objekta Resource ter nalaganje videov
1 import g o o g l e . oauth2 . c r e d e n t i a l s 2 import g o o g l e a p i c l i e n t
3 import g o o g l e a p i c l i e n t . d i s c o v e r y
4 from g o o g l e a p i c l i e n t . d i s c o v e r y import R e s o u r c e 5 from g o o g l e a p i c l i e n t . h t t p import M e d i a F i l e U p l o a d 6
7 c l a s s BaseManager :
8 ”””
9 Base Youtube API wrapper f o r Ads management .
10 ”””
11
12 def i n i t (
13 s e l f ,
14 c r e d e n t i a l s : g o o g l e . oauth2 . c r e d e n t i a l s . C r e d e n t i a l s
15 ) :
16 s e l f . c l i e n t : R e s o u r c e = g o o g l e a p i c l i e n t . d i s c o v e r y . b u i l d (
17 s e r v i c e N a m e=” youtube ” ,
18 v e r s i o n=” v3 ” ,
19 c r e d e n t i a l s=c r e d e n t i a l s , 20 c a c h e d i s c o v e r y=F a l s e ,
21 r e q u e s t B u i l d e r=g e t r e q u e s t b u i l d e r ( 22 o a u t h c r e d e n t i a l s=c r e d e n t i a l s
23 ) ,
24 )
25
26 def e x e c u t e v i d e o u p l o a d (
27 s e l f ,
28 v i d e o f i l e p a t h : s t r 29 ) −> s t r:
30 ”””
31 Upload v i d e o t o t h e YouTube a c c o u n t .
32
33 : param v i d e o f i l e p a t h : l o c a l f i l e p a t h o f t h e v i d e o 34 : r e t u r n : t h e new v i d e o ID
35 ”””
36 body = {
37 ” s t a t u s ” : {
38 ” embeddable ” : True ,
39 ” p r i v a c y S t a t u s ” : ” u n l i s t e d ” , 40 ” s e l f D e c l a r e d M a d e F o r K i d s ” : F a l s e ,
41 },
42 }
43 r e q u e s t = s e l f . c l i e n t . v i d e o s ( ) . i n s e r t ( 44 p a r t=” , ” . j o i n ( body . k e y s ( ) ) ,
45 body=body ,
46 media body=M e d i a F i l e U p l o a d ( 47 f i l e n a m e=v i d e o f i l e p a t h ,
48 c h u n k s i z e =−1,
49 r e s u m a b l e=True ,
50 ) ,
51 )
52
53 r e s p o n s e = r e q u e s t . e x e c u t e ( )
54 try:
55 v i d e o i d : s t r = r e s p o n s e [ ” i d ” ] 56 except KeyError a s e x c e p t i o n :
57 r a i s e Y o u T u b e M a n a g e r C r i t i c a l E r r o r (
58 f ” m i s s i n g v i d e o i d from youtube r e s p o n s e : { r e s p o n s e}”
59 ) from e x c e p t i o n
60
61 return v i d e o i d
Nastavljanje dodatnih informacij naloˇzenim videoposnetkom YouTube prek svojega aplikacijskega vmesnika podpira tudi samodejno na- stavljanje naslova ter podnaslova videa. Po tem, ko video naloˇzimo, pa lahko z novim klicem naloˇzimo tudi predogledno sliˇcico videa (ang. thumbnail), ki se vˇcasih prikaˇze uporabnikom, preden se jim prikaˇze video kot oglas.
Diplomska naloga 33 Da podpremo nastavljanje lastnega naslova in podnaslova, lahko v zgornji kodi spremenljivko body spremenimo na naslednji naˇcin, kjer spremenljivki video title ter video description sprejmemo kot argumenta zgornje funkcije
execute video upload:
1 body = {
2 ” s n i p p e t ” : {
3 ” t i t l e ” : v i d e o t i t l e ,
4 ” d e s c r i p t i o n ” : v i d e o d e s c r i p t i o n ,
5 },
6 ” s t a t u s ” : {
7 ” embeddable ” : True ,
8 ” p r i v a c y S t a t u s ” : ” u n l i s t e d ” , 9 ” s e l f D e c l a r e d M a d e F o r K i d s ” : F a l s e ,
10 },
11 }
Da pa lahko po pridobitvi identifikatorja naloˇzenega videoposnetka temu posnetku dodelimo lastno predogledno sliˇcico, moramo v razredBaseM anager, ki je prikazan v zgornji kodi, dodati ˇse metodo execute thumbnail upload, ki jo pokliˇcemo le po uspeˇsnem nalaganju posnetka.
1 def e x e c u t e t h u m b n a i l u p l o a d (
2 s e l f ,
3 v i d e o i d : str,
4 t h u m b n a i l l o c a l p a t h : s t r 5 ) −> None :
6 r e q u e s t = s e l f . c l i e n t . t h u m b n a i l s ( ) .s e t( 7 v i d e o I d=v i d e o i d ,
8 media body=M e d i a F i l e U p l o a d (
9 f i l e n a m e=t h u m b n a i l l o c a l p a t h ,
10 c h u n k s i z e =−1,
11 r e s u m a b l e=True ,
12 ) ,
13 )
14 r e q u e s t . e x e c u t e ( )
Ta metoda kot argument sprejme identifikator videa, ki smo ga naloˇzili, ter pot do predogledne sliˇcice na disku. Sama koda metode pa je razmeroma
preprosta - na clientu, ki smo ga inicializirali v razredu BaseM anager, po- kliˇcemo metodo thumbnails. Ta nam vrne objekt, ki predstavlja novo pre- dogledno sliˇcico, temu objektu pa nato preko metode set lahko podamo in- formacije v ciljnem videu ter o lokaciji sliˇcice na disku. Zahtevo nastavljanja sliˇcice nato ˇse izvrˇsimo.
Omejitve ter pasti
• Kvota za nalaganje medijev: Med raziskovanjem platforme in same dokumentacije za integracijo z aplikacijskim vmesnikom smo odkrili, da vmesnik za vsako aplikacijo, ki ga uporablja, uveljavlja zelo stroge kvote za uporabo. Natanˇcneje: novi
”projekti“, ki uporabljajo YouTu- bov aplikacijski vmesnik, imajo vsak dan pravico do 10.000 t. i. enot [8]. Ta omejitev je predstavljala znatno teˇzavo, saj vsak naloˇzen video porabi 1600 enot [9] (v dokumentaciji glej vrsticovideos→ insert), to- rej bi lahko vsak dan naloˇzili le 6 videov, kar pa je za podjetje bistveno premalo.
Dokumentacija tudi navede, da lahko lastnik projekta zaprosi za po- veˇcanje kvote. Izpolniti je treba obrazec [10], v katerem je potrebno obrazloˇziti naˇcin uporabe aplikacijskega vmesnika ter koliˇcino ˇzelenih enot.
• OAuth ter vrste aplikacije: Da lahko uporabljamo YouTubov apli- kacijski vmesnik, moramo programu, ki vmesnik uporablja, prej zago- toviti nekatereˇzetone preko avtentikacijskega in avtorizacijskega stan- darda OAuth. Da lahko generiramo ˇzetone, moramo za vsako okolje (razvojno, testno in produkcijsko), v katerem teˇce program, ustvariti t. i. OAuth aplikacijo.
Prvi korak je priprava t. i. strani privolitve (ang. consent screen) [11].
Tam je med drugim potrebno navestistatus izdajanja (ang. publishing status), ki je lahko bodisi testiranje, bodisi v produkciji. Vsaka izmed moˇznosti ima svoje slabosti - aplikacija s statusom v produkciji je na
