TikTok: 검색 모니터링이 제대로 작동하는지 확인하는 방법

HTTP 200 응답이 왔다고 해서 매일 실행되는 TikTok 모니터링이 동영상을 수집했다는 뜻은 아닙니다. 검색 결과는 aweme_list 또는 search_item_list[].aweme_info에 들어 있을 수 있습니다. 첫 번째 배열만 읽는 스크립트는 오류 없이 종료된 뒤 빈 보고서를 기록할 수 있습니다. 신뢰할 수 있는 점검은 전송 상태와 애플리케이션 상태를 각각 확인하고, 지원되는 두 가지 구조에서 모두 데이터를 추출하며, 이번 실행에서 고유 동영상을 몇 개 추출했는지 기록합니다.

무엇을 진단해야 할까요?

팀이 매일 아침 여러 검색어로 공개 동영상을 수집해 제품에 관한 새 게시물을 파악한다고 가정해 보겠습니다. 이 작업의 중요한 결과는 설명, 작성자, 게시 날짜, 이용 가능한 지표가 포함된 검색 기록의 재현 가능한 목록입니다. 보고서가 갑자기 비어 있다면 원인은 JSON 처리, 달라진 검색 결과, 이미 확인한 동영상의 중복 반환 또는 실제 요청 실패일 수 있습니다. 예를 들어 aweme_list의 길이처럼 단일 숫자만으로는 이런 경우를 구분하기 어렵습니다.

jsonscraper TikTok Scraper API의 검색 경로 /searchVideo에는 필수 매개변수 keyword와 선택 매개변수 count, cursor, date_posted, sort_by, region이 있습니다. 경로 문서에는 cursor를 사용하는 페이지네이션이 설명되어 있습니다. 이 값은 이전 응답에서 받은 불투명한 값 그대로 전달해야 합니다. count는 원하는 결과 수를 지정할 뿐, 게시물을 모두 가져온다는 보장은 아닙니다.

네 가지 신호를 따로 확인하세요

유용한 진단은 서로 독립적인 네 가지 확인으로 구성됩니다. 첫째, HTTP 요청이 성공적으로 완료되었는지 확인합니다. 둘째, 응답의 바깥쪽 status가 ok이고 내부 tiktok.status_code가 성공을 나타내는지 확인합니다. 셋째, tiktok 객체가 존재하며 문서화된 두 응답 위치에서 기록을 추출할 수 있는지 확인합니다. 넷째, 중복 제거 후 저장에 적합한 식별자가 있는 기록이 남는지 확인합니다. 로그에는 중복 제거 전후의 추출 항목 수를 모두 저장하세요. 두 수의 차이를 보면 정규화 과정에서 중복이 생겼는지 알 수 있습니다.

없는 필드는 비워 두고 임의의 값으로 대체하지 마세요. 예를 들어 특정 기록에는 조회 수가 없을 수 있습니다. 원본 JSON을 정규화된 행과 함께 저장하면 나중에 파싱 과정에서 정보가 누락되었는지, 아니면 원래 응답에 없었는지 확인할 수 있습니다.

Python으로 간단한 요청 및 정규화하기

jsonscraper 사양에는 기본 주소 https://tiktok.evelode.com와 요청 매개변수 license_key로 키를 전달하는 방법이 나와 있습니다. 아래 예시는 문서화된 매개변수를 사용합니다. 키는 환경 변수에서 읽으며 로그에는 출력하지 않습니다. 먼저 python -m pip install requests 명령으로 의존성을 설치한 다음, 환경 변수 JSONSCRAPER_TIKTOK_LICENSE_KEY를 설정하세요.

import json
import os
from datetime import datetime, timezone
from pathlib import Path

import requests

BASE_URL = "https://tiktok.evelode.com/searchVideo"
KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]


def extract_videos(payload):
    """알려진 두 가지 검색 응답 구조에서 동영상을 모읍니다."""
    tiktok = payload.get("tiktok") or {}
    videos = []

    for item in tiktok.get("aweme_list") or []:
        if isinstance(item, dict):
            videos.append(item)

    for item in tiktok.get("search_item_list") or []:
        if isinstance(item, dict):
            aweme = item.get("aweme_info")
            if isinstance(aweme, dict):
                videos.append(aweme)

    return videos


