ניתוח שיחה באמצעות ה-API

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

דרישות מוקדמות

1. מפעילים את ממשקי ה-API של Cloud Storage ו-Insights בפרויקט ב- Google Cloud .
2. ייבוא נתוני השיחות

שיחת צ'אט

1. ייבוא תמליל הצ'אט של השיחה כאובייקט בקטגוריה של Cloud Storage.

2. רושמים את נתיב האובייקט בפורמט gs://<bucket>/<object>.

קובץ תמליל הצ'אט צריך להיות בפורמט JSON, בהתאם לפורמט נתוני השיחות של CCAI.

שיחה קולית

1. ייבוא כל הקבצים מקטגוריה של Cloud Storage. צריך לייבא את קובצי האודיו והתמליל כאובייקטים בקטגוריה של Cloud Storage.

2. רושמים את שני נתיבי האובייקטים בפורמט gs://<bucket>/<object>.

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

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

ניתוח שיחה

אחרי שיוצרים אובייקט Conversation ב-CX Insights, צריך לנתח אותו כדי לקבל תוצאות שימושיות. אפשר לנתח שיחה אחת הרבה פעמים, וכל ניתוח נפרד יוצר אובייקט Analysis חדש.

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

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

הערה: אם השדה languageCode לא מוגדר, CX Insights יסיק אותו באופן אוטומטי. אפשר להשתמש רק באנגלית (בכל הניבים) בניתוחים.

יצירת ניתוח חדש

ההרשאות שנדרשות למשימה הזו

כדי לבצע את המשימה הזו, נדרשות ההרשאות הבאות:

• contactcenterinsights.analyses.create

REST

פרטים מלאים מופיעים בנקודת קצה ל-API‏ conversations.analyses:create.

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

• ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
• ‫CONVERSATION_ID: המזהה של השיחה שרוצים לנתח. הערך הזה הוחזר בתגובה של createConversation.

הערה: כל הדוגמאות מתייחסות למופע הגלובלי של Customer Experience Insights. הוראות לשימוש במופעים אזוריים מופיעות במאמר בנושא התאמה לאזור.

ה-method של ה-HTTP וכתובת ה-URL:

POST https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/conversations/CONVERSATION_ID/analyses

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

‫Curl (Linux,‏ macOS או Cloud Shell)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

מריצים את הפקודה הבאה:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d "" \
     "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/conversations/CONVERSATION_ID/analyses"

‎PowerShell (Windows)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

מריצים את הפקודה הבאה:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -Uri "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/conversations/CONVERSATION_ID/analyses" | Select-Object -Expand Content

אתם אמורים לקבל תגובת JSON שדומה לזו:

{
  "name": "projects/PROJECT_ID/locations/us-central1/operations/OPERATION_ID"
}

Python

כדי לבצע אימות ב-CX Insights, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית.

from google.cloud import contact_center_insights_v1


def create_analysis(conversation_name: str) -> contact_center_insights_v1.Analysis:
    """Creates an analysis.

    Args:
        conversation_name:
            The parent resource of the analysis.
            Format is 'projects/{project_id}/locations/{location_id}/conversations/{conversation_id}'.
            For example, 'projects/my-project/locations/us-central1/conversations/123456789'.

    Returns:
        An analysis.
    """
    # Construct an analysis.
    analysis = contact_center_insights_v1.Analysis()

    # Call the Insights client to create an analysis.
    insights_client = contact_center_insights_v1.ContactCenterInsightsClient()
    analysis_operation = insights_client.create_analysis(
        parent=conversation_name, analysis=analysis
    )
    analysis = analysis_operation.result(timeout=86400)
    print(f"Created {analysis.name}")
    return analysis

Java

כדי לבצע אימות ב-CX Insights, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית.

import com.google.cloud.contactcenterinsights.v1.Analysis;
import com.google.cloud.contactcenterinsights.v1.ContactCenterInsightsClient;
import java.io.IOException;

public class CreateAnalysis {

  public static void main(String[] args) throws Exception, IOException {
    // TODO(developer): Replace this variable before running the sample.
    String conversationName =
        "projects/my_project_id/locations/us-central1/conversations/my_conversation_id";

    createAnalysis(conversationName);
  }

