מתכונים — משימות נפוצות דרך 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 (mcp-data-01) אינו נדרש עוד

עד 23.08.2026 סכימת כלי הנתונים סימנה fieldName כמפתח חובה ב‑where וב‑data, וכל הדוגמאות כאן נשאו "fieldName": null. השרת עודכן באותו יום (tools/list מ‑19:12 שעון ישראל: propertyNames + additionalProperties), והדוגמאות בעמוד עודכנו ל‑where/data שטוחים. הפירוט וההיסטוריה: כלי נתונים.

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

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

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

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

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 שבסכימה נדחה (mcp-data-03)

תיאור הסכימה מונה 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 התקרה אינה נאכפת — core-api-03). עבדו באצוות של עשרות עד מאות, בלולאה סדרתית — גוף בקשה גדול מדי נופל על HTTP 413, לא על שגיאת כלי

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

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

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

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

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

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

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

• נקו כפילויות במקור. אין Delete-Data (mcp-data-08) — שורה כפולה שנטענה נשארת עד שמישהו ימחק אותה בממשק או ב‑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 של הטבלה פתוחה הוא יוצר עמודה חדשה בשקט (mcp-data-06). ובשכבת טפסי 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 רץ לפני כל כתיבה המונית	סופת אוטומציות היא בלתי הפיכה
הרשומות שנוצרו נשלפו בחזרה	“הצליח” אינו “נשמר נכון”

המשך

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