בדקו את פרופיל IG מול בריף הקמפיין לפני ההשקה: אימות באמצעות API

לפני השקת קמפיין אפשר להשוות אוטומטית רשימת חשבונות IG לבריף ולהפיק CSV עם הרשומות שדורשות תשומת לב בלבד. עבור כל שורה הסקריפט יבקש נתוני פרופיל, ישווה את שם המשתמש, את הגדרות הפרטיות ואת סטטוס האימות לערכים הצפויים, וישמור גם את המונים הזמינים. כך הופכת בדיקה ידנית שחוזרת על עצמה לשלב בקרה ברור לפני העברת הקמפיין לביצוע.

המשימה: לזהות פערים לפני הפרסום

בטבלת קמפיין מופיעים בדרך כלל שם החשבון וכמה ציפיות: הפרופיל צריך להיות ציבורי, שם המשתמש צריך להתאים לשם שאושר, וסימון האימות צריך להתאים לרישום שבבריף. בין הכנת הרשימה להשקה, חשבון עשוי לשנות את שמו, להפוך לפרטי או להתגלות כפרופיל אחר בעל שם דומה. כשבודקים את השורות ידנית, קשה לשחזר את התהליך ולבודד במהירות חריגים.

לצורך אבחון מקדים כזה, די לקבל פרופיל לפי שם משתמש. בתיעוד שפורסם של jsonscraper מצוין הנתיב GET /v1/user/by/username עם הפרמטר username; יש גם פרמטר אופציונלי בשם cache_timeout. התשובה עשויה לכלול שם משתמש, שם מלא, סימוני private ו-verified, מספר פוסטים, עוקבים ונעקבים, וכן ביוגרפיה. יש לקרוא את השדות מהתשובה בפועל: תמונת מצב של הסכמה מאשרת שהם הופיעו בתשובה שנצפתה, אך הערכים עשויים להשתנות או לא להופיע.

הכינו טבלה וכללי בדיקה

צרו קובץ CSV בשם profiles.csv עם העמודות username, expected_private ו-expected_verified. בשתי העמודות האחרונות הזינו את הערכים הצפויים true או false, ואת שם המשתמש כתבו בלי התו @. אם הציפייה לגבי פרופיל מסוים אינה ידועה, השאירו את התא ריק: הסקריפט לא אמור להתייחס להיעדר ציפייה כשגיאה.

username,expected_private,expected_verified
examplebrand,false,true
anotheraccount,false,false

כאן הבדיקה מטפלת בשתי משימות ממוקדות: היא קובעת אם שם המשתמש שהתקבל תואם לזה שהתבקש, ומזהה הבדלים מהציפיות המתועדות לגבי פרטיות ואימות. המונים והביוגרפיה נשמרים לצורך הקשר והערכה ידנית, ולא נחשבים הוכחה לאיכות הקהל או להתאמת היוצר לקמפיין.

התחברו ל-IG Scraper API

שמרו את מפתח הגישה במשתנה הסביבה JSONSCRAPER_INSTAGRAM_LICENSE_KEY. אל תכתבו את הסוד בקובץ CSV, בקוד המקור או ביומני הרצה. התיעוד הרשמי של endpoint IG מתאר את הנתיב ואת שמות הפרמטרים; כתובת הבסיס של ה-API היא https://ig.jsonscraper.com, ושם הפרמטר למפתח הוא license_key.

לפני עיבוד הרשימה המלאה, בצעו קריאת ניסיון אחת עבור שורת בדיקה, בדקו את מבנה ה-JSON וודאו שלחשבון שלכם יש גישה. מאחר שה-endpoint מקבל שם משתמש, אין צורך במזהה פרופיל ידוע או בנתיבים נוספים עבור התרחיש הפשוט הזה.

דוגמה: בקשות, השוואה ו-CSV של חריגים

הסקריפט הבא תואם ל-Python 3.8 ומעלה. הוא קורא קובץ CSV, מבצע בקשת GET אחת לכל פרופיל, בודק את סטטוס התגובה החיצוני ושומר את השדות הרלוונטיים המקוריים לצד תוצאת ההשוואה. התקינו את התלות באמצעות הפקודה python -m pip install requests, ואז הגדירו את המפתח לפני ההרצה.

import csv
import os
import time
from pathlib import Path

import requests

BASE_URL = "https://ig.jsonscraper.com/v1/user/by/username"
API_KEY = os.environ["JSONSCRAPER_INSTAGRAM_LICENSE_KEY"]
INPUT_FILE = Path("profiles.csv")
OUTPUT_FILE = Path("preflight_results.csv")


def parse_expected(value):
    value = (value or "").strip().lower()
    if value == "true":
        return True
    if value == "false":
        return False
    return None


def profile_from_response(payload):
    # The documented observed response wraps profile fields in "ig".
    if payload.get("status") != "ok":
        raise ValueError("API response status is not ok")
    profile = payload.get("ig")
    if not isinstance(profile, dict):
        raise ValueError("Response has no profile object under 'ig'")
    return profile


