מתכונים — משימות נפוצות דרך MCP

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

מתכון 0 · פתיחת הסשן

כל מתכון כאן מתחיל באותם שני צעדים. הם לא טקס — הם מה שמונע את רוב הטעויות.

1. Usage-Guide                    ← בלי פרמטרים. פעם אחת בסשן.
2. Get-Schema { className: "…" }  ← לפני כל נגיעה בטבלה שלא עבדתם עליה בסשן הזה.

Usage-Guide הוא הכלי שהשרת עצמו מורה להתחיל ממנו. הוא מחזיר אובייקט עם שני מפתחות, About Us ו‑How to use, ובשני: מפת טבלאות המערכת (Accounts, _User, _Timeline), כללי מודל הדפים (apps/mybusiness/…, masterPage, rDivider/sDivider), שני מבני התנאים (field/equesition/value ו‑F/C/T/V/P), פעולות כללי הטופס, תחביר ה‑placeholders {{{Name}}} כולל format(date,he-IL,Asia/Jerusalem), והמשאב get-file.

נתקלתם ב‑fieldName כמפתח חובה? הוא אינו נדרש עוד

בגרסאות שרת ישנות סכימת כלי הנתונים סימנה fieldName כמפתח חובה ב‑where וב‑data, ולכן דוגמאות מאותה תקופה נושאות "fieldName": null. בשרת עדכני הסכימה עברה ל‑propertyNames + additionalProperties, וה‑where וה‑data נשלחים שטוחים — כמו בכל הדוגמאות כאן. הפירוט: כלי נתונים.

Get-Schema הוא הכלל הראשון של הפלטפורמה:

למה בלי Get-Schema הקוד “עובד” ומחזיר זבל

סכימת Accounts שונה בין לקוח ללקוח. שדות מותאמים, שדות שהוסרו, שדות ששמם שונה בפרויקט מסוים. וטבלאות ה‑lookup מחזיקות objectId‑ים שנוצרו במערכת הספציפית הזו — הסטטוס “חדש” הוא מזהה אחר בכל מערכת.

הכתיבה לא נכשלת כשהשם שגוי. היא מחזירה 200, השדה שהתכוונתם אליו נשאר ריק, וכשהרשאת addField של הטבלה פתוחה (תלוי בקונפיגורציית המערכת), הערך נשמר בעמודה חדשה שנוצרת בשקט בסכימה. ראו סכימות ו‑סוגי נתונים.

JSON

{ "className": "Accounts" }

לרשימת שמות הטבלאות בלבד — { "tablesNameOnly": true } בלי className.

---

מתכון 1 · כמה לידים נכנסו החודש

השאלה הכי נפוצה, והתשובה הכי קל לטעות בה.

ליד במערכת הוא שורה ב‑Accounts עם IsAccount: false. לקוח הוא אותה טבלה עם true. זו לא שתי טבלאות — זו טבלה אחת עם דגל.

הדרך הנכונה

JSON

// Count-Data
{ "table": "Accounts",
  "where": {
    "IsAccount": false,
    "createdAt": { "$gte": { "__type": "Date", "iso": "2026-08-01T00:00:00.000Z" } }
  } }

תשובה אחת — {"count":361} — בלי תלות ב‑limit.

הדרך שנראית נכונה ואינה

JSON

// Get-Data — ואז לספור את השורות שחזרו ✗
{ "table": "Accounts", "where": { "IsAccount": false } }

מחזיר 5 שורות, תמיד

limit ב‑Get-Data הוא 5 כברירת מחדל (אותה שאילתה שספרה 361 מחזירה 5 שורות). ספירת השורות שחזרו תיתן “5 לידים החודש” בכל מערכת ובכל חודש.

זו לא שגיאה שמתפוצצת — היא מדווחת בביטחון מספר שגוי. מודל שפה יציג אותה כעובדה. כששואלים “כמה” — Count-Data, נקודה.

פילוח לפי סטטוס

JSON

