שיטות מומלצות

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

זיהוי מתקנים בעקביות

בחרו בשיטת הקישור שהוגדרה לחשבון השותף שלכם והשתמשו בה בעקביות:

• Direct Link - השתמשו ב-facility_id של Performance Hub שמוחזר מנקודת הקצה של המתקנים.
• Linking Identifier - השתמשו במזהה המיקום שלכם, כגון מזהה סניף, קוד מיקום או מספר חנות.

אל תשלחו את שני המזהים באותה בקשה. Performance Hub מפענח בקשות לפי שיטת הקישור שהוגדרה לחשבון השותף שלכם.

להנחיות הגדרה, ראו שיטות קישור של שותפים.

כתיבה באצוות בזהירות

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

הנחיות ברירת מחדל:

• השתמשו בעד 1000 פריטים בכל בקשת אצווה לביצועים מיטביים.
• שמרו על מטענים מתחת ל-10MB.
• הישארו בגבול של 5 בקשות לשנייה לכל נקודת קצה.

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

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

ניסיונות חוזרים בבטחה

השתמשו בהשהיה מעריכית (exponential backoff) עבור כשלים חולפים כגון 429, 500, 502, 503 ו-504.

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

1. נסו שוב לאחר שנייה אחת.
2. נסו שוב לאחר 2 שניות.
3. נסו שוב לאחר 4 שניות.
4. עצרו ושלחו התראה אם הפעולה עדיין נכשלת.

בכשלי אימות נתונים כגון 400 או 422, תקנו את הבקשה לפני ניסיון חוזר.

שימוש באידמפוטנטיות במקומות שבהם היא נתמכת

נקודת הקצה של פתיחת Door/Gate Controller תומכת בפרמטר אופציונלי idempotency_key. שימוש חוזר באותו מפתח עבור אותם שותף, מתקן ודלת מחזיר את התוצאה הקיימת, כשיש כזו.

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

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

שמירה על נתוני מקור נקיים

שלחו ערכים יציבים ומנורמלים בכל מקום אפשרי:

• השתמשו במזהי חברים, תוכניות, מתקנים וצ׳ק-אינים עקביים ממערכת המקור שלכם.
• השתמשו בחותמות זמן בפורמט ISO 8601 לתאריכים ולשעות.
• שלחו מספרי טלפון בפורמט בינלאומי, כשהם זמינים.
• שלחו מטבעות באמצעות השדות המתועדים לכל נקודת קצה.
• הימנעו מהעמסת שדות טקסט חופשי בנתונים ששייכים לשדות מובנים.

תכנון לסנכרון מצטבר ולסנכרון מלא

רוב אינטגרציות השותפים צריכות את שניהם:

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

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

פרסום Access Time Windows בבטחה

התייחסו לערך access_time_windows של כל חבר כאל תמונת מצב שלמה, עם גרסאות עצמאיות:

• תאמו זרם אחד של access_time_windows_revision שעולה באופן מונוטוני בין תהליכי העבודה המצטברים לבין תהליכי ההתאמה.
• שלחו שוב מסירה שתוצאתה לא ודאית או שנכשלה באופן חולף, עם אותה גרסה ואותו מטען מנורמל.
• השמיטו את access_time_windows כשאינכם מעדכנים אותו.
• שלחו [] רק לאחר ששליפה מוצלחת ממקור מוסמך מוכיחה שלא נותרו חלונות. לעולם אל תהפכו זמן קצוב שפג במערכת המקור, תוצאה חלקית או כשל בניתוח לשלילת גישה.
• שמרו על external_id ו-scope_key יציבים, ואשרו כל מיפוי של טווח לפני המעבר לסביבת הייצור.
• עקבו אחר גיל נתוני המקור ביחס למדיניות העדכניות שסוכמה לאותה אינטגרציה.

למידע על תמונות מצב שלמות, אזורי זמן, שעון קיץ, ביטול ווקטורי בדיקה, ראו את המדריך המוסמך ליצרני Access Time Windows.

התייחסות לבקרת גישה כקריטית לבטיחות

בפתיחות של Door/Gate Controller:

• המערכת שלכם חייבת להחליט אם מותר לאדם להיכנס לפני הקריאה ל-Performance Hub.
• Performance Hub מחזיר 200 רק לאחר שהבקר שבאתר מאשר שהממסר נפתח פיזית.
• רוב האישורים מתקבלים תוך 3-5 שניות.
• זמן קצוב שפג הוא פתיחה שנכשלה באופן מפורש, ולא הצלחה ברקע.
• נסו שוב רק בהתאם לכללי הגישה והבטיחות שלכם.

תמיד תעדו את ה-event_id וה-command_id שמוחזרים מנקודת הקצה של הפתיחה.

ניטור האינטגרציה שלכם

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

• חותמת הזמן של הבקשה.
• נקודת הקצה.
• מזהה רשומת המקור.
• מזהה המתקן.
• קוד סטטוס ה-HTTP.
• גוף התגובה או הודעת השגיאה של Performance Hub.

שדות אלה מאיצים מאוד את התמיכה ואת ההתאמה כשלקוח שואל מה קרה.