Oracle Digital Assistant bietet eine integrierte REST-Servicekomponente für Aufrufe, mit der Sie in Visual Dialog-Skills eine Anforderung an den Endpunkt eines REST-Service senden können. Bevor Sie die Anforderung von einer REST-Servicekomponente "Aufruf" ausführen können, müssen Sie den Endpunkt zuerst auf der Registerkarte "REST-Services" konfigurieren.

So fügen Sie einen REST-Service hinzu:

1. Klicken Sie in Oracle Digital Assistant auf , um das Seitenmenü zu öffnen, wählen Sie Einstellungen, API-Services aus, und klicken Sie dann auf die Registerkarte REST-Services.

2. Geben Sie diese allgemeinen Informationen an:

   Feld	Beschreibung
   Name	Ein eindeutiger Name, mit dem Sie den zu konfigurierenden Endpunkt einfach identifizieren können. Beispiel: Bei einer Termin-API können Sie die REST-Services "appointmentsUser" und "appointmentsUserEntry" nennen.
   Endpunkt	Der Endpunkt für den Zugriff auf den REST-Vorgang. Verwenden Sie geschweifte Klammern, um Pfadparameter abzugrenzen. Beispiel: https://example.com/appointments/{userId}. Stellen Sie bei Oracle Cloud Infrastructure-Endpunkten sicher, dass Sie den Endpunkt für die Region Ihres Mandanten verwenden. Hinweis: Verwenden Sie keine Abfrageparameter in diesem Feld. Wenn Sie einen Abfrageparameter zum Testen der API angeben möchten, können Sie die Eigenschaft Parameter (wie in der folgenden Tabelle beschrieben) für jede Methode verwenden, die Sie für den Endpunkt definieren.
   Beschreibung	Eine optionale Beschreibung, die den Zweck des Endpunkts erläutert. Beispiel: "Hinzufügen und Abrufen der Termine eines Benutzers".
   Authentifizierungstyp	Wählen Sie aus, wie der REST-Aufruf authentifiziert werden soll. Keine Authentifizierung erforderlich: Wählen Sie diese Option aus, wenn für den Service keine Authentifizierung erforderlich ist. Grundlegende Authentifizierung: Wählen Sie diese Option aus, wenn der Service eine Basisauthentifizierung verwendet. Sie müssen dann einen Benutzernamen und ein Kennwort angeben. API-Schlüssel: Wählen Sie diese Option aus, wenn der Service einen API-Schlüssel für die Authentifizierung verwendet. Sie müssen dann angeben, ob der Schlüssel als Pfadparameter oder Abfrageparameter übergeben werden muss, und Sie müssen den Schlüsselnamen und -wert angeben. Bearer-Token: Wählen Sie diese Option aus, wenn der Service ein Bearer-Token für die Authentifizierung verwendet. Sie müssen dann das Token angeben. OCI-Resource Principal: Wählen Sie diese Option aus, wenn Sie auf eine Oracle Cloud Infrastructure-API zugreifen.
   Privater Endpunkt	Wenn Sie einen privaten Endpunkt für den Service eingerichtet haben, auf den Sie zugreifen müssen, setzen Sie diesen Schalter auf die Position "Ein", und wählen Sie den privaten Endpunkt aus, den Sie verwenden. Hinweis: Sie können private Endpunkte für Services einrichten, die nicht öffentlich im Internet verfügbar gemacht werden. Siehe Privater Endpunkt.

