אחזור נתוני הגדרות משתמשים

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

נקודת הקצה הזו שונה מנקודות הקצה שמשמשות בתהליך העלאת משתמשים בכמות גדולה, והיא מספקת את המידע שנדרש לתמיכה בפעולות בכמות גדולה. מידע נוסף על ביצוע תהליכים של ניהול משתמשים בכמות גדולה זמין במאמר בנושא Bulk User Management API.

היכולות והמגבלות של ממשקי API

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

• משתמשים ספציפיים

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

• חלוקה לעמודים

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

  • פרמטר API מאפשר למשתמשים לבקש דף תוצאות ספציפי.

  • המשתמשים יכולים לציין את גודל הדף. גודל הדף שמוגדר כברירת מחדל הוא 100, והערך המקסימלי הוא 1,000. כשמספקים מספר דף ספציפי, אי אפשר לכלול את מזהי המשתמשים בבקשה.

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

• אין ערך למשתמשים פעילים.

• התאריך והשעה שבהם המשתמש הושבת.

בטבלה הבאה מפורטים שדות פרופיל המשתמש שייכללו בתשובת ה-API:

טבלה 1. טבלת שדות של פרופיל משתמש

הזמנה	סוג העמודה	מספר העמודות	שם העמודה	ערכים תקינים
1	אימייל	1	אימייל	אימייל
2	מזהה הסוכן	1	מזהה הסוכן	String
3	שם פרטי	1	שם פרטי	String
4	שם משפחה	1	שם משפחה	String
5	כינוי	1	כינוי	String
6	הושבת בתאריך	1	הושבת בתאריך	אין ערך, תאריך/שעה
7	מיקום	1	מיקום	מחרוזת שהיא שם מיקום, Empty (ללא שינוי), Null (הסרת המיקום הנוכחי).
8	מספר השיחות בצ'אט	1	מספר השיחות בצ'אט	‫1 עד X (כאשר X הוא הערך המוגדר), ריק
9	סטטוס של שיחות צ'אט בו-זמניות	1	סטטוס של שיחות צ'אט בו-זמניות	‫0, 1, ריק
10	שיחות לחו"ל ללא הגבלה	1	שיחות לחו"ל ללא הגבלה	(True/False)
11	משתמש חיצוני	1	משתמש חיצוני	(כן/לא)
12	כתובת URI חיצונית של SIP	1	כתובת URI חיצונית של SIP	String
13	שם משתמש ב-UCaaS	1	שם משתמש ב-UCaaS	String
14	תוספים לסוכנים	1	תוספים לסוכנים
15	תפקידים	כמה סוגים	תפקיד: שם התפקיד א' תפקיד: שם התפקיד ב' תפקיד: שם התפקיד ג' וכו'.	‫0, 1, ריק
16	ChromeOS	כמה סוגים	צוות: שם הצוות א', צוות: שם הצוות ב', צוות: שם הצוות ג' וכו'.	‫0, 1, ריק
17	מספר טלפון	כמה סוגים	מספר ישיר לשיחות נכנסות: 1, מספר ישיר לשיחות נכנסות: 2, מספר ישיר לשיחות נכנסות: 3	מספר טלפון שמתחיל באות E. פורמט 164
18	מסנן	רווק/ה	מסנן	String
19	זמן קצוב לסינון	רווק/ה	זמן קצוב לסינון	ערך מספרי בין 0 ל-1,440

מגבלות

• כל בקשה יכולה לכלול רק סוג אחד של מזהה משתמש.

• המספר המקסימלי של מזהים לכל בקשת API הוא 1,000.

• המשתמשים לא יכולים לציין גם מזהי משתמשים וגם בקשה למספר דף בבקשת API אחת. ה-API יחזיר את כל המשתמשים על סמך הבקשה, עד 1,000 משתמשים.

הודעות שגיאה ב-API

ה-API יספק את הודעות השגיאה הבאות בתרחישים ספציפיים:

• גודל הדף: 'חריגה מגודל הדף המקסימלי (הגודל המקסימלי הוא 1,000)'

• גודל הדף (נדרשת הזנה של מספר): "בקשה לא חוקית לגודל הדף. צריך להיות ערך מספרי"

• בקשה משולבת של מזהה משתמש וחלוקה לדפים: "לא ניתן לשלב בין מזהה משתמש לבין בקשה לחלוקה לדפים"

• מזהה משתמש (חרגה מהמגבלה): "חרגה מהמספר המקסימלי של מזהי משתמשים (1,000 הוא המספר המקסימלי)"

דוגמה לבקשה ולתגובה

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

בקשה:

Method: GET
Type:
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/users?page=1&per_page=100

תשובה:

[
  {
    "email": "email",
    "agent_number": "number",
    "first_name": "first",
    "last_name": "last",
    "status": "Active",
    "location": "location",
    "max_chat_limt": 3,
    "max_chat_limit_enabled": true,
    "deleted_at": "2024-07-16T15:57:12.000Z",
    "ucaas_user_name": "username",
    "external_user": true,
    "ucaas_sip_uri": "sip uri",
    "unrestricted_international_calling": false,
    "roles": [
      { "name": "Admin" },
      { "name": "Manager" }
    ],
    "teams": [
      { "name": "name" }
    ],
    "phone_numbers": [
      "123-456-7890",
      "098-765-4321"
    ]
  },
  ...
]

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

בקשה:

Method: GET
Type:
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/users?email[]=email

תשובה:

[
  {
    "email": "email",
    "agent_number": "number",
    "first_name": "first",
    "last_name": "last",
    "status": "Active",
    "location": "location",
    "max_chat_limt": 3,
    "max_chat_limit_enabled": true,
    "deleted_at": "2024-07-16T15:57:12.000Z",
    "ucaas_user_name": "username",
    "external_user": true,
    "ucaas_sip_uri": "sip uri",
    "unrestricted_international_calling": false,
    "roles": [
      { "name": "Admin" },
      { "name": "Manager" }
    ],
    "teams": [
      { "name": "name" }
    ],
    "phone_numbers": [
      "123-456-7890",
      "098-765-4321"
    ]
  }
]