חלוקה לדפים ומעקב

בדף הזה מוסבר איך להשתמש בהחלפה בין דפים ובמעקב אחרי קבצים כשקוראים לנקודות הקצה (endpoints) של manager API.

עימוד

רוב נקודות הקצה (endpoints) של Manager API תומכות בהחלפה בין דפים. חריגים מפורטים במאמר מעקב אחרי נקודת קצה כדי לקבל רשומות מעודכנות.

הגדרת גודל הדף

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

כדי להגדיר את גודל הדפים, משתמשים בנקודת הקצה הבאה:

/manager/api/v1/agents?per=50

הגדרת גודל הדף ל-50 רשומות.

בקשה לדף ספציפי

אפשר לבקש דף ספציפי של רשומות באמצעות פרמטר השאילתה page.

כדי לבקש דף ספציפי, משתמשים בנקודת הקצה הבאה:

/manager/api/v1/agents?page=2

הפונקציה מחזירה את הדף השני של הרשומות

קבלת כל הרשומות הזמינות

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

כדי לקבל את כל הרשומות הזמינות:

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

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

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

מעקב אחרי נקודת קצה כדי לראות רשומות מעודכנות

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

מעקב אחרי נקודת הקצה של Calls API

בכל פעם שמשנים רשומה של שיחה, חותמת הזמן updated_at שלה מתעדכנת. אפשר להשתמש בחותמת הזמן כדי לציין את רשומות השיחות שרוצים לאחזר כשקוראים לנקודת הקצה של Calls API.

כדי לעקוב אחרי נקודת הקצה של Calls API כל 60 דקות, פועלים לפי השלבים הבאים:

1. שולחים בקשה לנקודת הקצה (endpoint) של Calls API ‏(/manager/api/v1/calls) ומציינים את פרמטרים השאילתה הבאים:

   • updated_at[from]. מציינים שרוצים רשומות שעודכנו בתאריך הזה או אחריו.

   • ‫sort_column. מציינים את השדה שלפיו ימוינו הרשומות.

   • ‫sort_direction. מציינים את כיוון המיון של הרשומות בתגובה.

   הדוגמה הבאה היא של סקריפט Bash שמשתמש בפקודה curl:

   # 1. Define your environment variables (usually set in your shell or .env file)
   export API_HOSTNAME="ccaip-host.uc1.ccaiplatform.com/"
   export API_USER="ccaip-host"
   export API_PASS="CCAI Platform API Key"
   
   # 2. Calculate the timestamp for 60 minutes ago in ISO 8601 format (UTC)
   # For macOS (BSD date):
   # TIMESTAMP=$(date -v-60M -u +"%Y-%m-%dT%H:%M:%SZ")
   # For Linux (GNU date):
   TIMESTAMP=$(date --date='60 minutes ago' -u +"%Y-%m-%dT%H:%M:%SZ")
   
   # 3. Execute the curl command
   # -u handles the Base64 encoding for Basic Auth automatically
   curl -g -u "${API_USER}:${API_PASS}" \
   "https://${API_HOSTNAME}/manager/api/v1/calls?updated_at[from]=${TIMESTAMP}&sort_column=updated_at&sort_direction=asc" | jq
   

   התגובה שמוחזרת מ-Calls API דומה לתגובה הבאה:

     [
       {
         "id": 100,
         ...
         "updated_at": "2025-01-01T00:00:00Z"
       },
       {
         "id": 98,
         ...
         "updated_at": "2025-01-02T00:00:00Z"
       },
       {
         "id": 150,
         ...
         "updated_at": "2025-01-03T00:00:00Z"
       }
     ]
   

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

2. שולחים קריאה לנקודת הקצה של Call API 60 דקות מאוחר יותר. יוחזרו רשומות השיחות המעודכנות מאז הבקשה האחרונה.

3. חוזרים על השלב הקודם כדי להמשיך לעקוב אחרי נקודת הקצה.

מעקב אחרי נקודת הקצה של Chats API

בכל פעם שמשנים רשומת צ'אט, חותמת הזמן updated_at שלה מתעדכנת. אפשר להשתמש בחותמת הזמן כדי לציין את רשומות הצ'אטים שרוצים לאחזר כשקוראים לנקודת הקצה של Chats API.

כדי לעקוב אחרי נקודת הקצה של Chats API כל 60 דקות, פועלים לפי השלבים הבאים:

