התחילו עם Microsoft Learn Platform API

מאמר זה מסייע לך להתחיל להשתמש ב-API של Microsoft Learn Platform. אם אינך מכיר את פרטי ה-API או את מקרי השימוש שלו, אנו ממליצים לך לעיין תחילה במאמר סקירה של Microsoft Learn Platform API .

ללמוד אימות API של פלטפורמה

ממשקי REST של Learn Platform משתמשים ב-Microsoft Entra ID לאימות. לפני ביצוע קריאות API, עליך לבחור שיטת גישה, ואפליקציית הלקוח חייבת לאמת עם אישורים תקפים.

גישה בלבד לאפליקציה

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

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

ברגע שזהות ה-Entra ID שלך מוגדרת, קבל אסימון גישה מ-Entra ID עם היקף מוגדר כהוכחת אימות. כלול את אסימון הגישה בכותרת הרשאת HTTP בעת ביצוע בקשות API של REST ללמידה.

גישה מוסמכת

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

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

• : היקף זה מאפשר למשתמשים לגשת לתוכן ציבורי ב-Learn כשהם מתחזים למשתמש המחובר.

הבנת גרסאות API של Microsoft Learn Platform

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

גרסת API מוגדרת כפרמטר שאילתת גרסאות API ומשתמשת ב-yyyy-MM-dd לגרסאות יציבות ו-yyyy-MM-dd-preview לגרסאות תצוגה מקדימה. פרמטר השאילתות בגרסת API נדרש לכל בקשת API.

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

הגרסה הנוכחית היא 2023-11-01-preview.

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

למד הגבלת קצב API של פלטפורמה

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

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

כברירת מחדל, מגבלת הקצב היא 100 קריאות API לדקה, המחושבות לאורך חלון זמן של 5 דקות. אם אתה זקוק למגבלה גבוהה יותר לייצור, תוכל לפנות לתמיכת Learn Integrations כדי לבקש העלאה.

ממשקי API מסוימים, כמו API חיפוש הידע, גם הם מיישמים הגבלת קצב מבוססת טוקנים. זה מבוסס על מספר טוקני Microsoft Azure OpenAI שנצרכו, עם מגבלה ברירת מחדל של 10,000 טוקנים לדקה. כדי להגדיל את המגבלה הזו לייצור, פנו לתמיכה של Learn Integrations.

Learn Platform Api-Pagination

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

שיטות API לרשימה משתמשות בעמוד סמן, המסומן על ידי שדה nextLink בגוף התגובה. שדה זה מכיל כתובת URL אטומה עם המידע הדרוש לשליפת הדף הבא של התוצאות. כברירת מחדל, ממשקי List APIs מחזירים 30 פריטים לכל בקשה, אבל אפשר להתאים את גודל הדף באמצעות פרמטר maxpagesize.

ספריות ה-SDK שלנו מציעות עזרי אוטופיגינציה לעבור על כל דפי הרשימה.

תוכן קשור

• התחלה מהירה: הגדר ושימוש בנתוני קטלוג API של פלטפורמת Microsoft Learn
• הפניה למפתח נתוני קטלוג API של פלטפורמת Learn
• שאלות נפוצות על Learn Platform API