API zum Importieren von Unterhaltungen verwenden

Hier erfahren Sie, wie Sie Audio- und Transkriptdateien mit ihren Metadaten über die API importieren können. Sie können eine einzelne Datei mit der UploadConversation API importieren oder alle Dateien aus einem Cloud Storage-Bucket mit der IngestConversations API im Bulk-Verfahren importieren.

Die beiden Anfragebefehle UploadConversation und IngestConversations unterstützen die folgenden Funktionen:

Befehl anfordern Anzahl der Dateien Speech-to-Text Entfernen Metadatenaufnahme Automatische Analyse
UploadConversation 1 ✔ ✔ ✔ Mit Analyseregeln oder dem Prozentsatz für die Analyse von hochgeladenen Unterhaltungen im Projekt [settings](/contact-center/insights/docs/reference/rest/v1alpha1/Settings#analysisconfig)
IngestConversations Alle Dateien in einem Bucket ✔ ✔ ✔ Nur mit Analyseregeln

Vorbereitung

  1. Aktivieren Sie die Cloud Storage API, Speech-to-Text API, Cloud Data Loss Prevention API und Customer Experience Insights API für das Google Cloud Projekt, das Sie für Dialogflow verwenden.
  2. Speichern Sie Ihre Unterhaltungsdaten (Dual-Channel-Audio- und Transkriptdateien) in einem Cloud Storage-Bucket mit der Standard Storage-Klasse.
    1. Folgen Sie der Cloud Storage-Kurzanleitung, um einen Bucket zu erstellen.
    2. Legen Sie den Bucket-Speicherort auf einen Standort fest, der Ihrem Standort am nächsten ist.
    3. Beachten Sie die folgenden Informationen, die Sie benötigen, wenn Sie Konversationsdaten angeben:
      • Bucket-Name
      • Standort-ID, Format: us-west1
      • Objektpfad, Format: gs://<bucket>/<object>
  3. Gewähren Sie den Dienst-Agents für Speech-to-Text und Customer Experience Insights Zugriff auf die Objekte in Ihrem Cloud Storage-Bucket. Auf dieser Seite finden Sie Hilfe bei der Fehlerbehebung für Dienstkonten.

  4. Wenn Sie Unterhaltungsmetadaten importieren möchten, müssen sich die Metadatendateien in einem eigenen Bucket befinden und die Namen der Metadatendateien müssen mit den Namen der entsprechenden Unterhaltungsdateien übereinstimmen.

    Für eine Unterhaltung mit dem Cloud Storage-URI gs://transcript-bucket-name/conversation.mp3 muss beispielsweise eine entsprechende Metadatendatei wie gs://metadata-bucket-name/conversation.json vorhanden sein.

Konversationsdaten

Unterhaltungsdaten bestehen aus Sprach- oder Chattranskripten und Audio.

Transkripte

Chat-Transkripte müssen in JSON-formatierten Dateien bereitgestellt werden, wobei jede Datei Daten für eine einzelne Unterhaltung enthält. Ihre JSON-formatierten Textdateien enthalten das Konversationsdatenformat.

Sprachtranskripte können im Konversationsdatenformat oder als das zurückgegebene Spracherkennungsergebnis einer Speech-to-Text API-Transkription bereitgestellt werden. Die Antwort ist für die synchrone und asynchrone Erkennung in allen Speech-to-Text API-Versionen identisch.

Audio

Customer Experience Insights verwendet die Batcherkennung von Cloud Speech-to-Text, um Audio zu transkribieren. CX Insights konfiguriert die Speech-to-Text-Transkriptionseinstellungen mit Recognizer-Ressourcen. Sie können eine benutzerdefinierte Erkennung in der Anfrage erstellen. Wenn Sie keine Erkennung in den Einstellungen oder in der Anfrage angeben, wird in Ihrem Projekt eine Standard-ccai-insights-recognizer erstellt.

Der CX Insights-Recognizer transkribiert englische Sprache mit dem Telefonie-Modell. Die Standardsprache ist „en-US“. Eine vollständige Liste der Speech-to-Text-Unterstützung nach Region, Sprache, Modell und Erkennungsfunktion finden Sie in der Dokumentation zur Sprachunterstützung für Speech-to-Text.

Bevor Sie Audioinhalte zum ersten Mal in CX Insights importieren, sollten Sie Folgendes überlegen:

  • Verwenden Sie eine benutzerdefinierte Speech-to-Text-Transkriptionskonfiguration.
  • Analysieren Sie die (optional) geschwärzten Unterhaltungen.

Sie können diese Aktionen so konfigurieren, dass sie standardmäßig in jeder UploadConversation- oder IngestConversation-Anfrage ausgeführt werden. Dazu legen Sie die entsprechenden Felder in der Settings-Ressource des Projekts fest. Die Einstellungen für Sprache und Maskierung können auch pro Anfrage überschrieben werden. Wenn Sie keine Spracheinstellungen angeben, werden die Standardeinstellungen für die Sprache verwendet und die Transkripte werden nicht unkenntlich gemacht.

Entfernen

Cloud Data Loss Prevention entfernt keine Transkripte, sofern Sie nicht explizit Konfigurationen zum Entfernen in den Einstellungen des Projekts, im UploadConversationRequest oder im IngestConversationsRequest angeben. Cloud Data Loss Prevention unterstützt sowohl Inspektionsvorlagen als auch De-Identifikationsvorlagen für die Schwärzung.

Projekteinstellungen konfigurieren

Die Schwärzung und die Sprachausgabe können für UploadConversation- und IngestConversations-Anfragen konfiguriert werden, indem die entsprechenden Parameter für die Projekteinstellungen festgelegt werden. Diese Konfigurationen können auch individuell pro Anfrage festgelegt werden, wodurch die Projekteinstellungen überschrieben werden. Die in einer Analyseregel konfigurierte analysis_percentage überschreibt die über die Projekteinstellungen konfigurierte upload_conversation_analysis_percentage.

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

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/LOCATION_ID/settings?updateMask=redaction_config,speech_config,analysis_config.upload_conversation_analysis_percentage"

Metadaten

Metadaten in einer einzelnen Datei oder als Bulk-Import importieren

Metadaten direkt in die Anfrage einfügen

Bei Importen mit nur einer Datei können Ihre Qualitätsmetadaten direkt in den curl-Befehl für UploadConversationsRequest aufgenommen werden.

curl --request POST \
  'https://contactcenterinsights.googleapis.com/v1/projects/project-id/locations/location-id/conversations:upload' \
   --header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
   --header 'Accept: application/json' \
   --header 'Content-Type: application/json' \
   --data '{
           "conversation":{
            "qualityMetadata":{
               "agentInfo":[{"agentId":"agent-id","displayName":"agent-name"}]
             },
            "dataSource":{"gcsSource":{"transcriptUri":"transcript-uri"}}}
          }'

