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

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

עימוד

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

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

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

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

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

הפעולה הזו מגדירה את גודל הדף ל-50 רשומות.

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

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

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

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

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

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

כברירת מחדל, ה-API של מנהל ההתקנים מחזיר 100 רשומות בדף תגובה, אבל אפשר לשנות את מספר הרשומות בדף על ידי הגדרת גודל הדף. בנקודות הקצה שתומכות בחלוקה לדפים, כותרת התגובה כוללת את המספר הכולל של הרשומות הזמינות. אם המספר הזה גדול מגודל הדף, צריך לשלוח קריאה ל-API כמה פעמים כדי לקבל את כל הרשומות. בנקודות קצה שתומכות בעימוד, התשובה כוללת כותרת Link בהתאם ל-RFC 5988. הקישור rel="next" מופיע כשיש עוד רשומות, והקישור rel="last" מציג את מספר הדף האחרון. התשובה כוללת גם את הכותרות Total ו-Per-Page.

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

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

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

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

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

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

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

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

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

  1. שולחים בקשה לנקודת הקצה של 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
    

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

      [
        {
          "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 מהאובייקט האחרון בתגובה הזו. המסנן from הוא כולל, כך שהתגובה הבאה חוזרת על הרשומה בחותמת הזמן הזו. מבטלים כפילויות לפי מזהה הרשומה, או מתעדים את המזהים שכבר עובדו בחותמת הזמן הזו ומדלגים עליהם.

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

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

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

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

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

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

  1. שולחים בקשה לנקודת קצה ל-API של Chats‏ (/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
    

    ה-API של Chats מחזיר תשובה שדומה לזו:

    [
      {
        "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. שולחים שוב קריאה לנקודת הקצה ל-API אחרי 60 דקות. התשובה תכלול את רשומות הצ'אט שעודכנו מאז הבקשה האחרונה.

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

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

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

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

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

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

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

    • ‫page. צריך לכלול את הפרמטר הזה כדי שהתשובה תחזיר כותרות של חלוקה לדפים. בלי page, התגובה מוגבלת לגודל ברירת המחדל של הדף, שהוא 100 רשומות, בלי להחזיר את הכותרות Link,‏ Total או Per-Page.

    • ‫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
    

    ‫Agent Activity 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. קוראים שוב לנקודת קצה ל-API של Agent Activity אחרי 60 דקות. יוחזרו הרשומות המעודכנות של יומן הפעילות של הסוכן מאז הבקשה האחרונה.

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