3. Klicken Sie für jede Methode, die Sie für den Endpunkt konfigurieren möchten, auf + Methode hinzufügen, wählen Sie die Methode aus, und geben Sie die folgenden Informationen an:

   Feld	Beschreibung
   Inhaltstyp	Der Inhaltstyp, der im Anforderungstext enthalten ist. application/json und text/plain werden unterstützt.
   Text	Bei POST-, PUT- und PATCH-Anforderungen der Anforderungsbody, der mit der Anforderung gesendet werden soll. Sie können diesen Wert in der REST-Servicekomponente "Aufruf" überschreiben. Bei großen Anforderungsbodys klicken Sie auf Dialogfeld "Bearbeiten" verwenden, um einen Editor zu öffnen.
   Parameter	Sie können Pfad- und Abfrageparameter zum Testen der Anforderung hinzufügen. Sie können auch Pfad- und Abfrageparameter hinzufügen, um Standardwerte zu konfigurieren. Beachten Sie, dass die Skillentwickler diese Parameterwerte aus der Komponente "REST-Service aufrufen" überschreiben können. Das heißt, sie können Parameter in der Komponente hinzufügen, um die im REST-Service konfigurierten Werte außer Kraft zu setzen, und nicht die Parameter hinzufügen, in denen sie die in der REST-Servicekonfiguration festgelegten Werte verwenden möchten. Fügen Sie für die Pfadparameter im Endpunkt einen Parameter vom Typ Pfad hinzu, legen Sie den Schlüssel so fest, dass er mit dem Pfadparameter übereinstimmt, und legen Sie den gewünschten Wert fest. Fügen Sie für Abfrageparameter, die Sie in der REST-Anforderung übergeben möchten, einen Parameter vom Typ Abfrage hinzu, legen Sie den Schlüssel so fest, dass er mit dem Abfrageparameter übereinstimmt, und legen Sie den gewünschten Wert fest. Wenn der Authentifizierungstyp "API-Schlüssel" lautet und der Schlüssel als Abfrageparameter übergeben wird, fügen Sie hier keinen Abfrageparameter für diesen Schlüsselwert hinzu, da er bereits konfiguriert ist. Nachdem Sie den Parameter bearbeitet haben, klicken Sie auf , um den Parameter zur Liste hinzuzufügen. Hinweis: Der Abfrageparameterwert muss eine Zeichenfolge sein (Freemarker-Ausdrücke werden nicht unterstützt). Dieser Wert dient nur zum Testen der API. Der tatsächliche Wert, den Ihr Skill verwendet, muss in der Komponente REST-Service für Anrufe konfiguriert werden.
   Kopfzeilen	Fügen Sie alle Header hinzu, die Sie in der Anforderung übergeben möchten. Wenn der Authentifizierungstyp "API-Schlüssel" lautet und der Schlüssel in einem Header übergeben wird, fügen Sie hier keinen Header für diesen Schlüsselwert hinzu, da er bereits konfiguriert ist.
   Statische Antwort	Sie können die statische Antwortkonfiguration für Fälle verwenden, in denen Sie bei einem Fehler eine Fallback-Antwort benötigen. Sie können damit auch Mock-Daten für Entwicklungs- oder Testzwecke einrichten. Um eine statische Antwort zu konfigurieren, wählen Sie einen Rückgabestatuscode aus, und definieren Sie dann den Antwortbody. Alternativ können Sie die gewünschten Parameter und Header festlegen, auf Testanforderung klicken und dann auf Als statische Antwort speichern klicken, um Werte für die statische Antwort zu speichern.

4. Wenn Sie die Methode testen möchten, legen Sie den Pfad und die Abfrageparameter für den Pfad fest, legen Sie die erforderlichen Header fest, geben Sie bei Bedarf einen Anforderungsbody an, und klicken Sie auf Testanforderung. Ein Dialogfeld Antwortstatus mit dem Antwortstatus und dem Text wird angezeigt.

   Tipp:

   Sie können auf Als statische Antwort speichern klicken, um den Statuscode und den Text in den Feldern für statische Antworten zu speichern.

Wenn ein Skill einige Daten über einen Backend-Service abrufen oder aktualisieren muss, fügen Sie einen Status hinzu, der die REST-Servicekomponente "Aufrufen" verwendet. So verwenden Sie diese Komponente:

1. Konfigurieren Sie den Endpunkt auf der Seite Einstellungen > API-Services > REST-Services gemäß der Beschreibung unter REST-Service für einen Endpunkt hinzufügen. Hier definieren Sie den Endpunkt, den Authentifizierungstyp, die unterstützten Methoden, den Anforderungsbody, Pfad- und Abfrageparameter, Header und eine optionale statische Antwort.

