קוד הסטטוס בפריוריטי מפריד בין שלוש תקלות שונות: בקשה שגויה, הרשאה או רישוי חסר, ונתון שלא קיים. איך מצמצמים שאילתה עד שהאשם מתגלה, ומה שומרים בכל ניסיון.
עיקרי הדברים
- קוד הסטטוס מפריד בין שלוש בעיות שדורשות שלושה תיקונים שונים: תחביר, הרשאה או רישוי, ונתון שאינו קיים.
- מגרסה 19.1 שגיאות ה-REST API של פריוריטי מוחזרות ב-JSON במקום ב-XML. אם אתם עדיין מנתחים XML, זו התקלה.
- 404 בפריוריטי הוא דו-משמעי בכוונה: או שהטופס אינו חשוף, או שהרשומה עצמה אינה קיימת.
- הדרך היחידה שעובדת היא צמצום: רשומה אחת, שדה אחד, בלי פילטר. ואז מוסיפים רכיב אחד בכל פעם.
- שאילתה שעובדת מהדפדפן שלכם ונכשלת מהאינטגרציה היא כמעט תמיד משתמש אחר, חברה אחרת, או רישוי.
"ה-API של פריוריטי מחזיר שגיאה" אינו אבחון. פריוריטי מחזירה קודי סטטוס HTTP סטנדרטיים - 400 לבקשה שגויה, 404 לטופס או רשומה שלא נמצאו, 409 להתנגשות, 429 לחריגה מקצב, 500 לצד השרת - ומגרסה 19.1 גוף השגיאה חוזר כ-JSON. הקוד קובע לאיזו שכבה להסתכל.
שלוש השכבות שמתחבאות מאחורי המילה "שגיאה"
בקשת OData לפריוריטי עוברת שלוש שכבות עצמאיות לפני שהיא מחזירה נתון, וכל אחת נכשלת אחרת:
- פרוטוקול ותחביר. הכתובת, שם הישות, מבנה ה-
$filter, סוגי הערכים. כאן נופלים 400. - זהות, הרשאה ורישוי. מי המשתמש, האם יש לו גישה לטופס, ואם קיים רישיון API. כאן נופלים 401 ו-403, ולעיתים גם 404.
- נתונים עסקיים. התחביר תקין, ההרשאה קיימת, ופשוט אין רשומה שעונה על התנאי.
הבלבול נובע מכך שכל שלוש השכבות מוחזרות דרך אותו ערוץ. בלי לרשום את הקוד ואת גוף התשובה, השלוש נראות זהות ביומן.
מה כל קוד סטטוס אומר לכם לבדוק
| קוד | מה קרה | איפה לחפש קודם |
|---|---|---|
| 400 | הבקשה לא תקינה | תחביר ה-$filter, שם השדה, סוג הערך, מרכאות |
| 401 | לא זוהה | שיטת האימות, טוקן גישה אישי, סיסמה שהוחלפה |
| 403 | זוהה ולא מורשה | הרשאות המשתמש לטופס, רישוי API, סוג הפעולה |
| 404 | לא נמצא | שם הישות, האם הטופס חשוף ל-API, או שהרשומה אינה קיימת |
| 409 | התנגשות | POST על רשומה שכבר קיימת עם אותו מפתח |
| 429 | חריגה מקצב | תדירות הקריאות, ריצה מקבילה של כמה תהליכים |
| 500 | תקלה בצד השרת | זמינות השרת, ואז פנייה לתמיכה עם התיעוד המלא |
איך מצמצמים פילטר לא תקין לסעיף אחד?
בשיטה אחת שעובדת תמיד: מורידים הכול ומחזירים רכיב אחד בכל פעם.
- הריצו קריאה על הישות בלי
$filter, בלי$selectובלי הרחבה, והגבילו לרשומה אחת. אם גם זה נכשל, הבעיה אינה בשאילתה אלא בגישה לישות. - הוסיפו
$selectעל שדה אחד בלבד. אם נשבר כאן, שם השדה שגוי או שאינו חשוף. - הוסיפו סעיף פילטר יחיד, על שדה מספרי אם אפשר. שדות טקסט ותאריך הם מקור השגיאות הנפוץ.
- הוסיפו את הסעיף השני, ואז השלישי. הסעיף שהפיל את הבקשה הוא האשם.
- רק בסוף הוסיפו הרחבה לתת-טופס ומיון.
התועלת של הסדר הזה היא שכל שלב עונה על שאלה אחרת, ולכן בסופו יש לכם משפט אבחון ולא תחושה.
למה השאילתה עובדת אצלי ונכשלת באינטגרציה?
מפני שהיא לא באמת אותה שאילתה. שלושה הבדלים מסבירים כמעט את כל המקרים:
- משתמש אחר. אתם מריצים כמשתמש עם הרשאות רחבות, והאינטגרציה מריצה כמשתמש ייעודי מצומצם. פריוריטי מגבילה גישה ברמת הטופס, ולכן אותה ישות פשוט אינה קיימת עבורו.
- חברה אחרת. בסביבה רב-חברתית אותה ישות מכילה רשומות שונות לגמרי, ושדה שקיים באחת עשוי לא להיות מוגדר באחרת.
- רישוי. קריאות ל-API דורשות את מודול ה-API ורישוי מתאים, וגרסאות 18.3 ומעלה תומכות בכותרות רישוי ברמת האפליקציה -
X-App-Idו-X-App-Key. אינטגרציה שלא שולחת אותן מתנהגת אחרת מהדפדפן שלכם.
נתון חסר או שדה שלא קיים - איך מבדילים
זו ההבחנה שגוזלת הכי הרבה זמן, כי שתי התוצאות נראות כמו רשימה ריקה.
- אם החזרתם 200 עם מערך ריק, התחביר וההרשאות תקינים. אין רשומה שעונה על התנאי, וזו שאלה עסקית ולא טכנית.
- אם קיבלתם 400, השם שכתבתם אינו שדה חוקי בישות הזו. השוו מול המטא-דאטה של הישות ולא מול מסך המשתמש.
- אם קיבלתם 404, או שהטופס אינו חשוף ל-API בסביבה הזו, או שהמפתח שביקשתם אינו קיים.
- אם קיבלתם 200 עם רשומות אך שדה אחד ריק בכולן, כנראה השדה קיים אך אינו מאוכלס בחברה שאליה התחברתם.
הדרך המהירה להכריע היא לקחת מזהה של רשומה אחת שאתם רואים על המסך, לבקש אותה ישירות לפי המפתח בלי שום פילטר, ולראות מה חוזר. אם הרשומה חוזרת, הבעיה בתנאי הסינון ולא בנתונים. אם היא לא חוזרת למרות שהיא מוצגת במסך, ההבדל הוא הרשאה או חברה, ולא תחביר.
שלוש קריאות ששווה להחזיק כבדיקת בריאות
אינטגרציה שנשענת רק על הזרימה העסקית מגלה תקלות רק כשיש עבודה. שלוש קריאות קבועות, שרצות מתוזמנות ומדווחות רק כשהן משתנות, חוסכות את רוב שיחות "לא עובד כלום".
- קריאה על ישות אחת עם רשומה אחת. אם היא נכשלת, הבעיה היא חיבור, אימות או רישוי, ואין טעם להסתכל על שום שאילתה אחרת.
- קריאה עם פילטר על שדה מספרי שידוע שיש לו תוצאה. אם היא מחזירה ריק, השתנה משהו בנתונים או בחברה שנבחרה.
- קריאה על טופס שדורש הרשאה גבוהה יותר מהרגיל. היא מגלה שינוי בהרשאות המשתמש הייעודי לפני שהאינטגרציה נופלת באמצע יום עבודה.
הערך של השלוש הוא שהן מפרידות את השכבות עוד לפני שמישהו פתח קריאת תמיכה. כשמגיעה תלונה, אתם כבר יודעים אם השרת עונה, אם המשתמש מזוהה, ואם הנתונים במקומם.
מה לשמור בכל ניסיון כושל
תיעוד קבוע לכל קריאה כושלת הופך תקלה חוזרת מוויכוח לבדיקה. שמרו:
- את הכתובת המלאה בלי סודות, כולל מחרוזת השאילתה כפי שנשלחה בפועל.
- שם הישות, השדות שנבחרו והפילטר, כל אחד בשדה נפרד.
- קוד הסטטוס וגוף התשובה המלא, ולא רק הודעה מקוצרת.
- שם המשתמש שאיתו רצה הקריאה והחברה שנבחרה.
- חותמת זמן ומזהה רשומה לדוגמה שאפשר לפתוח ידנית במסך.
בלי גוף התשובה אי אפשר לאבחן בדיעבד. קוד שתופס חריגה וזורק "API error" מוחק בדיוק את המידע שהיה פותר את התקלה.
קשור: אינטגרציה ל-API של פריוריטי, שגיאות API נפוצות בפריוריטי, Webhooks וטריגרים בפריוריטי.
מקורות
שאלות נפוצות
באיזה פורמט מוחזרות שגיאות ה-API של פריוריטי?
החל מגרסה 19.1 של פריוריטי, שגיאות שה-REST API מחזיר הן ב-JSON במקום ב-XML. אינטגרציה ותיקה שמנתחת XML תיכשל בקריאת גוף השגיאה גם כשהקריאה עצמה תקינה לחלוטין, ותדווח שגיאה מטעה למי שקורא את היומן.
קיבלתי 404 - הישות לא קיימת או שאין לי הרשאה?
שתי האפשרויות מייצרות 404, וזו הסיבה שהקוד לבדו לא מספיק. בדקו קודם שהטופס אכן חשוף ל-API בסביבה שאליה אתם מחוברים, ואז נסו את אותה קריאה עם משתמש בעל הרשאות רחבות. אם היא מצליחה, זו הרשאה.
מה עושים כשמקבלים 429?
429 מציין חריגה מקצב הקריאות. הפחיתו את התדירות, הוסיפו השהיה גדלה בין ניסיונות חוזרים, וודאו ששני תהליכים אינם מושכים במקביל את אותם נתונים. משיכה מלאה שרצה כל דקה במקום שינויים בלבד היא הסיבה הנפוצה.
האם צריך רישיון מיוחד כדי לכתוב נתונים דרך ה-API?
כן, גישת API בפריוריטי מותנית במודול ה-API וברישוי המתאים, וכתיבת נתונים דורשת גם חבילות תנועות. אם קריאות קריאה עובדות וקריאות כתיבה נכשלות בעקביות, זו נקודת הבדיקה הראשונה מול הספק, לפני שינוי בקוד.
להמשך קריאה
שירות רלוונטי
אינטגרציות
לגרום למערכות שאתם כבר משלמים עליהן לדבר זו עם זו.
על הכותב
יהונתן סעדיה
מפתח פרילנסר לאוטומציה, אתרים ו-MVP
אני יהונתן סעדיה, מפתח בכיר שבונה אוטומציה עסקית, אתרים מותאמים ומוצרי MVP לעסקים קטנים ובינוניים בארה"ב, אירופה וישראל. המדריכים האלה נכתבים מתוך עבודה אמיתית עם לקוחות, לא מתיאוריה.
בוא נעבוד יחדיש לך פרויקט דומה?
ספר לי מה אתה רוצה לבנות או איזה תהליך להפוך לאוטומטי. אני חוזר תוך 24 שעות עסקים עם כמה שאלות ממוקדות, ואז עוברים על זה יחד בשיחת היכרות חינמית של 30 דקות, בלי התחייבות. בסוף יש לך היקף עבודה, לוח זמנים ומחיר קבוע - או תשובה כנה שלא שווה לבנות את זה.