1. שולחים בקשה לנקודת הקצה של Chats API ‏ (/manager/api/v1/chats) ומציינים את פרמטרים השאילתה הבאים:

   • updated_at[from]. מציינים שרוצים רשומות שעודכנו בתאריך הזה או אחריו.

   • ‫sort_column. מציינים את השדה שלפיו ימוינו הרשומות.

   • ‫sort_direction. מציינים את כיוון המיון של הרשומות בתגובה.

   הדוגמה הבאה היא של סקריפט Bash שמשתמש בפקודה curl:

   # 1. Define your environment variables (usually set in your shell or .env file)
   export API_HOSTNAME="ccaip-host.uc1.ccaiplatform.com/"
   export API_USER="ccaip-host"
   export API_PASS="CCAI Platform API Key"
   
   # 2. Calculate the timestamp for 60 minutes ago in ISO 8601 format (UTC)
   # For macOS (BSD date):
   # TIMESTAMP=$(date -v-60M -u +"%Y-%m-%dT%H:%M:%SZ")
   # For Linux (GNU date):
   TIMESTAMP=$(date --date='60 minutes ago' -u +"%Y-%m-%dT%H:%M:%SZ")
   
   # 3.. Execute the curl command
   # -u handles the Base64 encoding for Basic Auth automatically
   curl -g -u "${API_USER}:${API_PASS}" \
   "https://${API_HOSTNAME}/manager/api/v1/chats?updated_at[from]=${TIMESTAMP}&sort_column=updated_at&sort_direction=asc" | jq
   

   התגובה מ-Chats API תיראה כך:

   [
     {
       "id": 100,
       ...
       "updated_at": "2025-01-01T00:00:00Z"
     },
     {
       "id": 98,
       ...
       "updated_at": "2025-01-02T00:00:00Z"
     },
     {
       "id": 150,
       ...
       "updated_at": "2025-01-03T00:00:00Z"
     }
   ]
   

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

2. אחרי 60 דקות, שולחים שוב קריאה לנקודת הקצה של ה-API. יוחזרו רשומות הצ'אט המעודכנות מאז הבקשה האחרונה.

3. חוזרים על השלב הקודם כדי להמשיך לעקוב אחרי נקודת הקצה.

מעקב אחרי נקודת הקצה של Agent Activity API

בניגוד לרשומות של Chat ושיחות, יומני הפעילות של הסוכן לא מתעדכנים, ולכן אין להם חותמת זמן updated_at. אתם יכולים להשתמש ב-started_at timestamp כדי לציין את רשומות הפעילות שאתם רוצים לאחזר כשאתם קוראים לנקודת הקצה של Agent Activity API.

כדי לעקוב אחרי נקודת הקצה של Agent Activity API כל 60 דקות, פועלים לפי השלבים הבאים:

1. שולחים בקשה לנקודת הקצה של Agent Activity API ‏(/manager/api/v1/agent_activity_logs) ומציינים את פרמטרי השאילתה הבאים:

   • ‫started_at[from]. מציינים שרוצים יומני פעילות שהתחילו בזמן הזה או אחריו.

   • ‫sort_column. מציינים את השדה שלפיו ימוינו הרשומות.

   • ‫sort_direction. מציינים את כיוון המיון של הרשומות בתגובה.

   הדוגמה הבאה היא של סקריפט Bash שמשתמש בפקודה curl:

   # 1. Define your environment variables (usually set in your shell or .env file)
   export API_HOSTNAME="ccaip-host.uc1.ccaiplatform.com/"
   export API_USER="ccaip-host"
   export API_PASS="CCAI Platform API Key"
   
   # 2. Calculate the timestamp for 60 minutes ago in ISO 8601 format (UTC)
   # For macOS (BSD date):
   # TIMESTAMP=$(date -v-60M -u +"%Y-%m-%dT%H:%M:%SZ")
   # For Linux (GNU date):
   TIMESTAMP=$(date --date='60 minutes ago' -u +"%Y-%m-%dT%H:%M:%SZ")
   
   # 3. Execute the curl command
   # -u handles the Base64 encoding for Basic Auth automatically
   curl -g -u "${API_USER}:${API_PASS}" \
   "https://${API_HOSTNAME}/manager/api/v1/agent_activity_logs?started_at[from]=${TIMESTAMP}&sort_column=started_at&sort_direction=asc" | jq
   

   ה-API של פעילות הסוכן מחזיר תגובה שדומה לדוגמה הבאה:

   [
     {
       "id": 100,
       ...
       "started_at": "2025-01-01T00:00:00Z"
     },
     {
       "id": 98,
       ...
       "started_at": "2025-01-02T00:00:00Z"
     },
     {
       "id": 150,
       ...
       "started_at": "2025-01-03T00:00:00Z"
     }
   ]
   

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

2. מתקשרים שוב לנקודת הקצה של Agent Activity API‏ 60 דקות מאוחר יותר. יוחזרו רשומות מעודכנות של יומן פעילות הסוכן מאז הבקשה האחרונה.

3. חוזרים על השלב הקודם כדי להמשיך לעקוב אחרי נקודת הקצה.