// Aggregate-Data
{ "table": "Accounts",
  "where": {
    "IsAccount": false,
    "createdAt": { "$gte": { "__type": "Date", "iso": "2026-08-01T00:00:00.000Z" } }
  },
  "group":   { "count": { "sum": 1 } },
  "groupby": "LeadStatusId.LeadStatuses.Name",
  "order":   "-count" }

{"count":{"sum":1}} הוא איך כותבים “ספירה” — אין פונקציית count נפרדת. ה‑groupby עובר דרך ה‑Pointer אל שם הסטטוס, לא אל המזהה שלו. התשובה: {"results":[{"count":353},{"_id":"ליד חדש","count":8}]} — שימו לב לשורה בלי _id: אלה הרשומות שבהן ה‑Pointer ריק. היא תופיע בכל קיבוץ לפי Pointer, וכדאי לתת לה שם בדוח.

אמתו את שם טבלת ה‑lookup

LeadStatuses הוא השם המקובל, ולא בהכרח השם במערכת שלכם. Get-Schema { className: "Accounts" } מראה את ה‑targetClass האמיתי של LeadStatusId — קחו אותו משם ולא מכאן.

כשצריך גם את השורות עצמן — Get-Data עם limit מפורש, keys כדי לא לגרור שדות מיותרים, ו‑order:

JSON

{ "table": "Accounts",
  "where": { "IsAccount": false,
             "createdAt": { "$gte": { "__type": "Date", "iso": "2026-08-01T00:00:00.000Z" } } },
  "keys": ["Name", "PhoneNumber", "Email", "LeadStatusId", "createdAt"],
  "order": "-createdAt",
  "limit": 500 }

---

מתכון 2 · הכנסות לפי בעלים

הדוגמה הקלאסית שבה מסלול ה‑Pointer של Aggregate-Data מרוויח את מקומו.

JSON

// 1. לוודא שמות שדות
{ "className": "Sales" }

// 2. Aggregate-Data
{ "table": "Sales",
  "where": {
    "SaleStatusId": { "__type": "Pointer", "className": "SaleStatuses", "objectId": "zrP1MSVBoq" },
    "ClosingDate": { "$gte": { "__type": "Date", "iso": "2026-01-01T00:00:00.000Z" } }
  },
  "group":   { "total": { "sum": "Total" } },
  "groupby": "OwnerId._User.name",
  "order":   "-total",
  "limit":   10 }

תוצאה: עשרת אנשי המכירות המובילים, עם השמות שלהם, בקריאה אחת — {"results":[{"_id":"דנה לוי","total":14850}, …]}.

אין IsWon ב‑Sales

במערכת vanilla אין ל‑Sales שדות IsWon / IsLost — “זכייה” היא ערך של SaleStatusId (למשל הסטטוס “הושלמה”), והמזהה שלו שונה בכל מערכת. שאילתה על IsWon: true לא נכשלת: היא מחזירה {"results":[]} בשקט. זה בדיוק מה ששלב 1 (Get-Schema) נועד לתפוס.

מבנה מסלול ה‑Pointer

OwnerId . _User . name
   ↑        ↑       ↑
   שדה   מחלקת   השדה
 בטבלה   היעד    שאותו
 המקור            מציגים

שם המחלקה באמצע. דוגמאות נוספות: SaleStatusId.SaleStatuses.Name, AccountId.Accounts.Name. שדות של _User הם באותיות קטנות — name, email — בניגוד למוסכמה בשאר הטבלאות.

ב‑REST זה עובד באותה צורה — בנתיב הנכון

הנתיב הפעיל לאגרגציה הוא /parse/classes-aggregate/ (הגנרי /parse/aggregate/ מחזיר 404 בפריסה הזו), והוא כן מבין את הדוט‑נוטציה דרך Pointer: groupby=SaleStatusId.SaleStatuses.Name מחזיר את שמות הסטטוסים בקריאה אחת, בלי שליפה שנייה לתרגום objectId‑ים. השוואה מלאה.

