ParseDialogflowRequest-Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Richtliniensymbol

Übersicht

Die ParseDialogflowRequest-Richtlinie ermöglicht die Einbindung von Dialogflow in Apigee. Weitere Informationen finden Sie unter Apigee in Contact Center AI einbinden.

Diese Richtlinie ist eine erweiterbare Richtlinie und die Verwendung dieser Richtlinie kann je nach Apigee-Lizenz Auswirkungen auf die Kosten oder die Nutzung haben. Informationen zu Richtlinientypen und Auswirkungen auf die Nutzung finden Sie unter Richtlinientypen.

Die ParseDialogflowRequest-Richtlinie verarbeitet den WebhookRequest von einem Dialogflow-Agent, bevor die Anfragedaten an Ihre Backend-Systeme gesendet werden. Die Richtlinie extrahiert Daten aus dem WebhookRequest in die Ablaufvariablen, die Ihnen für die Dauer des gesamten API-Aufrufs zur Verfügung stehen. Sie können die Variablen in nachfolgenden Callouts und Suchvorgängen oder in der orchestrierten Logik verwenden. Diese Richtlinie ist besonders hilfreich, wenn der Dialogflow-Agent mit Ihren Legacy-Back-End-Systemen interagieren soll. Bevor Sie die Daten des Agents an die Backend-Systeme senden, haben Sie die Möglichkeit, diese zu parsen und so zu strukturieren, dass sie von den Backend-Systemen verarbeitet werden können.

Wenn Sie Backend-Dienstintegrator sind, ist das Format der Dialogflow-WebhookRequest für Sie nicht relevant. Die vorkonfigurierte ParseDialogflowRequest-Richtlinie verarbeitet die Anfragedaten automatisch.

Für den Zugriff auf die WebhookRequest des Dialogflow-Agents in Apigee müssen Sie für die Webhook-URL (Auftragsausführung) des Agents den in Apigee konfigurierten ProxyEndPoint festlegen. Der ProxyEndPoint sollte öffentlich zugänglich sein. Weitere Informationen finden Sie unter Anforderungen an Webhook-Dienste.

<ParseDialogflowRequest>

Definiert eine ParseDialogflowRequest-Richtlinie.

Standardwert
Erforderlich? Erforderlich
Typ Komplexes Objekt
Übergeordnetes Element
Untergeordnete Elemente <DialogflowVersion>
<DisplayName>
<VariablePrefix>

Die folgende Tabelle enthält eine allgemeine Beschreibung der untergeordneten Elemente speziell der ParseDialogflowRequest-Richtlinie:

Untergeordnetes Element Erforderlich? Beschreibung
<VariablePrefix> Optional Legt ein benutzerdefiniertes Präfix für die Ablaufvariablen fest.
<DialogflowVersion> Optional Gibt die Dialogflow-Version an.

Beispiel

Das folgende Beispiel zeigt eine Webhook-Anfrage, die zugehörige ParseDialogflowRequest-Richtlinie und die Ablaufvariablen, die nach dem Anwenden der Richtlinie generiert wurden:

Syntax

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ParseDialogflowRequest continueOnError="false" enabled="true"
        name="POLICY_NAME">
    <!-- The display name for this policy -->
    <DisplayName>DISPLAY_NAME</DisplayName>
    <!-- The optional prefix to be added to all variables created from the
         Dialogflow Webhook request. Note that all variables created from the
         WebhookRequest object will be within a container named
         "google.dialogflow" -->
    <VariablePrefix>CUSTOM_PREFIX</VariablePrefix>
    <!-- The version of Dialogflow for which this request policy is written up.
         This policy supports only the CX version. This element is optional and
         defaults to CX if unspecified -->
    <DialogflowVersion>DIALOGFLOW_VERSION</DialogflowVersion>
</ParseDialogflowRequest>

Webhook-Anfrage

Das folgende Beispiel zeigt die Webhook-Anfrage (im JSON-Format) von einem Dialogflow-Agent.

{
    "fulfillmentInfo": {
        "tag": "check-claim-status"
    },
    "sessionInfo": {
        "session": "projects/apigee-test/locations/global/agents/ea45003d-3f5c-46ba-ac6b-f4c6dc8db707/sessions/5ea2e8-7c1-cf4-2cf-8e4d89e72",
        "parameters": {
            "claimId": "1234",
            "policyId": "abcd"
        }
    },
    "sentimentAnalysisResult": {
      "score": -0.7,
      "magnitude": 0.7
  }
}

Informationen zu den verschiedenen Feldern, die Sie in der Anfrage konfigurieren können, finden Sie unter WebhookRequest.

Im nächsten Beispiel wird die Konfiguration der ParseDialogflowRequest-Richtlinie gezeigt.

