Michael JohnsonSovelluksen tai uuden ominaisuuden julkaisun jälkeen palaute hajaantuu nopeasti lyhyisiin videoihin. Markkinoija etsii käsin muutaman videon ja lähettää linkit chattiin, mutta analyytikko ei myöhemmin pysty selvittämään, mitkä julkaisut on jo huomioitu ja miten katselukerrat ovat muuttuneet. Käytännöllinen ratkaisu on kerätä hakutuloksia säännöllisesti muutamalla vakaalla hakulausekkeella, tallentaa alkuperäiset vastaukset ja laatia raportti vahvistettujen kenttien perusteella.
Tässä oppaassa määritämme tiedonkeruun tiettyä tilannetta varten: tiimi on julkaissut uuden ominaisuuden ja haluaa seurata viikoittain julkisia TikTok-videoita, joiden kuvauksissa mainitaan tuotteen nimi, keskeinen ominaisuus tai tyypillinen käyttäjän ongelma. Kyseessä on löydettyyn hakutulosotokseen perustuva seuranta: API palauttaa kyselyn ja parametrien mukaisia tuloksia, ei taattua luetteloa kaikista julkaisuun liittyvistä julkaisuista.
Määritä ensin, mitä signaalia tiimi tarvitsee
Katselukertojen suuri määrä ei yksin kerro, mitä pitäisi tehdä seuraavaksi. Tiimin on hyödyllisempää tietää, mitkä kysymykset toistuvat, millaisia käyttötapoja ihmiset esittelevät ja mitkä videot saavat huomattavia julkisia reaktioita. Muotoile siis ensin muutama hakulauseke ja päätä, mitkä kentät sisällytetään raporttiin.
Esimerkiksi julkaisujen suunnittelutyökalun lanseerauksessa voi kokeilla hakusanoja ”tuotteen nimi”, ”sisältökalenteri” ja ”miten TikTok-julkaisu ajastetaan”. Lausekkeiden tulisi kuvata eri tapoja, joilla ihmiset voivat käsitellä samaa aihetta. Kirjaa ne yhdessä seurannan aloituspäivän ja alueen kanssa, jotta myöhempiä poimintoja voidaan vertailla samoilla asetuksilla.
Vähimmäistaulukkoon voi sisällyttää keräysajan, hakulausekkeen, videon tunnisteen, linkin, kuvauksen, tekijän nimen, tekijän tunnisteen sekä saatavilla olevat katselu-, tykkäys- ja kommenttimäärät. TikTok Scraper APIn dokumentaatiossa hakutuloksille mainitaan kenttiä, kuten aweme_id, desc, share_url, tekijän tiedot ja osa tilastoista. Tarkista kentän olemassaolo jokaisesta objektista: yksittäisiä mittareita voi puuttua.
Ota dokumentoitu haku käyttöön
Käytä videoiden etsimiseen GET-reittiä /searchVideo perusosoitteessa https://tiktok.evelode.com. Dokumentaatiossa luetellaan pakollinen parametri keyword sekä lisäparametrit count, cursor, date_posted, sort_by, region ja cache_timeout. Päivämääräsuodattimen sallittuihin arvoihin kuuluu this-week, ja lajitteluarvoihin relevance, most-liked ja date-posted. Tarkista niiden käyttötarkoitus ja nimet TikTok-APIn reittiohjeesta.
Lisenssiavain välitetään kyselyparametrina license_key. Lue se tuotantokäytössä ympäristömuuttujasta JSONSCRAPER_TIKTOK_LICENSE_KEY, älä kirjoita salaisuutta lähdekoodiin äläkä tulosta sitä lokeihin. Esimerkki edellyttää Python 3.8+:aa ja käyttää requests-pakettia:
import os
import requests
BASE_URL = "https://tiktok.evelode.com"
API_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
def search_videos(keyword, cursor=None):
params = {
"license_key": API_KEY,
"keyword": keyword,
"count": 20,
"date_posted": "this-week",
"sort_by": "date-posted",
"region": "US",
}
if cursor is not None:
params["cursor"] = cursor
response = requests.get(
f"{BASE_URL}/searchVideo",
params=params,
timeout=30,
)
response.raise_for_status()
payload = response.json()
if payload.get("status") != "ok":
raise RuntimeError("TikTok API palautti muun kuin ok-tilan")
return payload["tiktok"]
result = search_videos("content planning app")
print("Löydettyjä objekteja:", len(result.get("aweme_list", [])))Skripti tarkistaa HTTP-virheet ja vastauksen ylimmän tason tilan. Onnistunut HTTP-vastaus ei itsessään takaa, että hausta löytyy videoita: tyhjän otoksen luettelo voi olla tyhjä. Ensimmäisellä ajokerralla koko vastaus kannattaa tallentaa suojattuun tallennustilaan, jotta todellisia objekteja voi verrata normalisoitujen kenttien taulukkoon.
Käsittele haun kaksi vastausrakennetta
Hakutuloksissa on tärkeä rakenteellinen piirre. Videot voivat olla suoraan kohdassa tiktok.aweme_list tai ne voivat tulla kohdassa tiktok.search_item_list[].aweme_info. Jos käsittelijä lukee vain ensimmäistä luetteloa, se saattaa ohittaa toisessa rakenteessa olevat tulokset.
Lisää pieni normalisointifunktio, joka tukee molempia rakenteita ja ohittaa turvallisesti kohteet, joista puuttuu sisäkkäinen video-objekti:
def extract_awemes(tiktok):
items = list(tiktok.get("aweme_list") or [])
for item in tiktok.get("search_item_list") or []:
aweme = item.get("aweme_info")
if aweme:
items.append(aweme)
return items
def normalize(aweme, keyword, collected_at):
author = aweme.get("author") or {}
stats = aweme.get("statistics") or {}
return {
"collected_at": collected_at,
"keyword": keyword,
"video_id": aweme.get("aweme_id"),
"posted_at": aweme.get("create_time"),
"description": aweme.get("desc"),
"share_url": aweme.get("share_url"),
"author_id": author.get("uid"),
"author_name": author.get("nickname"),
"views": stats.get("play_count"),
"likes": stats.get("digg_count"),
"comments": stats.get("comment_count"),
"shares": stats.get("share_count"),
}Puuttuvan arvon tilalle jää None. Älä korvaa sitä nollalla: nolla tarkoittaa mitattua arvoa, kun taas None säilyttää tiedon siitä, ettei kenttää tullut vastauksessa. Ero vaikuttaa keskiarvoihin, osuuksiin ja kaikkiin niistä tiimille tehtäviin päätelmiin.
Tallenna historia, älä vain nykyistä tilannekuvaa
Tallenna kehityksen seuraamiseksi erillisiä havaintotietueita. Videon tunniste sopii julkaisujen duplikaattien tunnistamiseen, mutta ei historian poistamiseen: kun sama video löytyy seuraavalla keruukerralla, siitä saadaan uusi havainto. Havaintotaulukon yksilöllinen avain voi esimerkiksi muodostua kentistä video_id ja collected_at. Tallenna linkki ja kuvaus tietueeseen tarkistamisen helpottamiseksi.
SQLite-tietokannan vähimmäisrakenne sopii prototyyppiin:
import sqlite3
conn = sqlite3.connect("tiktok_observations.sqlite3")
conn.execute("""
CREATE TABLE IF NOT EXISTS observations (
video_id TEXT NOT NULL,
collected_at TEXT NOT NULL,
keyword TEXT NOT NULL,
posted_at INTEGER,
description TEXT,
share_url TEXT,
author_id TEXT,
author_name TEXT,
views INTEGER,
likes INTEGER,
comments INTEGER,
shares INTEGER,
PRIMARY KEY (video_id, collected_at, keyword)
)
""")
conn.commit()Käytännössä normalisoi keräysajankohta UTC-aikaan, tallenna alkuperäinen JSON erikseen ja lisää skeemaversion sisältävä sarake. Alkuperäisestä vastauksesta voi tarkistaa muunnoksen, jos uudet objektit poikkeavat tutusta rakenteesta. Jos julkaisu löytyy usealla hakulausekkeella, tallenna osuneet hakusanat erilliseen linkitettyyn tauluun tai yhdistä ne raporttia muodostettaessa.
Sivutus: jatka vain vastauksesta saadulla kursorilla
cursor-parametrilla jatketaan hakua. Sen arvo otetaan edellisestä vastauksesta ja välitetään takaisin muuttamatta. Haku päättyy, kun has_more ei enää ilmoita jatkosta tai kun määritetty raja saavutetaan. Kursoria tulee käsitellä läpinäkymättömänä arvona: älä laske sitä itse äläkä korvaa sivulaskurilla.
def collect_pages(keyword, max_pages=3):
cursor = None
collected = []
for _ in range(max_pages):
page = search_videos(keyword, cursor)
collected.extend(extract_awemes(page))
if not page.get("has_more"):
break
cursor = page.get("cursor")
if cursor is None:
break
return collectedSivujen määrän rajaaminen tekee säännöllisestä työstä ennakoitavan kyselymäärän osalta. Kirjaa suorituksen lokiin sivujen määrä ja has_more-arvo: ne antavat kontekstia otosta koskevalle raportille. Sivutuksesta huolimatta tulos kuvaa API:n palauttamia vastauksia ja keruulle asetettua rajaa; se ei ole arvio kaikista alustan julkaisuista.
Kokoa toistettava raportti
Aja keruu aikataulun mukaan viikoittain tai useammin, jos tiimi tarvitsee signaaleja tiheämmin. Kirjaa jokaisesta ajosta hakulausekkeet, parametrit, ajankohta, saatujen objektien määrä ja yksilöllisten tunnisteiden määrä. Laske erikseen tässä ajossa ensimmäistä kertaa havaitut julkaisut ja aiemmin löydetyt julkaisut.
Raporttiin sopii neljä yksinkertaista näkymää:
- Uudet videot: linkit, kuvaukset, julkaisupäivät ja hakulausekkeet, joilla videot löytyivät.
- Toistuvat aiheet: kuvausten ryhmittely käsin määriteltyihin luokkiin, kuten ”asetusvirhe”, ”ominaisuuspyyntö” ja ”käyttötapaesittely”.
- Julkiset reaktiot: saatavilla olevat katselukerrat, tykkäykset, kommentit ja jaot esitettyinä havaintoajankohdan yhteydessä.
- Tarkistettavat signaalit: uudet ilmaisut, usein esitetyt kysymykset tai videot, joihin työntekijän kannattaa perehtyä.
Älä kutsu kahden tilannekuvan välistä erotusta ”uusiksi tykkäyksiksi” tarkistamatta ensin vastausten arvojen merkitystä ja ajantasaisuutta. Täsmällisempi ilmaus on ”viimeisimmässä saadussa vastauksessa ollut mittariarvo” ja ”tallennettujen tilannekuvien välinen ero”. Näin tiimi näkee, mitä on laskettu, ja voi avata alkuperäisen julkaisun ennen päätöksentekoa.
Käytä tekoälyä luokitteluun, älä tiedonkeruun korvaamiseen
Normalisoinnin jälkeen videokuvaukset voi toimittaa mallille ennalta määriteltyihin luokkiin luokittelua varten. Lähetä vain tarvittavat tekstikentät ja pyydä jäsennelty tulos: luokka, lyhyt perustelu, luottamustaso ja kuvauksen katkelma, johon luokitus perustuu. Säilytä alkuperäinen julkaisu luokituksen rinnalla, jotta analyytikko voi tarkistaa epäselvät tapaukset.
Työnkulku pysyy yksinkertaisena: ajastin käynnistää keruun, Python tarkistaa vastauksen ja tallentaa JSONin, erillinen tehtävä normalisoi uudet tietueet, luokittelija käsittelee vain uudet kuvaukset ja raportti kootaan tietokannasta sekä toimitetaan tiimin valitsemaan kanavaan. TikTok Scraper API tarjoaa hakutiedot, kun taas luokittelu ja raportin toimitus ovat omaa integraatiologiikkaasi, jonka voi toteuttaa Pythonilla, n8n:llä tai Makella.
Vähennä kohinaa määrittämällä luokkasanasto ennen tekstien lähettämistä mallille ja tarkistamalla säännöllisesti käsin merkitty otos. Lyhyille tai monitulkintaisille kuvauksille on hyödyllistä antaa tila ”kontekstia ei ole riittävästi” sen sijaan, että valittaisiin väkisin jokin luokka. Tekoälyluokitukset auttavat järjestämään tarkistusjonon, mutta päätelmät käyttäjien ongelmista on vahvistettava lukemalla julkaisut ja vertailemalla useita havaintoja.
Virheet, uudelleenyritykset ja avaimen turvallinen käsittely
Verkkopyyntö voi päättyä aikakatkaisuun tai tilapäiseen virheeseen, tai vastausta ei ehkä pystytä jäsentämään JSONiksi. Jaa käsittely vaiheisiin: pyyntö, HTTP-koodin tarkistus, JSONin jäsennys, ulomman tilan tarkistus, normalisointi ja tallennus. Käytä tilapäisissä häiriöissä rajattua määrää uudelleenyrityksiä ja pidennä viivettä niiden välillä. Kirjaa pysyvät virheet myöhempää selvitystä varten äläkä merkitse ajoa onnistuneeksi.
Säilytä avain ajoalustan salaisuuksien hallintapalvelussa tai ympäristömuuttujassa. Koska API ottaa license_key-arvon kyselymerkkijonossa, vältä koko URL-osoitteen ja kyselyparametrien lokittamista: niihin päätyisi salaisuus. Kirjaa diagnostiikkaa varten reitti, vastauskoodi, kesto, hakulauseke ja tehtävän tunniste, mutta poista avain lokeista.
Aseta aikataulu ja otoksen koko oman käyttötarpeesi ja alustan käyttöehtojen mukaisesti. Julkisten tietojen keruu kannattaa rajata siihen, mitä analyysi todella tarvitsee. Kuvausten, linkkien ja tekijätunnisteiden tallennus tulee kuvata tiimin sisäisissä ohjeissa. API-vastaukset ja mittarit voivat olla puutteellisia tai muuttua havaintokertojen välillä, joten raportissa on säilytettävä kunkin rivin keräysaika ja alkuperä.
Tulos: käsin jaetuista linkeistä tarkistettavaan historiaan
Kun järjestelmä on määritetty, tiimi saa säännöllisesti päivittyvän luettelon löydetyistä videoista, auditointia varten alkuperäiset vastaukset, saatavilla olevien julkisten mittareiden taulukon ja yhteenvedon toistuvista aiheista. Tämä auttaa huomaamaan uutta ominaisuutta koskevia kysymyksiä nopeammin, löytämään esimerkkejä käyttötavoista ja valitsemaan julkaisuja käsin analysoitaviksi. Tilannekuvien vertailu näyttää, miten jo löydettyjen videoiden tallennetut arvot muuttuvat, ja hakujen loki kertoo, miten otos muodostui.
Aloita yhdellä hakulausekkeella ja pienellä sivurajalla, tarkista vastauksen todellinen rakenne ja lisää sitten muita ilmaisuja sekä ajastus. Ennen prototyypin siirtämistä tuotantoon määritä duplikaattien käsittely-, tallennus- ja virheenkäsittelysäännöt. Ajantasaiset reitit ja parametrit löytyvät APIn virallisesta dokumentaatiosta, ja ominaisuuksien kuvaus sekä linkki kokeiluun löytyvät TikTok Scraper API -sivulta.