2. Fügen Sie im gewünschten Ablauf im Ablaufdesigner des Skills den Status hinzu, wählen Sie Serviceintegration > Call Rest Service aus, geben Sie einen Namen an, und klicken Sie auf Einfügen.

3. Wählen Sie den REST-Service aus, den Sie auf der Seite "REST-Services" konfiguriert haben.

4. Wählen Sie die Methode aus.

5. Bei POST-, PUT- und PATCH-Anforderungen müssen Sie in der Regel einen Anforderungsbody angeben.

   Tipp:

   Wenn der Body FreeMarker-Ausdrücke enthält, können Sie Ausdruck auf "Ein" setzen, um die FreeMarker-Syntaxfarbe anzuzeigen. In diesem Fall ist die Validierung der JSON-Syntax jedoch deaktiviert.

6. Konfigurieren Sie im Abschnitt Parameter den Pfad und die Abfrageparameter, die Sie mit der Anforderung senden möchten.

   Die in der Komponente festgelegten Parameter überschreiben die in der REST-Servicekonfiguration festgelegten Parameter. Wenn Sie dagegen keinen Parameter in der Komponente festlegen, verwendet die Anforderung den Parameterwert aus der REST-Servicekonfiguration.

   Wenn Sie bei Abfrageparametern, die in der REST-Servicekonfiguration definiert sind, diesen Abfrageparameter nicht übergeben möchten, setzen Sie den Wert auf ${r""}.

7. Legen Sie alle Header fest, die Sie mit der Anforderung senden möchten.

   Die in der Komponente festgelegten Header überschreiben die in der REST-Servicekonfiguration festgelegten Header. Wenn Sie dagegen keinen Header in der Komponente festlegen, verwendet die Anforderung den Headerwert aus der REST-Servicekonfiguration.

8. Geben Sie an, welche Antwort nach Abschluss des Anrufs zurückgegeben werden soll:

   • Tatsächliche REST-API-Antwort verwenden: Hiermit wird die tatsächliche Antwort vom REST-Service zurückgegeben.

   • Immer statische REST-Antwort verwenden: Gibt die statische Antwort zurück, die auf der Registerkarte "REST-Services" konfiguriert ist. Diese Reaktion ist unter anderem in Entwicklungs- und Testphasen hilfreich.

   • Fallback mit statischer Antwort: Wenn die REST-Anforderung erfolgreich ist, wird die REST-Antwort zurückgegeben. Andernfalls wird die statische Antwort zurückgegeben, die auf der Registerkarte "REST-Services" konfiguriert ist.

   Wenn die REST-Servicekonfiguration keine statische Antwort enthält, können Sie nur die Option Istantwort verwenden auswählen.

9. Wählen Sie für die Ergebnisvariable die Zuordnungsvariable zum Speichern der Antwortdaten aus. Wenn sie noch nicht vorhanden ist, klicken Sie auf Erstellen, um sie zu erstellen.

   Nach Abschluss der Anforderung enthält die Zuordnung eine Eigenschaft responsePayload für den Antwortbody und eine Eigenschaft statusCode für den Statuscode. Wie der Antwortbody in der Variablen gespeichert wird, hängt davon ab, ob die Antwort ein JSON-Objekt, ein JSON-Array oder ein Nur-Text (Zeichenfolge) ist:

   • JSON-Objekt: Das Objekt wird in der Eigenschaft responsePayload gespeichert.

   • JSON-Array: Das Array wird in der Eigenschaft responsePayload.responseItems gespeichert.

   • Nur Text: Der Text wird in der Eigenschaft responsePayload.message gespeichert.

10. Geben Sie auf der Registerkarte Übergänge den nächsten Übergang und die Übergänge für die Aktionen Erfolg und Fehler an.

    • Die Aktion Erfolg wird ausgeführt, wenn die statusCode zwischen 100 und 299 liegt.

    • Die Aktion nicht erfolgreich wird ausgeführt, wenn statusCode 300 oder höher ist.

Weitere Informationen zu dieser Komponente finden Sie unter REST-Service aufrufen.