קיבוץ לפי חודש

JSON

{ "table": "Sales",
  "where": { "SaleStatusId": { "__type": "Pointer", "className": "SaleStatuses", "objectId": "zrP1MSVBoq" } },
  "group":   { "total": { "sum": "Total" } },
  "groupby": { "month": { "mm": "ClosingDate" } },
  "timeZone": "Asia/Jerusalem" }

התשובה: {"results":[{"_id":{"month":1},"total":1500}, …, {"_id":{"month":""},"total":11106}]} — השורה עם month: "" היא המכירות בלי ClosingDate. היא תמיד שם; תנו לה שם או סננו אותה ב‑where.

חלקי תאריך אפשריים: hour, dow, q, q/yy, mm, mm/yy, yy.

מגבלה ידועה — m/yy שבסכימה נדחה

תיאור הסכימה מונה m/yy, אבל השרת מחזיר עליו Error: Invalid parameter for groupby date: [object Object]. האסימון שעובד הוא mm/yy ⇒ {"_id":{"p":{"yy":2026,"mm":3}}}.

timeZone אינו קישוט: בלעדיו החישוב רץ באזור הזמן של השרת, ומכירה שנסגרה ב‑1 בחודש בשעה 01:00 בישראל עלולה ליפול לחודש הקודם.

groupby כאובייקט — עובד

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

כמה מדדים בקריאה אחת — עובד, למרות הסכימה. תיאור group אומר “Only one property is allowed”, אבל בפועל: "group": { "total": { "sum": "Total" }, "cnt": { "sum": 1 } } מחזיר את שני המדדים בכל שורה. מאחר שהסכימה מצהירה אחרת, ודאו שכל התוויות חוזרות אם אתם מסתמכים על זה.

---

מתכון 3 · יבוא מרוכז בלי סופת טריגרים

זה המתכון שהכי כדאי לקרוא לפני ולא אחרי.

יבוא מפעיל אוטומציות כברירת מחדל

כתיבה דרך ה‑API מפעילה טריגרים בדיוק כמו הקלדה בממשק.

5,000 שורות = 5,000 הפעלות של כל טריגר יצירה על הטבלה. אם אחד מהם שולח מייל — 5,000 מיילים יצאו ללקוחות אמיתיים, ואי אפשר להחזיר אותם.

הרצף המלא

JSON

// 1. מה בכלל ירוץ כאן?
{ "tableName": "Accounts" }          // Get-Triggers

// 2. הסכימה, כדי לדעת מה מותר לשלוח
{ "className": "Accounts" }          // Get-Schema

// 3. פתרון ערכי lookup לפני, לא תוך כדי
{ "table": "LeadStatuses", "where": { "Name": "ליד חדש" }, "limit": 1 }
{ "table": "LeadSource",   "where": { "Name": "אתר" }, "limit": 1 }

// 4. הטעינה — באצוות
{ "table": "Accounts",
  "skipTriggers": true,
  "skipTimeline": false,
  "data": [
    { "Name": "לקוח א'", "PhoneNumber": "0501234567", "IsAccount": false,
      "LeadStatusId": { "__type": "Pointer", "className": "LeadStatuses", "objectId": "e9TwcETDGq" } },
    { "Name": "לקוח ב'", "PhoneNumber": "0507654321", "IsAccount": false,
      "LeadStatusId": { "__type": "Pointer", "className": "LeadStatuses", "objectId": "e9TwcETDGq" } }
  ] }

// 5. אימות
{ "table": "Accounts", "where": { "IsAccount": false, "…": "…" } }   // Count-Data

התשובה של Create-Many היא מערך באורך הקלט, פריט לכל רשומה: [{"success":{"objectId":"S0bkiLAr0y","createdAt":"…"}},{"success":{…}}]. שמות טבלאות ה‑lookup כאן — LeadStatuses, LeadSource — ומזהי הסטטוסים הם של סביבת בדיקה; קחו את שלכם מ‑Get-Schema ומשליפה.