def main():
    params = {
        "license_key": KEY,
        "keyword": "제품에 관한 예시 검색어",
        "count": 20,
        "region": "US",
    }
    response = requests.get(BASE_URL, params=params, timeout=30)
    response.raise_for_status()
    payload = response.json()

    if payload.get("status") != "ok":
        raise RuntimeError("API가 ok가 아닌 외부 상태를 반환했습니다")

    tiktok = payload.get("tiktok")
    if not isinstance(tiktok, dict):
        raise RuntimeError("응답에 tiktok 객체가 없습니다")

    if tiktok.get("status_code") != 0:
        raise RuntimeError("내부 status_code가 성공 값 0이 아닙니다")

    raw_videos = extract_videos(payload)
    unique = {}
    for video in raw_videos:
        video_id = video.get("aweme_id")
        if video_id:
            unique.setdefault(str(video_id), video)

    snapshot = {
        "collected_at": datetime.now(timezone.utc).isoformat(),
        "keyword": params["keyword"],
        "status": payload.get("status"),
        "status_code": tiktok.get("status_code"),
        "raw_items": len(raw_videos),
        "unique_items": len(unique),
        "has_more": tiktok.get("has_more"),
        "cursor": tiktok.get("cursor"),
        "videos": list(unique.values()),
    }

    Path("snapshots").mkdir(exist_ok=True)
    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
    Path(f"snapshots/{stamp}.json").write_text(
        json.dumps(snapshot, ensure_ascii=False, indent=2),
        encoding="utf-8",
    )

    print({
        "status": snapshot["status"],
        "status_code": snapshot["status_code"],
        "raw_items": snapshot["raw_items"],
        "unique_items": snapshot["unique_items"],
        "has_more": snapshot["has_more"],
    })


if __name__ == "__main__":
    main()

이 스크립트는 raise_for_status()로 전송 계층을 확인한 다음, 외부 상태와 tiktok 객체의 존재 여부, 내부 status_code를 확인합니다. 그 후 두 가지 검색 구조에서 기록을 추출하고 aweme_id를 기준으로 중복을 제거한 뒤 수집 시각이 포함된 스냅샷을 저장합니다. 적합한 기록이 없어도 파일에는 실행 정보가 남으므로, 저장된 빈 결과와 보고서 자체가 없는 상황을 구분할 수 있습니다.

스냅샷을 팀을 위한 신호로 바꾸기

cron, CI 또는 워크플로 스케줄러를 사용해 스크립트를 정기적으로 실행하세요. 검색어별로 스냅샷을 따로 저장하거나 파일 이름에 검색어를 추가하세요. 상태 표에는 실행 시각, 상태, 추출된 기록 수와 고유 기록 수, has_more 플래그를 기록하면 충분합니다. 요청에서 예외가 발생하거나 응답의 필수 부분이 없거나, 추출된 기록 수가 자체 이력과 비교해 급격히 달라지면 알림을 보내는 것이 좋습니다.

이렇게 비교하면 파이프라인의 이상 징후를 발견할 수 있지만, 그 자체로 원인을 설명하지는 않습니다. 결과 수가 줄어든 것은 API나 파서의 고장이 아니라 현재 검색 결과의 구성 때문일 수 있습니다. 따라서 원본 JSON을 저장하고 동일한 매개변수를 비교하며 발견된 식별자를 확인하는 것이 좋습니다. 알림 임계값은 보편적인 숫자가 아니라 해당 검색어에 대한 관측 기록을 바탕으로 정하세요.

페이지네이션에는 응답의 cursor를 사용하고 API가 다음 결과가 없다고 알리면 탐색을 중단하세요. 실행을 재현할 수 있도록 사용한 커서와 요청 매개변수를 저장하세요. date_posted와 sort_by 매개변수로 시간 필터와 정렬을 지정할 수 있습니다. 반복 가능한 비교가 필요한 작업이라면 실행마다 이 설정을 고정하세요.

결과 해석하기

이 점검을 도입하면 팀은 세 가지 실무 질문에 검증 가능한 답을 얻을 수 있습니다. 요청이 실행되었는지, JSON의 어느 위치에 결과가 있는지, 저장된 스냅샷에 고유 동영상이 몇 개 포함되었는지 알 수 있습니다. 덕분에 빈 표가 발견된 뒤 진단까지 걸리는 시간이 줄어듭니다. 먼저 상태와 구조를 확인하고, 이어서 매개변수와 중복 여부, 원본 응답의 내용을 살펴보면 됩니다.

응답 스키마와 사용할 수 있는 필드는 기록마다 다를 수 있습니다. 2026년 10월 25일 jsonscraper 실시간 점검에서 검색 결과에는 식별자, 설명, 작성자, 통계 필드가 포함되었습니다. 다만 개별 기록에서 각 값이 제공된다고 가정해서는 안 됩니다. 실제 보고서는 수신한 데이터를 그대로 보관하며 누락된 값을 0으로 바꾸지 않습니다.

TikTok Scraper API 페이지에서 시작한 뒤, 정확한 경로와 매개변수는 공식 API 문서에서 확인할 수 있습니다. 모니터링을 시작하기 전에 이런 점검을 해두면 보고서를 관측 가능한 결과물로 만들고 품질을 진단할 수 있습니다.