ParseDialogflowRequest-Richtlinie

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ParseDialogflowRequest continueOnError="false" enabled="true"
        name="DialogflowRequest-InsuranceAgent">
    <DisplayName>Insurance Agent Webhook Request Policy</DisplayName>
    <VariablePrefix>my-prefix</VariablePrefix>
    <DialogflowVersion>CX</DialogflowVersion>
</ParseDialogflowRequest>

Im folgenden Beispiel werden die von der Richtlinie erstellten Ablaufvariablen dargestellt.

Ablaufvariablen

google.dialogflow.my-prefix.fulfillment.tag = "check-claim-status"
google.dialogflow.my-prefix.session.id = "5ea2e8-7c1-cf4-2cf-8e4d89e72"
google.dialogflow.my-prefix.session.project.id = "apigee-test"
google.dialogflow.my-prefix.session.agent.id = "ea45003d-3f5c-46ba-ac6b-f4c6dc8db707"
google.dialogflow.my-prefix.session.parameters.claimId = "1234"
google.dialogflow.my-prefix.session.parameters.policyId = "abcd"
google.dialogflow.my-prefix.sentimentAnalysisResultScore = -0.7
google.dialogflow.my-prefix.sentimentAnalysisResultMagnitude = 0.7

Alle generierten Ablaufvariablen beginnen mit google.dialogflow, gefolgt von einem Präfix (google.dialogflow), das im Element <VariablePrefix> angegeben wird.

Dieses Element hat folgende Attribute, die allen Richtlinien gemeinsam sind:

Attribut Standard Erforderlich? Beschreibung
name - Erforderlich

Der interne Name der Richtlinie. Der Wert des Attributs name kann Buchstaben, Ziffern, Leerzeichen, Bindestriche, Unterstriche und Punkte enthalten. Dieser Wert darf 255 Zeichen nicht überschreiten.

Optional können Sie das Element <DisplayName> verwenden, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen Namen in einer natürlichen Sprache zu versehen.

continueOnError false Optional Legen Sie false fest, um einen Fehler zurückzugeben, wenn eine Richtlinie fehlschlägt. Dies ist für die meisten Richtlinien das erwartete Verhalten. Legen Sie true fest, damit die Ablaufausführung auch nach dem Fehlschlagen einer Richtlinie fortgesetzt wird. Weitere Informationen:
enabled wahr Optional Setzen Sie den Wert auf true, um die Richtlinie zu erzwingen. Legen Sie false fest, um die Richtlinie zu deaktivieren. Die Richtlinie wird nicht durchgesetzt, selbst wenn sie mit einem Ablauf verknüpft ist.
async   false Verworfen Dieses Attribut wurde verworfen.

Verweis auf untergeordnetes Element

In diesem Abschnitt werden die untergeordneten Elemente von <ParseDialogflowRequest> beschrieben.

<DisplayName>

Wird zusätzlich zum Attribut name verwendet, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen, natürlicher klingenden Namen zu versehen.

Das Element <DisplayName> ist für alle Richtlinien gleich.

Standardwert
Erforderlich? Optional. Wenn Sie <DisplayName> weglassen, wird der Wert des Attributs name der Richtlinie verwendet.
Typ String
Übergeordnetes Element <PolicyElement>
Untergeordnete Elemente Keine

Das <DisplayName>-Element verwendet die folgende Syntax:

Syntax

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Beispiel

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

Das <DisplayName>-Element hat keine Attribute oder untergeordneten Elemente.

<VariablePrefix>

Legt ein benutzerdefiniertes Präfix für die Ablaufvariablen fest. Der in diesem Element angegebene Wert wird allen Variablennamen, die von der ParseDialogflowRequest-Richtlinie generiert werden, vorangestellt. Standardmäßig haben alle von der Richtlinie generierten Variablen das Präfix google.dialogflow. Wenn Sie das Element VariablePrefix festlegen, wird nach google.dialogflow das benutzerdefinierte Präfix hinzugefügt. Der Variablenname beginnt dann mit google.dialogflow.CUSTOM_PREFIX.

Wenn Sie das Element VariablePrefix nicht festlegen, wird dem Variablennamen nur google.dialogflow vorangestellt.

Standardwert
Erforderlich? Optional
Typ String
Übergeordnetes Element <ParseDialogflowRequest>
Untergeordnete Elemente Keine
Das <VariablePrefix>-Element verwendet die folgende Syntax:

Syntax

<VariablePrefix>VARIABLE_PREFIX</VariablePrefix>

Beispiel

Im folgenden Beispiel wird für VariablePrefix der Wert my-prefix festgelegt:

<VariablePrefix>my-custom-prefix</VariablePrefix>

Gemäß dieser Konfiguration beginnen alle Variablennamen mit google.dialogflow.my-custom-prefix.

<DialogflowVersion>