בטריגרים שמגיעים עם מערכת vanilla על Accounts (“Lead Conversion Date”, “Account Lead Status” — שניהם על IsAccount: true): עם skipTriggers: true הרשומות נוצרות בלי LeadConversionDate ועם הסטטוס שנשלח; בלעדיו הטריגר רץ, ממלא LeadConversionDate ומחליף את LeadStatusId ל“לקוח”.

שלוש החלטות שחייבות להיסגר מראש

ההחלטה	האפשרויות
טריגרים	skipTriggers: true — ואז אתם ממלאים את מה שהטריגר היה ממלא (חותמות זמן, רשומות בת) · או לתת להם לרוץ במודע, אחרי שניטרלתם את פעולות ההתראה לזמן היבוא
ציר הזמן	skipTimeline: true מהיר יותר, ומוחק את היכולת להוכיח מה נטען ומתי. ביבוא נתונים ראשוני לרוב משאירים אותו דלוק — יומנים וראיות
גודל אצווה	לא נמצאה תקרה קשיחה (120 רשומות בקריאה אחת עברו כולן success; גם ב‑REST batch התקרה אינה נאכפת). עבדו באצוות של עשרות עד מאות, בלולאה סדרתית — גוף בקשה גדול מדי נופל על HTTP 413, לא על שגיאת כלי

שני הדגלים נכבדים רק באימות Master Key

כך כתוב בסכימה במפורש (“This option is only honored when the request is authenticated using the master key”). בחיבור התחברות משתמש (OAuth) הדגלים מתעלמים בשקט — הבקשה מצליחה, הטריגרים רצים, וההודעות יוצאות.

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

סדר התשובה = סדר הקלט

Create-Many מחזיר את המזהים בסדר שבו שלחתם את הרשומות (data[0] ⇒ [0].success.objectId). זה מה שמאפשר טעינה דו‑שלבית — לידים ואז המכירות שלהם — לפי מיקום:

data[0] → objectId[0] → הליד של שורה 0 בקובץ
data[1] → objectId[1] → הליד של שורה 1
…
ואז: Create-Many על Sales, עם Pointer ל-objectId המתאים לכל שורה

לפני שמתחילים

• נקו כפילויות במקור. אין Delete-Data — שורה כפולה שנטענה נשארת עד שמישהו ימחק אותה בממשק או ב‑REST עם Master Key.
• נרמלו טלפונים. מספרים ישראליים מגיעים בעשרות פורמטים; החליטו על אחד לפני הטעינה, לא אחריה.
• בדקו על 2 שורות קודם. אצווה קטנה, Get-Data על מה שנוצר, ורק אז השאר.

---

מתכון 4 · מצא‑או‑צור, ואז רשומה מקושרת

הזרימה הקנונית של כל אינטגרציה: לוודא שיש איש קשר, ואז לתלות עליו משהו — מכירה, פנייה, משימה, הרשמה.

Get-Schema → חיפוש → קיים? השתמש : צור → צור רשומה מקושרת עם Pointer → אמת

שלב 1 · חיפוש

JSON

// Get-Data
{ "table": "Accounts",
  "where": { "PhoneNumber": "0501234567" },
  "keys": ["Name", "PhoneNumber", "Email", "IsAccount"],
  "limit": 5 }

שם השדה משתנה בין מערכות

PhoneNumber הוא המוסכמה במוצר, אבל יש מערכות שבהן השדה נקרא אחרת. Get-Schema נותן את השם האמיתי — קחו אותו משם.

limit: 5 ולא 1 בכוונה: אתם רוצים לדעת שיש שלוש התאמות, לא לתפוס בשקט את הראשונה.

טלפון ישראלי מופיע בפורמטים שונים באותה מערכת — 0501234567, +972501234567, 050-123-4567. השוואה מדויקת על ערך אחד תפספס. אם ההתאמה חשובה, חפשו לפי אימייל, או הריצו כמה שאילתות על הווריאציות. הדפוס שהמוצר עצמו מיישם בקליטת טפסים מתואר בזיהוי כפילויות.