with INPUT_FILE.open(newline="", encoding="utf-8") as source:
    rows = list(csv.DictReader(source))

results = []
for row in rows:
    requested = (row.get("username") or "").strip().lstrip("@")
    if not requested:
        results.append({
            "requested_username": "",
            "result": "missing_username",
            "error": "username is empty",
        })
        continue

    try:
        response = requests.get(
            BASE_URL,
            params={"username": requested, "license_key": API_KEY},
            timeout=30,
        )
        response.raise_for_status()
        profile = profile_from_response(response.json())

        actual_username = profile.get("username")
        actual_private = profile.get("is_private")
        actual_verified = profile.get("is_verified")
        expected_private = parse_expected(row.get("expected_private"))
        expected_verified = parse_expected(row.get("expected_verified"))

        checks = []
        if actual_username and actual_username.casefold() != requested.casefold():
            checks.append("username_mismatch")
        if expected_private is not None and actual_private != expected_private:
            checks.append("privacy_mismatch")
        if expected_verified is not None and actual_verified != expected_verified:
            checks.append("verification_mismatch")

        results.append({
            "requested_username": requested,
            "username": actual_username,
            "full_name": profile.get("full_name"),
            "is_private": actual_private,
            "is_verified": actual_verified,
            "media_count": profile.get("media_count"),
            "follower_count": profile.get("follower_count"),
            "following_count": profile.get("following_count"),
            "result": "review" if checks else "matched",
            "checks": ";".join(checks),
            "error": "",
        })
    except (requests.RequestException, ValueError, KeyError) as exc:
        results.append({
            "requested_username": requested,
            "result": "request_or_response_error",
            "error": str(exc),
        })

    # A small delay spaces requests; it is not a documented quota guarantee.
    time.sleep(0.5)

fieldnames = sorted({key for item in results for key in item})
with OUTPUT_FILE.open("w", newline="", encoding="utf-8") as destination:
    writer = csv.DictWriter(destination, fieldnames=fieldnames)
    writer.writeheader()
    writer.writerows(results)

print("Saved", len(results), "rows to", OUTPUT_FILE)

הקוד בודק את מעטפת התשובה שנצפתה: status חיצוני ואובייקט הפרופיל ig. אם הספק ישנה את הפורמט, בדיקת המבנה תעצור את העיבוד של הרשומה הספציפית ותשמור שגיאה, במקום ליצור בשקט התאמה שגויה. הסקריפט לא מדפיס את המפתח ולא מוסיף אותו לקובץ התוצאה.

איך לקרוא את התוצאה

בקובץ preflight_results.csv, שורות עם הסטטוס matched עברו את ההשוואות שהוגדרו. הערך review פירושו שפרמטר אחד או יותר שונים מהבריף; העמודה checks מציינת אילו מהם. שגיאת בקשה או תשובה מסומנת בנפרד, כך שזמינות נתונים אינה נראית כהתאמה מאושרת.

מספר העוקבים והפוסטים עוזר לאדם לראות תמונת מצב עדכנית של הפרופיל לצד הבקשה. אלה ערכים רגעיים מהתשובה לבקשה. כדי להעריך שינויים לאורך זמן, שמרו הרצות נפרדות עם תאריך; בדיקה יחידה אינה כוללת היסטוריה. שדות עשויים להיות ריקים, ובמקרה כזה הרשומה עדיין מתאימה לבדיקת זהות ולבדיקת מאפיינים זמינים אחרים, אך לא להשוואה של מונה חסר.

אוטומציה לפני השקת הקמפיין

לאחר בדיקה ידנית של קובץ CSV לניסיון, הוסיפו את הסקריפט ללוח זמנים או לשלב ההכנה של הקמפיין. כדי לאפשר בקרה שניתנת לשחזור, שמרו את הרשימה המקורית בנפרד, תעדו את תאריך ההרצה ושמרו את קובץ ה-CSV של התוצאות באחסון עבודה מוגן. לעיבוד חוזר, כדאי להשתמש במזהה שורה יציב מהמערכת שלכם, אם שם המשתמש עשוי להשתנות.

כשהרשימה גדלה, הוסיפו הגבלת מקביליות, ניסיונות חוזרים רק עבור שגיאות רשת זמניות ויומן נפרד של קודי שגיאה ללא סודות. אל תבצעו ניסיונות חוזרים ללא הגבלה במקרה של מפתח שגוי או שם משתמש לא תקין. אפשר להוסיף את הערך cache_timeout רק בהתאם למדיניות העדכניות הנדרשת: לפי התיעוד, שמירה במטמון עבור IG מושבתת כברירת מחדל, וערך גדול מאפס מפעיל שמירה במטמון למשך פרק הזמן שנקבע.

בדיקת הפרופילים מצמצמת את ההשוואה הידנית לרשימה ממוקדת של חריגים: שם, פרטיות, אימות והמונים זמינים מופיעים בטבלה אחת לפני תחילת הקמפיין. לפרמטרים של ה-API ולאפשרויות האינטגרציה העדכניות, עיינו בדף IG Scraper API ובתיעוד הנתיבים.