Metadaten aus Cloud Storage-Dateien importieren

Stellen Sie Dateien mit Unterhaltungsmetadaten als JSON-formatierte Dateien bereit. Geben Sie für Massenimporte einen Bucket an, der im Feld gcs_source.metadata_bucket_uri der IngestConversationsRequest angegeben ist. Geben Sie für einzelne Importe einen Objektpfad im Feld data_source.metadata_uri des UploadConversationRequest an.

CX Insights füllt die in der Datei enthaltenen Metadaten zur Konversationsqualität aus. Sie können aber auch benutzerdefinierte Metadaten erstellen.

Wenn Sie beispielsweise für jede Unterhaltung in Ihrem Dataset eine benutzerdefinierte Unterhaltungs-ID angeben möchten, geben Sie benutzerdefinierte Metadaten für das Unterhaltungsobjekt in Cloud Storage an. Legen Sie den Schlüssel auf ccai_insights_conversation_id fest. Der Wert ist Ihre benutzerdefinierte Unterhaltungs-ID. Benutzerdefinierte Konversations-IDs können auch in der Metadatendatei angegeben werden.

Wenn Sie benutzerdefinierte Metadaten im Feld custom_metadata_keys eines IngestConversationsRequest angeben, werden diese benutzerdefinierten Metadaten in den Labels der Konversation gespeichert. Es werden bis zu 100 Labels unterstützt.

Im Folgenden sehen Sie ein Beispiel für eine gültige Metadatendatei, die die Ressource Conversation.quality_metadata sowie eine benutzerdefinierte Unterhaltungs-ID und die Startzeit der Unterhaltung enthält:

{
  "customer_satisfaction_rating": 5,
  "agent_info": [
    {
      "agent_id": "123456",
      "display_name": "Agent Name",
      "team": "Agent Team",
      "disposition_code": "resolved"
    }
  ],
  "custom_key": "custom value"
  "conversation_id": "custom-conversation-id"
  "start_time": "%Y-%m-%d%ET%H:%M:%E*S%Ez"
}

Einzelne Audiodatei importieren

