Cloudflare עדכנה את ה־introspection של SQL API: איך לזהות שדות JSON בלי לנחש

אם הסכמה של מערך נתונים אנליטי כוללת עמודת JSON בשם attributes, אך המפתחות שלה תלויים בנתוני החשבון, Cloudflare מאפשרת כעת לגלות אותם באמצעות introspection. העדכון מ־27 באוקטובר 2026 הוסיף את הפרמטר include_attributes=true: התשובה מפרטת את המפתחות והסוגים שנמצאו בנתוני החשבון בשבעת הימים שקדמו לבקשה.

למפתחים, השינוי פותר בעיה מעשית: לפני יצירת מסנן אפשר לבדוק אילו שדות אכן מופיעים במערך הנתונים שנבחר. השמות הישנים include_custom_attributes ו־custom_attributes עדיין פועלים, אך Cloudflare סימנה אותם כמוצאים משימוש. מומלץ לבנות אינטגרציות חדשות על בסיס עדכון ה־introspection של SQL API.

מה בדיוק מחזיר ה־introspection

חלק ממערכי הנתונים של Cloudflare Analytics שומרים זוגות נוספים של מפתח וערך בעמודה attributes. באמצעות הפרמטר החדש, ה־introspection מזהה מפתחות ואת סוגיהם על סמך נתונים משבעת הימים האחרונים ומחזיר את הפרטים בשדה attributes של אובייקט מערך הנתונים. זו סכימה שהוסקה מרשומות החשבון האחרונות, והיא מסייעת להכין שאילתת SQL.

בדוגמה הרשמית של Cloudflare נעשה שימוש בנתיב /client/v4/analytics/sql/introspection, מועברים מזהה החשבון ושם המערך events.httpRequests, ומופעל גילוי המאפיינים:

curl --get "https://api.cloudflare.com/client/v4/analytics/sql/introspection" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --data-urlencode "account_tag=$CLOUDFLARE_ACCOUNT_TAG" \
  --data-urlencode "dataset_name=events.httpRequests" \
  --data-urlencode "include_attributes=true"

לפני ההרצה, הגדירו בסביבה את המשתנים CLOUDFLARE_API_TOKEN ו־CLOUDFLARE_ACCOUNT_TAG. האסימון מועבר כאמצעי אימות מסוג bearer; שמות המשתנים בדוגמה הם הגדרות מקומיות של הפקודה, ולא פרמטרים נפרדים של Cloudflare.

ממפתח שאותר לשאילתה

לאחר ה־introspection, בדקו את השדה attributes בתיאור של המערך הרלוונטי ובחרו מפתח שמופיע בו בפועל. Cloudflare מציגה דוגמה לגישה מדויקת למפתח בעמודת JSON: attributes['http.method']. השתמשו במסנן בשם שאותר, ולא בשם משוער על סמך סוג האירוע.

תהליך העבודה המעשי נראה כך:

1. שלחו בקשת introspection למערך הנתונים הרצוי עם include_attributes=true.
2. שמרו את המפתחות והסוגים מהשדה המוחזר attributes, לצד תאריך הבדיקה.
3. בנו את השאילתה באמצעות שם המפתח המדויק, למשל attributes['http.method'].
4. בדקו את השאילתה בנתוני החשבון שלכם וחזרו על הגילוי כאשר הסכמה או אופי האירועים הנכנסים משתנים.

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

איך לעבור מהשמות הישנים

בקוד קיים, החליפו את פרמטר השאילתה include_custom_attributes ב־include_attributes, ושנו את הטיפול בשדה התשובה מ־custom_attributes לקריאה של attributes. לפי Cloudflare, השמות הקודמים עדיין פועלים, ולכן אפשר לבצע את ההעברה בנפרד מתיקון דחוף של האינטגרציה.

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

השורה התחתונה לצינורות נתוני אנליטיקה

include_attributes=true מאפשר לגלות שדות JSON דינמיים באמצעות מנגנון ה־introspection הרשמי, ומספק למפתחים סוגים לצד שמות המפתחות. העבירו שאילתות ומנתחי תשובות חדשים ל־include_attributes ולשדה התשובה attributes, שמרו את תאריך הגילוי ובנו מסננים לפי מפתחות שאותרו בפועל.