Skip to main content
ה-API של /v1 אוכף שני תקציבי בקשות עצמאיים. בקשה נדחית אם אחד מהתקציבים אזל. התקציב לכל מפתח עוקב אחר המפתח בכל מקום שבו נעשה בו שימוש. התקציב לכל כתובת IP הוא התקציב היחיד עבור תעבורה לא מאומתת, ותקרה שנייה עבור תעבורה מאומתת.
המגבלות נאכפות לפני האימות, ולכן גם בקשות עם אישורי גישה לא תקינים או חסרים נספרות במסגרת תקציב המקור. התקציבים המספריים המדויקים נקבעים על ידי המפעיל ועשויים להשתנות; חוזה התגובה שלהלן הוא הממשק היציב שעליו יש לבסס את הפיתוח.
יש לבצע אימות באחד משני מבני אישורי ה-Basic — ראו התחלה מהירה (apikey:secret או secret:). יש להגדיר את BASE למארח האזורי של הארגון — ראו אזורים.

תגובת 429

כאשר תקציב אזל, ה-API מחזיר 429 Too Many Requests עם כותרת Retry-After (בשניות) וגוף תקני של פרטי בעיה (problem details):
429 Too Many Requests
התגובה אינה מציינת איזה תקציב אזל. יש להתייחס לכל 429 באותו אופן: להמתין ואז לנסות שוב.

טיפול בתגובות 429

1

כיבוד Retry-After

יש להמתין לפחות את מספר השניות המצוין בכותרת Retry-After לפני ביצוע ניסיון חוזר. ניסיון חוזר מוקדם יותר רק צורך שוב תקציב בבקשות שיידחו.
2

האטה מעריכית בניסיונות חוזרים

אם ניסיון חוזר נדחה שוב, יש להגדיל את זמן ההמתנה ולהוסיף jitter אקראי כדי שעובדים מקבילים לא יבצעו ניסיונות חוזרים בו-זמנית. אין לקצר את Retry-After של השרת כדי להתאימו למגבלה מקומית. אם השרת מבקש להמתין זמן רב יותר ממה שתקציב הניסיונות החוזרים שלכם מאפשר, יש להפסיק ולתזמן את העבודה למועד מאוחר יותר.
3

החלקת קצב הבקשות

מומלץ להעדיף קצב בקשות יציב על פני פרצים. בקריאות נפח גדול, יש להשתמש בגודל העמוד המרבי (limit=500) כדי לכסות את האוסף בפחות בקשות — ראו דפדוף. כאשר כמה מעברי רשימה פועלים במקביל (לדוגמה, טבלאות Power BI), יש לשמור על רמת מקביליות מתונה ולכבד את Retry-After כדי ש-429 זמני לא יכשיל את הרענון כולו.
דוגמה זו מבצעת ניסיון חוזר רק בתגובות 429 עבור בקשת GET, עם לכל היותר חמישה ניסיונות ולכל היותר 60 שניות המתנה בין ניסיון לניסיון. היא נעצרת מיד בשגיאות אחרות. פסקי זמן ברשת מועברים אל הקורא. יש להגדיר פסקי זמן ותקציבי ניסיונות חוזרים בהתאם לעומס העבודה שלכם. requests מפרש את פסק הזמן לקריאה כזמן הסרק המרבי בעת קבלת נתונים, ולא כמועד יעד כולל. יש לטעון את LIVING_SECURITY_API_KEY ממנהל הסודות שלכם. יש להתקין את requests לפני הרצת הדוגמה. יש לקרוא ל-get_with_retry("/organization") כדי להשתמש בה.
Python
אין להעתיק לולאה זו סביב פעולת כתיבה. פסק זמן לאחר כתיבה עשוי לציין שהשרת ביצע את הפעולה לפני שהחיבור נכשל. יש לחזור על כתיבה רק כאשר התיעוד של אותה פעולה מציין במפורש אידמפוטנטיות, תוך שמירה על אותו מפתח ועל אותו מטען (payload). אחרת, יש ליישב את מצב המשאב לפני ביצוע ניסיון נוסף.

לוח זמנים מומלץ לרענון

יש לקבוע את תדירות הרענון בהתאם לתקציב המפתח ולגודל העמוד. טעינה היסטורית מלאה של אוסף גדול היא עלות חד-פעמית; מומלץ להעדיף חלונות מצטברים ברענונים במצב יציב, כך שכל הרצה תישאר הרבה מתחת לתקציב. יש להגדיר תמיד את limit=500 במפורש — ברירת המחדל של 25 מכפילה את מספר הבקשות.