Gibt die Dialogflow-Version an. Die ParseDialogflowRequest-Richtlinie unterstützt nur die CX-Version. Wenn Sie dieses Element nicht in der Richtlinie angeben, wird die Version standardmäßig auf CX gesetzt.

Standardwert
Erforderlich? Optional
Typ String
Übergeordnetes Element
Untergeordnete Elemente Keine
Das <DialogflowVersion>-Element verwendet die folgende Syntax:

Syntax

<DialogflowVersion>DIALOGFLOW_VERSION</DialogflowVersion>

Beispiel

Im folgenden Beispiel wird für DialogflowVersion der Wert CX festgelegt:

<DialogflowVersion>CX</DialogflowVersion>

Fehlercodes

In diesem Abschnitt werden die zurückgegebenen Fehlercodes und Fehlermeldungen beschrieben, die von Apigee festgelegt werden, wenn die Richtlinie einen Fehler auslöst. Diese Informationen sind wichtig, wenn Sie Fehlerregeln zur Verarbeitung von Fehlern entwickeln. Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen und Fehler beheben.

Laufzeitfehler

Diese Fehler können bei Ausführung der Richtlinie auftreten.

Fehlercode HTTP-Status Ursache Korrektur
steps.parsedialogflowrequest.InvalidSessionInfo 500 Dieser Fehler tritt auf, wenn eine Dialogflow-Anfrage ein ungültiges Feld sessionInfo.session enthält. Mit diesem Feld kann ein Webhook eine Sitzung identifizieren. Informationen zum unterstützten Sitzungsformat finden Sie unter SessionInfo-Klasse.
steps.parsedialogflowrequest.MalformedInput 500 Dieser Fehler tritt auf, wenn die JSON-Datei für diese Richtlinie ungültig oder fehlerhaft ist.

Bereitstellungsfehler

Diese Fehler können auftreten, wenn Sie einen Proxy mit dieser Richtlinie bereitstellen.

Fehlername Ursache Korrektur
UnsupportedOperation Dieser Fehler tritt auf, wenn Sie im DialogflowVersion-Element eine nicht unterstützte Dialogflow-Version angegeben haben. Die ParseParseDialogflowRequest-Richtlinie unterstützt nur die Version CX.

Fehlervariablen

Wenn in einer Richtlinie Ausführungsfehler auftreten, generiert Apigee Fehlermeldungen. Sie können sich diese Fehlermeldungen in der Fehlerantwort ansehen. Häufig sind vom System generierte Fehlermeldungen im Kontext Ihres Produkts möglicherweise nicht relevant. Sie können die Fehlermeldungen basierend auf dem Fehlertyp anpassen, um die Nachrichten aussagekräftiger zu machen.

Zum Anpassen der Fehlermeldungen können Sie entweder Fehlerregeln oder die RaiseFault-Richtlinie verwenden. Informationen zu Unterschieden zwischen Fehlerregeln und der RaiseFault-Richtlinie finden Sie unter FaultRules-Richtlinie im Vergleich zur RaiseFault-Richtlinie. Prüfen Sie, ob Bedingungen mit dem Element Condition in den Fehlerregeln und in der RaiseFault-Richtlinie verwendet werden. Apigee stellt Fehlervariablen bereit, die für jede Richtlinie eindeutig sind. Die Werte der Fehlervariablen werden festgelegt, wenn eine Richtlinie Laufzeitfehler auslöst. Mit diesen Variablen können Sie nach bestimmten Fehlerbedingungen suchen und entsprechende Maßnahmen ergreifen. Weitere Informationen zum Prüfen von Fehlerbedingungen finden Sie unter Bedingungen erstellen.

In der folgenden Tabelle werden die für diese Richtlinie spezifischen Fehlervariablen beschrieben.

Variablen Wo Beispiel
fault.name="FAULT_NAME" FAULT_NAME ist der Name des Fehlers, wie er in der Tabelle der Laufzeitfehler aufgeführt ist. Der Fehlername ist der letzte Teil des Fehlercodes. fault.name Matches "UnresolvedVariable"
ParseDialogflowRequest.POLICY_NAME.failed POLICY_NAME ist der benutzerdefinierte Name der Richtlinie, die den Fehler ausgelöst hat. ParseDialogflowRequest.My-Parse-Dialogflow-Req.failed = true
Weitere Informationen zu Richtlinienfehlern finden Sie unter Was Sie über Richtlinienfehler wissen müssen.

Weitere Informationen

Referenzimplementierungen von Apigee-Proxys und freigegebenen Abläufen, die die Nutzung der ParseDialogflowRequest-Richtlinie veranschaulichen, sind auf Apigee GitHub verfügbar. Weitere Informationen finden Sie unter Referenzimplementierungen für dialogorientierte KI.