  public static Analysis createAnalysis(String conversationName) throws Exception, IOException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (ContactCenterInsightsClient client = ContactCenterInsightsClient.create()) {
      // Construct an analysis.
      Analysis analysis = Analysis.newBuilder().build();

      // Call the Insights client to create an analysis.
      Analysis response = client.createAnalysisAsync(conversationName, analysis).get();
      System.out.printf("Created %s%n", response.getName());
      return response;
    }
  }
}

Node.js

כדי לבצע אימות ב-CX Insights, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית.

/**
 * TODO(developer): Uncomment this variable before running the sample.
 */
// const conversationName = 'projects/my_project_id/locations/us-central1/conversations/my_conversation_id';

// Imports the Contact Center Insights client.
const {
  ContactCenterInsightsClient,
} = require('@google-cloud/contact-center-insights');

// Instantiates a client.
const client = new ContactCenterInsightsClient();

async function createAnalysis() {
  try {
    const [operation] = await client.createAnalysis({
      parent: conversationName,
    });

    // Wait for the operation to complete.
    const [analysis] = await operation.promise();
    console.info(`Created ${analysis.name}`);
  } catch (err) {
    console.error(`createAnalysis failed: ${JSON.stringify(err, null, 2)}`);
    process.exitCode = 1;
  }
}
createAnalysis();

(אופציונלי) הגדרת ניתוח

ההרשאות שנדרשות למשימה הזו

כדי לבצע את המשימה הזו, נדרשות ההרשאות הבאות:

• contactcenterinsights.analyses.create

REST

פרטים מלאים מופיעים בנקודת קצה ל-API‏ conversations.analyses:create. כוללים את כל כלי ההערות שרוצים להפעיל באובייקט annotatorSelector ומגדירים אותם לערך true. אם לא תציינו מגיבים, ברירת המחדל תהיה false. אם לא מציינים אף כלי להוספת הערות באובייקט annotatorSelector, כל הכלים להוספת הערות יופעלו.

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

• ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
• ‫PHRASE_MATCHER(s): שמות המשאבים המוגדרים במלואם של כלי ההתאמה לביטויים שרוצים להשתמש בהם לסימון ביטויים. אם השדה הזה יישאר ריק, כל ההתאמות הפעילות לביטויים יפעלו.
• ‫ISSUE_MODEL(s): שמות המשאבים המוגדרים במלואם של מודלים לזיהוי בעיות שרוצים להשתמש בהם לסימון מודלים לזיהוי בעיות. הפעולה הזו עובדת רק אם run_issue_model_annotator הוא true. אם לא תציינו ערך בשדה הזה, כל המודלים של הבעיות שפרסתם יפעלו. בשלב הזה אפשר לפרוס רק מודל אחד.

הערה: כל הדוגמאות מתייחסות למופע הגלובלי של Customer Experience Insights. הוראות לשימוש במופעים אזוריים מופיעות במאמר בנושא התאמה לאזור.

ה-method של ה-HTTP וכתובת ה-URL:

POST https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/conversations/CONVERSATION_ID/analyses

תוכן בקשת JSON:

{
  "annotatorSelector": {
    "run_interruption_annotator": {true/false},
    "run_silence_annotator": {true/false},
    "run_phrase_matcher_annotator": {true/false},
    "phrase_matchers": PHRASE_MATCHER(s),
    "run_sentiment_annotator": {true/false},
    "run_entity_annotator": {true/false},
    "run_intent_annotator": {true/false},
    "run_issue_model_annotator": {true/false}
    "issue_models": ISSUE_MODEL(s)
  }
}

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

‫Curl (Linux,‏ macOS או Cloud Shell)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/conversations/CONVERSATION_ID/analyses"

‎PowerShell (Windows)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/conversations/CONVERSATION_ID/analyses" | Select-Object -Expand Content

אתם אמורים לקבל תגובת JSON שדומה לזו:

{
  "name": "projects/PROJECT_ID/locations/us-central1/operations/OPERATION_ID"
}

דגימה של הפעולה

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