שלב 2 · יצירה אם אין

JSON

// Create-Data
{ "table": "Accounts",
  "data": {
    "Name": "דנה כהן",
    "PhoneNumber": "0501234567",
    "Email": "dana@example.co.il",
    "IsAccount": false
  } }

התשובה — { "objectId": "ajBZIKKbyU", "createdAt": "…" } — זה מה שמחזיקים לשלב הבא.

שלב 3 · הרשומה המקושרת

JSON

// Create-Data
{ "table": "Sales",
  "data": {
    "Name": "הצעה — אתר תדמית",
    "AccountId":    { "__type": "Pointer", "className": "Accounts",     "objectId": "xK9mP2qRsT" },
    "OwnerId":      { "__type": "Pointer", "className": "_User",        "objectId": "2b0QVKoigE" },
    "SaleStatusId": { "__type": "Pointer", "className": "SaleStatuses", "objectId": "zrP1MSVBoq" },
    "Total": 18500,
    "ClosingDate": { "__type": "Date", "iso": "2026-09-30T00:00:00.000Z" }
  } }

Pointer הוא אובייקט, ותאריך הוא אובייקט

ב‑MCP הטעות הזו רועשת — וזה החדשות הטובות:

JSON

"AccountId": "xK9mP2qRsT"                                              ✗ Error: schema mismatch for Sales.AccountId; expected Pointer<Accounts> but got String
"AccountId": { "__type": "Pointer", "className": "Accounts",
               "objectId": "xK9mP2qRsT" }                              ✓

"ClosingDate": "2026-09-30"                                            ✗ Error: schema mismatch for Sales.ClosingDate; expected Date but got String
"ClosingDate": { "__type": "Date", "iso": "2026-09-30T00:00:00.000Z" } ✓

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

מזהי הסטטוס (SaleStatusId, LeadStatusId וכו’) אינם קבועים בין מערכות. שולפים אותם פעם אחת בתחילת הסשן ומחזיקים מפה בזיכרון:

JSON

{ "table": "SaleStatuses", "keys": ["Name"], "limit": 100 }
// ⇒ [{"objectId":"E9cYlAlooc","Name":"חדש"}, {"objectId":"zrP1MSVBoq","Name":"הושלמה"}, …]

שלב 4 · אימות

JSON

// Get-Data על מה שנוצר, עם ה-Pointer
{ "table": "Sales",
  "where": { "AccountId": { "__type": "Pointer", "className": "Accounts", "objectId": "xK9mP2qRsT" } },
  "keys": ["Name", "Total", "SaleStatusId", "createdAt"],
  "order": "-createdAt",
  "limit": 5 }

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

---

מה לבדוק לפני שסוגרים משימה

הבדיקה	למה
Get-Schema רץ על כל טבלה שנגעתם בה	שם שדה שגוי לא מייצר שגיאה
כל Get-Data נושא limit מפורש	ברירת המחדל 5
שאלות “כמה” נענו ב‑Count-Data	ספירת שורות שחזרו היא ספירה של ה‑limit
כל Pointer וכל תאריך עטופים באובייקט	אחרת schema mismatch — ושם שדה שגוי יוצר עמודה בשקט
מזהי lookup נשלפו מהמערכת הזו	הם שונים בכל מערכת
Get-Triggers רץ לפני כל כתיבה המונית	סופת אוטומציות היא בלתי הפיכה
הרשומות שנוצרו נשלפו בחזרה	“הצליח” אינו “נשמר נכון”

המשך

• כלי נתונים — הפרמטרים המלאים
• כלי טריגרים ואוטומציות — מה ירוץ כשתכתבו
• סוכן במצב קריאה בלבד — לתכנן עכשיו, לבצע בהמשך
• אינדקס הכלים המלא
• מודל הנתונים ומוסכמות · סוגי נתונים · מפת הטבלאות