Michael JohnsonPo premierze aplikacji lub nowej funkcji opinie szybko rozpraszają się w krótkich filmach. Marketer ręcznie znajduje kilka materiałów i przesyła linki na czacie, a analityk później nie może ustalić, które publikacje już uwzględniono ani jak zmieniała się liczba wyświetleń. Praktycznym rozwiązaniem jest regularne zbieranie wyników wyszukiwania dla kilku stabilnych zapytań, zapisywanie surowych odpowiedzi i tworzenie raportu na podstawie potwierdzonych pól.
W tym przewodniku skonfigurujemy zbieranie danych dla konkretnego przypadku: zespół wprowadził nową funkcję i chce co tydzień monitorować publiczne filmy TikTok, których opisy zawierają nazwę produktu, kluczową funkcję lub typowy problem użytkownika. Jest to monitoring wyników znalezionych w wyszukiwarce: API zwraca wyniki dla zapytania i określonych parametrów, a nie gwarantowaną listę wszystkich publikacji dotyczących premiery.
Najpierw określ, jakiego sygnału potrzebuje zespół
Sama duża liczba wyświetleń niewiele mówi o tym, co należy zrobić dalej. Zespołowi bardziej przydadzą się informacje o powtarzających się pytaniach, prezentowanych przez użytkowników scenariuszach oraz filmach, które uzyskują zauważalne publiczne reakcje. Dlatego najpierw sformułuj kilka fraz wyszukiwania i zdecyduj, które pola znajdą się w raporcie.
Na przykład w przypadku premiery narzędzia do planowania publikacji można sprawdzić zapytania „nazwa produktu”, „planer treści” i „jak zaplanować TikToka”. Frazy powinny odzwierciedlać różne sposoby opisywania tego samego tematu. Zapisz je wraz z datą rozpoczęcia monitoringu i regionem, aby można było porównywać kolejne eksporty przy tych samych ustawieniach.
Minimalna tabela może zawierać czas zebrania danych, frazę wyszukiwania, identyfikator filmu, link, opis, nazwę autora, identyfikator autora oraz dostępne wartości wyświetleń, polubień i komentarzy. TikTok Scraper API dokumentuje w wynikach wyszukiwania takie pola jak aweme_id, desc, share_url, dane autora i część statystyk. Każde konkretne pole trzeba sprawdzać w poszczególnych obiektach: niektórych metryk może brakować.
Skonfiguruj udokumentowane wyszukiwanie
Do wyszukiwania filmów użyj trasy GET /searchVideo pod adresem bazowym https://tiktok.evelode.com. Dokumentacja wymienia wymagany parametr keyword oraz dodatkowe parametry count, cursor, date_posted, sort_by, region i cache_timeout. Dozwolone wartości filtra daty obejmują this-week, a sortowania — relevance, most-liked i date-posted. Ich przeznaczenie i nazwy sprawdź w dokumentacji tras TikTok API.
Klucz licencyjny przekazuje się jako parametr zapytania license_key. W skrypcie produkcyjnym odczytuj go ze zmiennej środowiskowej JSONSCRAPER_TIKTOK_LICENSE_KEY, nie zapisuj sekretu w kodzie źródłowym ani nie umieszczaj go w logach. Ten przykład wymaga Pythona 3.8 lub nowszego i korzysta z pakietu requests:
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 zwróciło status inny niż ok")
return payload["tiktok"]
result = search_videos("content planning app")
print("Znalezione obiekty:", len(result.get("aweme_list", [])))Skrypt sprawdza błędy HTTP i zewnętrzny status odpowiedzi. Pomyślna odpowiedź HTTP sama w sobie nie gwarantuje, że wyszukiwanie zwróciło filmy: przy pustym zbiorze lista może być pusta. Przy pierwszym uruchomieniu warto zapisać całą odpowiedź w bezpiecznym miejscu, aby porównać rzeczywiste obiekty z tabelą znormalizowanych pól.
Obsłuż oba warianty odpowiedzi wyszukiwania
Wyniki wyszukiwania mają ważną cechę strukturalną. Filmy mogą znajdować się bezpośrednio w tiktok.aweme_list albo być zwracane wewnątrz tiktok.search_item_list[].aweme_info. Jeśli obsługa odczytuje tylko pierwszą listę, może pominąć wyniki obecne w drugim wariancie.
Dodaj niewielki normalizator, który obsługuje obie struktury i pomija elementy bez zagnieżdżonego obiektu filmu:
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"),
}Brakująca wartość pozostaje None. Nie zastępuj jej zerem: zero oznacza zmierzoną wartość, natomiast None zachowuje informację, że pole nie zostało zwrócone. Ta różnica wpływa na średnie, udziały i wszystkie wnioski wyciągane przez zespół.
Zachowaj historię, a nie tylko bieżący stan
Aby śledzić zmiany, przechowuj osobne rekordy obserwacji. Identyfikator filmu nadaje się do deduplikacji publikacji, ale nie do usuwania historii: ponowne pojawienie się tego samego filmu podczas kolejnego zbierania danych daje nowy punkt obserwacji. Na przykład unikalny klucz tabeli obserwacji można utworzyć z video_id i collected_at, a link i opis zapisywać w rekordzie, by ułatwić weryfikację.
Minimalny schemat SQLite przyda się do prototypu:
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()W praktyce normalizuj czas zbierania danych do UTC, przechowuj osobno pierwotny JSON i dodaj kolumnę wersji schematu. Surowa odpowiedź pomaga ponownie sprawdzić transformację, gdy struktura nowych obiektów różni się od typowej. W przypadku publikacji znalezionych przez kilka zapytań zapisuj dopasowane frazy w osobnej, powiązanej tabeli albo łącz je podczas tworzenia raportu.
Paginacja: kontynuuj tylko przy użyciu kursora z odpowiedzi
Parametr cursor służy do kontynuowania wyszukiwania. Jego wartość pobiera się z poprzedniej odpowiedzi i przekazuje z powrotem bez modyfikacji; proces kończy się, gdy has_more nie wskazuje już kolejnych wyników albo zostanie osiągnięty ustalony limit. Kursor należy traktować jako nieprzejrzystą wartość: nie obliczaj go samodzielnie i nie zastępuj licznikiem stron.
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 collectedLimit stron sprawia, że regularne zadanie ma przewidywalną liczbę zapytań. Zapisuj liczbę stron i wartość has_more w dzienniku uruchomienia: zapewni to kontekst dla raportu o zbiorze danych. Nawet przy paginacji wyniki opisują odpowiedzi otrzymane z API i ustalony limit zbierania danych; nie są oszacowaniem wszystkich publikacji na platformie.
Przygotuj powtarzalny raport
Uruchamiaj zbieranie danych według harmonogramu raz w tygodniu lub częściej, jeśli zespół potrzebuje częstszych sygnałów. Dla każdego uruchomienia zapisuj listę zapytań, parametry, czas, liczbę otrzymanych obiektów i liczbę unikalnych identyfikatorów. Osobno licz publikacje zauważone po raz pierwszy w danym uruchomieniu oraz te, które pojawiły się już wcześniej.
Raport może zawierać cztery proste zestawienia:
- Nowe filmy: linki, opisy, daty publikacji i frazy wyszukiwania, za pomocą których znaleziono materiały.
- Powtarzające się tematy: grupowanie opisów według ręcznie określonych kategorii, takich jak „błąd konfiguracji”, „prośba o funkcję” i „przegląd scenariusza”.
- Publiczne reakcje: dostępne wyświetlenia, polubienia, komentarze i udostępnienia, pokazywane wraz z czasem obserwacji.
- Sygnały do weryfikacji: nowe sformułowania, częste pytania lub filmy, które warto sprawdzić.
Nie nazywaj różnicy między dwoma zrzutami danych „nowymi polubieniami” bez sprawdzenia semantyki i aktualności wartości w odpowiedzi. Precyzyjniejsze sformułowania to „wartość metryki w ostatniej otrzymanej odpowiedzi” i „różnica między zapisanymi zrzutami”. Dzięki temu zespół wie, co dokładnie obliczono, i może otworzyć oryginalną publikację przed podjęciem decyzji.
Wykorzystaj AI do klasyfikacji, a nie zamiast zbierania danych
Po normalizacji możesz przekazać opisy filmów modelowi, aby klasyfikował je według wcześniej określonych kategorii. Wysyłaj tylko niezbędne pola tekstowe i proś o zwrócenie uporządkowanych wyników: kategorii, krótkiego uzasadnienia, poziomu pewności i fragmentu opisu, na którym oparto etykietę. Zachowuj oryginalną publikację razem z etykietą, aby analityk mógł zweryfikować wątpliwe przypadki.
Przepływ pracy pozostaje prosty: harmonogram uruchamia zbieranie danych; Python weryfikuje odpowiedź i zapisuje JSON; osobne zadanie normalizuje nowe rekordy; klasyfikator przetwarza tylko nowe opisy; raport powstaje na podstawie bazy danych i jest wysyłany do wybranego przez zespół kanału. Sam TikTok Scraper API udostępnia dane z wyszukiwania, a klasyfikacja i dostarczenie raportu to logika integracyjna, którą można wdrożyć w Pythonie, n8n lub Make.
Aby ograniczyć szum, przygotuj słownik kategorii przed przekazaniem danych modelowi i co jakiś czas sprawdzaj ręcznie oznakowaną próbkę. W przypadku krótkich lub niejednoznacznych opisów przydatny jest status „za mało kontekstu”, zamiast wymuszania wyboru kategorii. Etykiety AI pomagają sortować kolejkę materiałów do sprawdzenia, ale wnioski o problemach użytkowników należy potwierdzać, czytając publikacje i porównując kilka obserwacji.
Błędy, ponawianie prób i bezpieczne obchodzenie się z kluczem
Żądanie sieciowe może zakończyć się przekroczeniem limitu czasu, tymczasowym błędem albo odpowiedzią, której nie uda się zinterpretować jako JSON. Podziel obsługę na etapy: żądanie, sprawdzenie kodu HTTP, interpretacja JSON, weryfikacja zewnętrznego statusu, normalizacja i zapis. Przy tymczasowych problemach stosuj ograniczoną liczbę ponowień z coraz dłuższymi przerwami; trwałe błędy zapisuj do późniejszej analizy i nie oznaczaj uruchomienia jako udanego.
Przechowuj klucz w menedżerze sekretów środowiska uruchomieniowego lub w zmiennej środowiskowej. Ponieważ API przyjmuje license_key w ciągu zapytania, unikaj zapisywania w logach pełnego adresu URL i parametrów żądania, bo znajdzie się wśród nich sekret. Na potrzeby diagnostyki zapisuj trasę, kod odpowiedzi, czas trwania, frazę wyszukiwania i identyfikator zadania, usuwając klucz z logów.
Ustal harmonogram i zakres zbioru danych odpowiednio do zadania oraz warunków korzystania z platformy. Zbieranie danych publicznych warto ograniczyć do informacji rzeczywiście potrzebnych do analizy; zasady przechowywania opisów, linków i identyfikatorów autorów należy opisać w wewnętrznych wytycznych zespołu. Odpowiedzi API i metryki mogą być niepełne lub zmieniać się między obserwacjami, dlatego raport powinien zachowywać czas zbierania i pochodzenie każdego wiersza.
Rezultat: od ręcznie zbieranych linków do weryfikowalnej historii
Po skonfigurowaniu procesu zespół otrzymuje regularnie aktualizowaną listę znalezionych filmów, surowe odpowiedzi do audytu, tabelę dostępnych publicznych metryk i przegląd powtarzających się tematów. Pomaga to szybciej zauważać pytania dotyczące nowej funkcji, znajdować przykłady scenariuszy użytkowników i wybierać publikacje do ręcznej analizy. Porównanie zrzutów pokazuje, jak zmieniają się zapisane wartości dla już znalezionych filmów, a dziennik zapytań wyjaśnia, w jaki sposób utworzono zbiór danych.
Zacznij od jednego zapytania i niewielkiego limitu stron, sprawdź rzeczywistą strukturę odpowiedzi, a następnie dodaj kolejne sformułowania i harmonogram. Przed przeniesieniem prototypu do środowiska produkcyjnego określ zasady deduplikacji, przechowywania i obsługi błędów. Aktualne trasy i parametry znajdziesz w oficjalnej dokumentacji API; opis możliwości i opcję rozpoczęcia testów zawiera strona TikTok Scraper API.
