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 konfigurierten Endpunkt einfach identifizieren können. Beispiel: Für eine 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 zu trennen. 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.
   Beschreibung	Eine optionale Beschreibung, die den Zweck des Endpunkts erläutert. Beispiel: "Fügt Termine eines Benutzers hinzu und ruft sie ab."
   Authentifizierungstyp	Wählen Sie aus, wie der REST-Aufruf authentifiziert werden soll. Keine Authentifizierung erforderlich: Wählen Sie diese Option aus, wenn der Service keine Authentifizierung erfordert. Basisauthentifizierung: 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 zur 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 zur 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, aktivieren Sie diesen Schalter in der 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 dann die folgenden Informationen an:

   Feld	Beschreibung
   Contenttyp	Der Typ des Inhalts, der im Anforderungstext enthalten ist. application/json und text/plain werden unterstützt.
   Inhalt	Bei POST-, PUT- und PATCH-Anforderungen der Anforderungsbody, der mit der Anforderung gesendet werden soll. Sie können diesen Wert in der Komponente "REST-Service aufrufen" ü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, bei denen sie die in der REST-Servicekonfiguration festgelegten Werte verwenden möchten. Fügen Sie für die Pfadparameter im Endpunkt einen Parameter des Typs 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 des Typs 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. Klicken Sie nach dem Bearbeiten des Parameters auf , um den Parameter zur Liste hinzuzufügen.
   Header	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 eine Fallback-Antwort benötigen, wenn ein Fehler auftritt. Sie können damit auch Modelldaten für Entwicklungs- oder Testzwecke einrichten. Um eine statische Antwort zu konfigurieren, wählen Sie einen Rückgabestatuscode aus, und definieren Sie dann den Antworttext. 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 fest, die für den Pfad verwendet werden sollen, legen Sie die erforderlichen Header fest, geben Sie bei Bedarf einen Anforderungsbody an, und klicken Sie auf Anforderung testen. Das Dialogfeld Antwortstatus wird mit dem Antwortstatus und dem Text angezeigt.

   Tipp:

   Sie können auf Als statische Antwort speichern klicken, um den Statuscode und den Text in den statischen Antwortfeldern zu speichern.

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

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

2. Fügen Sie im Ablaufdesigner des Skills den Status hinzu, wählen Sie Serviceintegration > Rest-Service aufrufen 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. Für POST-, PUT- und PATCH-Anforderungen müssen Sie in der Regel einen Anforderungstext angeben.

   Tipp:

   Wenn der Body FreeMarker-Ausdrücke enthält, können Sie Ausdruck auf "Ein" setzen, um die Syntaxfärbung von FreeMarker anzuzeigen. Wenn Sie dies jedoch tun, ist die JSON-Syntaxvalidierung 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 für Abfrageparameter, die in der REST-Servicekonfiguration definiert sind, diesen Abfrageparameter nicht übergeben möchten, setzen Sie den Wert auf ${r""}.

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

   In der Komponente festgelegte Header überschreiben die Header, die in der REST-Servicekonfiguration festgelegt sind. 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 Aufrufs zurückgegeben werden soll:

   • Tatsächliche REST-API-Antwort verwenden: Gibt die tatsächliche Antwort vom REST-Service zurück.

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

   • Fallback mit statischer Antwort: Wenn die REST-Anforderung erfolgreich war, 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 Tatsächliche Antwort 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 eine 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 Antworttext in der Variablen gespeichert wird, hängt davon ab, ob die Antwort ein JSON-Objekt, ein JSON-Array oder ein einfacher 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 in der Registerkarte Transitions den nächsten Übergang und die Übergänge für die Aktionen success und failure an.

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

    • Die Aktion failure tritt auf, wenn die statusCode 300 und höher ist.

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