Mit der UploadConversation API wird ein Vorgang mit langer Ausführungszeit erstellt, der Ihre Unterhaltungen transkribiert und optional vertrauliche Informationen entfernt. Eine Audiodatei wird transkribiert, wenn die Unterhaltung nur ein audio_uri in der DataSource enthält. Andernfalls wird die angegebene transcript_uri gelesen und verwendet.

JSON-Text der Anfrage:

{ 
  "conversation": { 
    "data_source": { 
      "gcs_source": { "audio_uri": AUDIO_URI }
    }
  },
  "redaction_config": {
    "deidentify_template": DEIDENTIFY_TEMPLATE,
    "inspect_template": INSPECT_TEMPLATE
  },
  "speech_config": {
    "speech_recognizer": RECOGNIZER_NAME
  }
}

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

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/LOCATION_ID/conversations:upload"

Bulk-Import

REST

Ausführliche Informationen finden Sie unter dem API-Endpunkt conversations:ingest.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • PROJECT_ID: Ihre Google Cloud-Projekt-ID.
  • GCS_BUCKET_URI: Der Cloud Storage-URI, der auf den Bucket mit den Konversationsabschriften verweist. Kann ein Präfix enthalten. Beispiel: gs://BUCKET_NAME oder gs://BUCKET_NAME/PREFIX. Platzhalter werden nicht unterstützt.
  • MEDIUM: Je nach Datentyp auf PHONE_CALL oder CHAT festgelegt. Wenn nicht angegeben, ist der Standardwert PHONE_CALL.
  • AGENT_ID: Optional. Agent-ID für den gesamten Bucket.

HTTP-Methode und URL: 

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

JSON-Text anfordern:

{
  "gcsSource":  {
    "bucketUri": "GCS_BUCKET_URI",
    "bucketObjectType": "AUDIO"
  },
  "transcriptObjectConfig": { "medium": "PHONE_CALL" },
  "conversationConfig": {
    "agentId": "AGENT_ID",
    "agentChannel": "AGENT_CHANNEL",
    "customerChannel": "CUSTOMER_CHANNEL"
  }
}

Or

{
  "gcsSource":  {
    "bucketUri": "GCS_BUCKET_URI",
    "bucketObjectType": "TRANSCRIPT"
  },
  "transcriptObjectConfig": { "medium": "MEDIUM" },
  "conversationConfig": {"agentId": "AGENT_ID"}
}

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:


{
  "name": "projects/PROJECT_ID/locations/us-central1/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.contactcenterinsights.v1main.IngestConversationsMetadata",
    "createTime": "...",
    "request": {
      "parent": "projects/PROJECT_ID/locations/us-central1",
      "gcsSource": {
        "bucketUri": "GCS_BUCKET_URI",
        "bucketObjectType": "BUCKET_OBJECT_TYPE"
      },
      "transcriptObjectConfig": {
        "medium": "MEDIUM"
      },
      "conversationConfig": {
        "agentId": "AGENT_ID"
      }
    }
  }
}

Vorgang abfragen

Sowohl die UploadConversation- als auch die IngestConversation-Anfragen geben einen Vorgang mit langer Ausführungszeit zurück. Methoden mit langer Ausführungszeit sind asynchron und der Vorgang ist möglicherweise noch nicht abgeschlossen, wenn die Methode eine Antwort zurückgibt. Sie können den Vorgang abfragen, um seinen Status zu prüfen. Weitere Informationen und Codebeispiele finden Sie auf der Seite zu Vorgängen mit langer Ausführungszeit.

Speech-to-Text-Kontingente

Customer Experience Insights verwendet zwei verschiedene Speech-to-Text-APIs: BatchRecognize und GetOperation. Customer Experience Insights sendet eine BatchRecognize-Anfrage, um die Speech-to-Text-Transkription zu starten, und eine GetOperation-Anfrage, um zu prüfen, ob die Transkription abgeschlossen ist. Zum Starten von BatchRecognize-Vorgängen wird eine BatchRecognize-Anfrage gesendet, um ein Kontingent pro Minute und Region zu verwenden. Zum Überwachen der Vorgänge wird eine GetOperation-Anfrage gesendet, um ein minutengenaues Kontingent pro Region zu verwenden.

Für einen einzelnen UploadConversation-Aufruf wird in Customer Experience Insights eine BatchRecognize verbraucht, aber möglicherweise mehr GetOperation-Anfragen, je nach Dauer der Aufgabe. Beim Bulk-Import werden für Customer Experience Insights 100 Anfragen jedes Typs verwendet.