ה-REST API של פריוריטי: השגיאות שגוזלות הכי הרבה זמן

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

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

מבנה הכתובת - ומה נשבר בו

הכתובת הבסיסית היא:

https://<server>/odata/Priority/<tabula.ini>/<environment>/<FORM>

שלושת המשתנים הם מקור לטעויות: tabula.ini הוא קובץ ה-tabula שבשימוש בהתקנה, ו-environment הוא השם הפנימי של החברה בפריוריטי - לא שם החברה כפי שהוא מוצג. שני אלה שונים בין לקוח ללקוח, ובין סביבת בדיקות לייצור אצל אותו לקוח.

הסקת הערכים האלה מניחוש היא בזבוז זמן. יש לבקש אותם מהאיש שמתחזק את ההתקנה.

השגיאה שמבלבלת הכי הרבה: XML מתוך API של JSON

אתה שולח JSON, מצפה ל-JSON, ומקבל בחזרה XML. שגיאות ולידציה חוזרות כאלמנט <FORM> שמכיל <InterfaceErrors>:

<InterfaceErrors>
  <text>Specify 'N' or 'Y' as the default value...</text>
</InterfaceErrors>

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

מה לעשות: לבדוק את סוג התוכן בתשובה, ואם היא אינה JSON - לחלץ את הטקסט מתוך InterfaceErrors ולתעד אותו כמות שהוא. זו ההודעה שתגיד לך בדיוק איזה שדה נדחה ולמה.

מפתחות: איפה זה נשבר

מפתח בודד ומפתח מורכב

רשומה מזוהה בסוגריים אחרי שם הישות:

GET  /FAMILY_LOG('765')
GET  /AINVOICES(IVNUM='T9696',IVTYPE='A',DEBIT='D')

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

המלכודת: PATCH לפי מפתח אוטומטי

זו כנראה השגיאה הכי מתסכלת בפרויקט ראשון. אי אפשר לעדכן רשומה לפי מפתח אוטומטי (auto-unique key). יש להשתמש במפתח הייחודי הרגיל.

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

תת-טפסים

שורות בתת-טופס נכתבות דרך ניווט מהאב:

POST  /ORDERS('SO18000002')/ORDERITEMS_SUBFORM
PATCH /ORDERS('SO18000002')/ORDERITEMS_SUBFORM(1)

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

{
  "CUSTNAME": "007",
  "ORDERITEMS_SUBFORM": [
    { "PARTNAME": "111-001", "DUEDATE": "2016-08-01T00:00:00+03:00" }
  ]
}

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

אימות: שלוש שיטות ושילוב אחד אסור

השילוב האסור: אי אפשר להשתמש ב-Basic Authentication בזמן שגישת External ID מופעלת. זה חשוב לא רק בהקמה - זה אומר שהפעלת External ID בהתקנה, מסיבה שאין לה שום קשר אליך, תשבור אינטגרציה שרצה שנה. שווה לתעד את זה מול הלקוח.

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

מגבלות שכדאי לדעת מראש

• גרסה מינימלית: ה-REST API זמין מפריוריטי 17.2 ומעלה.
• אצווה: עד 100 בקשות בקריאה אחת. בגרסאות שלפני 21.0 המגבלה הייתה 1,000. אם כתבת ייבוא שמסתמך על אצוות של 1,000 והלקוח שדרג - הוא נשבר.
• שמות שדות: אינם אינטואיטיביים ואינם זהים בין התקנות.

$metadata - הכלי שחוסך הכי הרבה זמן

נקודת הקצה /$metadata מחזירה את הסכימה המלאה של אותה התקנה: ישויות, שדות, טיפוסים וקשרים.

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

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

סדר ניפוי שגיאות שעובד

1. לוודא שהכתובת נכונה - במיוחד tabula.ini ושם הסביבה.
2. לבדוק שהמשתמש מחזיק רישיון API ורואה את הטופס בממשק.
3. למשוך $metadata ולאמת את שם הישות ואת שמות השדות.
4. לבצע GET לרשומה בודדת לפני שמנסים לכתוב.
5. אם כתיבה נכשלת - לקרוא את ה-XML. הטקסט ב-InterfaceErrors הוא כמעט תמיד ההסבר המדויק.