מתכונים — משימות נפוצות דרך 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.

בלי 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 · הכנסות לפי בעלים

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 נועד לתפוס.

מבנה מסלול ה‑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 עטוף נזרק בשקט. טבלת ההמרה המלאה: סוגי נתונים.

מזהי הסטטוס (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 לרשומה הלא נכונה, או טריגר ששינה את מה שכתבתם — אף אחד מאלה אינו מייצר שגיאה.

המשך

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