Komponentenpackage zu Skill hinzufügen

Sie fügen ein Komponentenpackage zu einem Skill hinzu, indem Sie einen Komponentenservice erstellen.

Bei Komponentenpackages, die Sie auf einem externen Server, auf Oracle Cloud Infrastructure Functions oder auf Oracle Mobile Hub hosten, ist ein Komponentenservice eine aktive Verbindung vom Skill zum Hostserver. Alternativ können Sie das Komponentenpackage hochladen und in Ihrer Oracle Digital Assistant-Instanz hosten. Dies wird als eingebetteter Komponentenservice bezeichnet.

Ein Komponentenservice hat zwei Funktionen:

Er fragt die Komponente ab, um die Packagemetadaten abzurufen, einschließlich der Namen der Komponenten, deren Eigenschaften und zulässigen Aktionen für jede Komponente. Nachdem dem Skill ein Service hinzugefügt wurde, können Sie diese Informationen auf der Registerkarte Komponenten anzeigen, auf die Sie zugreifen, indem Sie in der linken Navigationsleiste auf Komponenten klicken. Sie können diese Seite verwenden, um die Komponentennamen, Eigenschaften und Aktionen zu erhalten, die Sie zur Verwendung der Komponenten in Ihrem Dialogablauf benötigen.
Damit kann der Skill die Komponenten aufrufen.

Die JSON-Payload des Aufrufs, der von der Dialog-Engine an die Komponenten durchgeführt wird, umfasst Eingabeparameter, Variablenwerte, Kontext auf Benutzerebene und den Nachrichtentext des Benutzers. Die Komponente gibt die Ergebnisse zurück, indem die Werte vorhandener Variablen geändert oder neue Variablen hinzugefügt werden (oder beides). Die Dialog-Engine parst die zurückgegebene Payload und fährt fort.

Um ein benutzerdefiniertes Komponentenpackage zu einem Skill hinzuzufügen, gehen Sie zur Registerkarte Komponenten des Skills, und klicken Sie auf Service hinzufügen. Dadurch wird ein Dialogfeld zur Konfiguration des Service geöffnet.

Wie Sie den Service konfigurieren, hängt davon ab, wo Sie das Komponentenpackage hosten. In den folgenden Themen finden Sie die Anweisungen für jeden Typ:

Nachdem Sie den Service erstellt haben, können Sie die benutzerdefinierten Komponenten wie unter Benutzerdefinierte Komponenten beschrieben aus dem Dialogablauf aufrufen.

Wenn Sie ein Package in den eingebetteten Container hochladen, prüft Digital Assistant, ob das Package gültig ist. Das Package kann aus folgenden Gründen abgelehnt werden:

Es liegen JavaScript-Fehler vor.
Das Package enthält nicht alle Knotenmodulabhängigkeiten.
Ein Komponentenname enthält mehr als 100 Zeichen, beginnt mit System. oder enthält andere Zeichen als alphanumerische Zeichen und Unterstriche. In diesem Fall verläuft das Erstellen des Service nicht erfolgreich.
Ihre Instanz weist bereits die maximale Anzahl von eingebetteten Komponentenservices auf.
Die TGZ-Datei ist zu groß. Dies kommt in der Regel vor, wenn die Datei .npmignore keinen *.tgz-Eintrag enthält. Daher wird jedes Mal, wenn Sie die Dateien verpacken, eine verschachtelte Kopie der vorhandenen TGZ-Datei hinzugefügt.

Weitere Informationen zu diesen Verifizierungsprüfungen finden Sie unter Eingebetteten Komponentenservice hinzufügen.

Eingebetteten Komponentenservice hinzufügen

Wenn Sie das benutzerdefinierte Komponentenpackage in Ihrer Oracle Digital Assistant-Instanz hosten möchten, gehen Sie wie folgt vor:

Package für einen eingebetteten Containerservice vorbereiten

Wenn Sie das benutzerdefinierte Komponentenpackage in Oracle Digital Assistant als eingebetteten Komponentenservice hosten möchten, müssen Sie zuerst die benutzerdefinierten Komponenten in eine TGZ-Datei verpacken. Diese Datei laden Sie dann beim Erstellen des eingebetteten Komponentenservice hoch.

Diese TGZ-Datei, die Sie mit bots-node-sdk pack verpacken, muss die in Benutzerdefinierte Komponenten implementieren beschriebenen Assets und Strukturen enthalten. Sie muss außerdem alle Knotenmodule enthalten, von denen sie abhängig ist (bots-node-sdk pack führt diese Aufgabe für Sie aus).

Hinweis

Die zulässige Anzahl eingebetteter benutzerdefinierter Komponentenservices einer Instanz ist begrenzt. Wenn Sie das Limit nicht kennen, bitten Sie den Serviceadministrator, den Parameter embedded-custom-component-service-count für Sie abzurufen, wie unter Servicelimits in der Infrastructure-Konsole anzeigen beschrieben. Wenn Sie versuchen, einen Komponentenservice hinzuzufügen, nachdem Sie dieses Limit erreicht haben, verläuft das Erstellen des Service nicht erfolgreich.

So bereiten Sie ein Package für das Hochladen in den eingebetteten Containerservice vor:

Stellen Sie sicher, dass Sie über die neueste Version der Bots-Node.js-Befehlszeilentools verfügen.

Der eingebettete Container erfordert, dass die TGZ-Datei alle dependencies enthält. Bei früheren Versionen sind die dependencies nicht in der Datei enthalten. Mit dem Befehl, mit dem Sie die TGZ-Datei erstellen, wird sichergestellt, dass Ihre package.json-Datei einen bundledDependencies-Knoten enthält, der alle abhängigen Module auflistet, die in die TGZ-Datei aufgenommen werden müssen.
Führen Sie in dem Verzeichnis, in dem die Datei main.js enthalten ist, den folgenden Befehl für jedes Modul aus, von dem Ihr Package abhängig ist. Dies ist für devDependencies wie das Bots-Node.js-SDK nicht erforderlich.

Dieser Befehl fügt das Modul zum Ordner node_modules sowie als Abhängigkeit in package.json hinzu.
```
npm install <module>
```
Wenn Ihre package.json-Datei bereits alle Abhängigkeiten benennt, können Sie stattdessen npm install ausführen.
Stellen Sie sicher, dass der Ordner der obersten Ebene eine .npmignore-Datei mit einem *.tgz-Eintrag enthält. Beispiel:
```
*.tgz
spec
service-*
```
Andernfalls fügen Sie jedes Mal, wenn Sie die Dateien in eine TGZ-Datei verpacken, die TGZ-Datei ein, die bereits im Ordner der obersten Ebene vorhanden ist, sodass Ihre TGZ-Datei ihre Größe verdoppelt. Nachdem Sie die Dateien ein paar Mal verpackt haben, wird die TGZ-Datei zu groß für den Upload in den Container.
Gehen Sie wie folgt vor:
```
bots-node-sdk pack
```
Dieser Befehl validiert das Komponentenpackage, nimmt ggf. devDependencies darin auf und erstellt dann eine TGZ-Datei, die Sie hochladen, wenn Sie einen eingebetteten Komponentenservice über die Registerkarte Komponenten des Skills erstellen. Beachten Sie, dass die Dateien, die Sie als dependencies aufgelistet haben, als bundledDependencies enthalten sind, mit Ausnahme von Bots Node SDK und Express, die devDependencies sind.

Ihr Paket sollte mit Node 14.17.0 kompatibel sein.

Weitere Informationen zum Befehl pack finden Sie unter https://github.com/oracle/bots-node-sdk/blob/master/bin/CLI.md.

Package hochladen, um einen eingebetteten Komponentenservice zu erstellen

Nachdem Sie ein benutzerdefiniertes Komponentenpackage in eine TGZ-Datei verpackt haben, können Sie es hochladen, um über die Registerkarte Komponenten des Skills einen eingebetteten Komponentenservice zu erstellen.

Weitere Informationen zum Erstellen der TGZ-Datei finden Sie unter Package für einen eingebetteten Containerservice vorbereiten.

Hinweis

Wenn Sie das Package in den eingebetteten Komponentenservice hochladen, wird es in Oracle Functions Service bereitgestellt. Wenn Ihre Instanz auf Oracle Cloud Platform bereitgestellt ist (wie alle Instanzen der Version 19.4.1), wird der Service stattdessen in der Digital Assistant-Instanz bereitgestellt.

So erstellen Sie den eingebetteten Komponentenservice:

Klicken Sie im Skill auf Komponenten .
Klicken .
Wählen Sie Integrierter Container aus.
Klicken Sie auf Komponentenpackagedatei hochladen, und zeigen Sie auf die hochzuladende TGZ-Datei, oder ziehen Sie die Datei in das Feld Packagedatei.
(Optional) Wenn Sie context.logger()-Anweisungen einer benutzerdefinierten Komponente an das Servicelog senden möchten, aktivieren Sie die Option Komponentenlogging aktivieren. Diese Option kann nur in Instanzen von Oracle Digital Assistant aktiviert werden, die auf Oracle Cloud Infrastructure bereitgestellt wurden (auch als Cloud-Infrastruktur der 2. Generation bezeichnet).

Sie können das Log auf der Registerkarte Komponenten anzeigen, indem Sie auf Diagnose > Logs anzeigen klicken.

Hinweis

Der Skill speichert einen Logeintrag für zwei Tage. Wenn Sie einen eingebetteten benutzerdefinierten Komponentenservice löschen, werden die Logeinträge des Skills für diesen Service gelöscht.
Klicken Sie auf Erstellen.

Digital Assistant lädt die TGZ-Datei hoch und erstellt den eingebetteten Komponentenservice. Während des Uploads prüft Digital Assistant, ob das Package gültig ist, und kann das Package aus Gründen ablehnen, die später in diesem Abschnitt beschrieben werden.

Nachdem Sie die TGZ-Datei hochgeladen haben, wird der benutzerdefinierte Komponentenservice erstellt, und seine Komponenten werden bereitgestellt. Wenn auf der Seite Komponenten nach dem Hochladen der TGZ-Datei eine Meldung angezeigt wird, dass auf ein Deployment gewartet wird, bedeutet dies, dass der Service erstellt wurde, jedoch noch nicht verfügbar ist. Sobald der Service verfügbar ist, werden die Deployment-Metadaten anstelle der Nachricht angezeigt, dass auf ein Deployment gewartet wird.
Stellen Sie sicher, dass die Option Service aktiviert aktiviert ist.

Während des Uploads kann Digital Assistant das Package ablehnen. Nachstehend finden Sie Gründe für eine Ablehnung und Möglichkeiten, die Probleme zu lösen:

JavaScript enthält Syntaxfehler: Wenn der JavaScript-Code einer Komponente Syntaxfehler enthält, wird diese Komponente nicht zum Container hinzugefügt. Diese Situation führt zu folgender Fehlermeldung:
```
Error Message: failed to start service built: Invalid component
      path:
```
Zeigen Sie die Komponentendateien in einem Editor an, der Syntaxfehler erkennt. Versuchen Sie außerdem, das Package auf einem lokalen Server zu hosten, der Fehlermeldungen an ein Konsolenlog sendet.

Ein weiterer Grund für diese Meldung ist möglicherweise, dass das Package nicht alle Knotenmodulabhängigkeiten enthält. Siehe nächstes Element in dieser Liste.
Fehlende Knotenmodule: Wenn das Package nicht alle Knotenmodulabhängigkeiten enthält, wird dieselbe Fehlermeldung wie oben ausgegeben:
```
Error Message: failed to start service built: Invalid component
      path:
```
Weitere Informationen zum Einschließen von Knotenmodulabhängigkeiten finden Sie unter Package für einen eingebetteten Containerservice vorbereiten.
Komponentenname ist zu lang: Wenn ein Komponentenname mehr als 100 Zeichen enthält, mit System. beginnt oder andere Zeichen als alphanumerische Zeichen und Unterstriche enthält, verläuft das Erstellen des Service nicht erfolgreich.

Ändern Sie den Namen im JavaScript-Code der Komponente, erstellen Sie ein neues Package, und laden Sie es erneut hoch.
Limit für Komponentenservice überschritten: Wenn Ihre Instanz bereits die maximale Anzahl von eingebetteten benutzerdefinierten Komponentenservices aufweist, verläuft das Erstellen des Service nicht erfolgreich. Fragen Sie den Serviceadministrator nach dem embedded-custom-component-service-count-Limit, wie unter Servicelimits in der Infrastructure-Konsole anzeigen beschrieben.

Wenn Sie das Limit erhöhen müssen, können Sie eine Erhöhung beantragen. Siehe Erhöhung des Servicelimits beantragen.
TGZ-Datei ist zu groß: Dies kommt in der Regel vor, wenn die Datei .npmignore keinen *.tgz-Eintrag enthält. Daher wird jedes Mal, wenn Sie die Dateien verpacken, eine verschachtelte Kopie der vorhandenen TGZ-Datei hinzugefügt.

Wenn der Ordner der obersten Ebene eine .npmignore-Datei mit *.tgz enthält, wird die vorherige Version der TGZ-Datei beim Aktualisieren des Packages nicht mit aufgenommen.

Wenn Sie context.logger()-Anweisungen einer benutzerdefinierten Komponente an das Servicelog senden möchten, aktivieren Sie die Option Komponentenlogging aktivieren. Diese Option kann nur in Instanzen von Oracle Digital Assistant aktiviert werden, die auf Oracle Cloud Infrastructure bereitgestellt wurden (auch als Cloud-Infrastruktur der 2. Generation bezeichnet).

Wenn Komponentenlogging aktivieren aktiviert ist, können Sie auf die Schaltfläche Diagnose klicken, damit der Service zur Problemdiagnose auf Ansichtslogs und Absturzberichte zugreifen kann.

Wählen Sie Logs anzeigen aus, um Nachrichten anzuzeigen, die die benutzerdefinierte Komponente an context.logger() sendet. Dieses Features ist nur in Instanzen von Oracle Digital Assistant verfügbar, die auf Oracle Cloud Infrastructure bereitgestellt wurden (auch als Cloud-Infrastruktur der 2. Generation bezeichnet). Der Schalter Komponentenlogging aktivieren muss aktiviert sein, damit das Log diese Nachrichten enthält.
Wählen Sie Absturzbericht anzeigen aus, um Details dazu anzuzeigen, was zu einem Absturz des Containers geführt hat.

Nachdem Sie den Service erstellt haben, können Sie die benutzerdefinierten Komponenten wie unter Benutzerdefinierte Komponenten beschrieben aus dem Dialogablauf aufrufen.

Oracle Functions-Service hinzufügen

Sie können Ihre benutzerdefinierten Komponenten in Oracle Cloud Infrastructure Functions bereitstellen und sie als Oracle Function-Service einem Skill hinzufügen.

So fügen Sie einen Oracle Functions-Service hinzu:

Sie müssen die URL der Funktion kennen. Ein Benutzer mit Funktionsentwicklungsberechtigungen kann die URL aus der Integrationskonsole für Sie abrufen.
1. Melden Sie sich bei der Integrationskonsole an.
2. Klicken Sie oben links auf , um das Navigationsmenü zu öffnen, klicken Sie auf Entwicklerservices > Functions, und wählen Sie dann das Compartment aus, das für die Funktionsentwicklung eingerichtet wurde.
3. Klicken Sie auf die Anwendung.
4. Klicken Sie im Abschnitt Functions auf das Symbol Mehr für Ihre Funktion, und klicken Sie dann auf Aufrufendpunkt kopieren. Skillentwickler benötigen diesen Wert, um das benutzerdefinierte Komponentenpackage als Komponentenservice in einem Skill hinzuzufügen.
Ein Skillentwickler fügt den Komponentenservice zu einem Skill in Oracle Digital Assistant hinzu. Melden Sie sich bei Oracle Digital Assistant an, öffnen Sie den Skill, und klicken Sie auf Komponenten .
Klicken .
Geben Sie einen Namen und eine Beschreibung für den Service an.
Wählen Sie Oracle-Funktion aus.
Geben Sie im Textfeld URL die Aufrufendpunkt-URL ein, die Sie auf der Seite Entwicklerservices > Functions in der Infrastructure-Konsole kopiert haben, während Sie die Schritte unter Benutzeraccount für Oracle Functions einrichten ausgeführt haben.
Klicken Sie auf Erstellen.

Wenn der Fehler "Service kann nicht erstellt werden" angezeigt wird, gehen Sie in der Infrastructure-Konsole zu Entwicklerservices > Functions, wählen Sie das Compartment aus, klicken Sie auf die Anwendung, und klicken Sie im Menü Ressourcen auf Logs. Aktivieren Sie dann das Log für die Funktion, wiederholen Sie das Deployment, und prüfen Sie die Logs (klicken Sie auf den Lognamen, um das Log anzuzeigen). Weitere Informationen zu Logs finden Sie unter Funktionslogs speichern und anzeigen in der Oracle Cloud Infrastructure-Dokumentation.

Wenn ein solcher Fehler angezeigt wird, liegt das daran, dass der Ordner nicht über die richtigen Berechtigungen verfügt. Verwenden Sie auf dem lokalen Rechner chmod 775, um die Berechtigungen des Ordners zu ändern. Wiederholen Sie das Deployment dann:
```
"Error: EACCES: permission denied, stat
'/function/components/hello.world.js.js'"
```
Wenn ein solcher Fehler angezeigt wird, löschen Sie auf dem lokalen Rechner node_modules, führen Sie npm install aus, und wiederholen Sie das Deployment.
```
"Error: Cannot find module '@fnproject/fdk'"
```
Stellen Sie sicher, dass die Option Service aktiviert aktiviert ist.

Nachdem Sie den Service erstellt haben, können Sie die benutzerdefinierten Komponenten wie unter Benutzerdefinierte Komponenten beschrieben aus dem Dialogablauf aufrufen.

Externen Komponentenservice hinzufügen

Sie können Ihre benutzerdefinierten Komponenten auf Ihrem eigenen Node.js-Server hosten und sie als externen Komponentenservice zu einem Skill hinzufügen.

Tipp:

Sie können die Option für den externen Service während der Entwicklung verwenden, wie unter Komponentenservice in einer Entwicklungsumgebung ausführen beschrieben.

So fügen Sie einen externen Komponentenservice hinzu:

Klicken Sie im Skill auf Komponenten .
Klicken .
Wählen Sie Extern aus.
Geben Sie im Textfeld Metadaten-URL die URL ein, die auf den GET-Endpunkt zeigt, der die Komponentenliste zurückgibt.
Geben Sie den Benutzernamen und das Kennwort für den Service ein.
Klicken Sie auf Erstellen.
Stellen Sie sicher, dass die Option Service aktiviert aktiviert ist.

Nachdem Sie den Service erstellt haben, können Sie die benutzerdefinierten Komponenten wie unter Benutzerdefinierte Komponenten beschrieben aus dem Dialogablauf aufrufen.

Mobile Hub-Komponentenservice hinzufügen

Sie können Ihre benutzerdefinierten Komponenten in Oracle Mobile Hub hosten und als Oracle Mobile Cloud-Komponentenservice zu einem Skill hinzufügen. Benutzerdefinierte Komponenten, die in Mobile Hub gehostet werden, können mittels Connectors, die von einem Mobile Hub-Backend gesteuert werden, mit Remoteservices integriert werden. Sie haben Zugriff auf die Mobile Hub-Plattform-APIs.

Weil das Backend, das den benutzerdefinierten Code hostet, die Authentifizierung für die benutzerdefinierten Komponenten verarbeitet, müssen Sie die Seite "Einstellungen" des Backends einsehen, um die Informationen zu erhalten, die Sie zur Konfiguration benötigen.

So fügen Sie einen Komponentenservice für das Mobile Hub-Backend hinzu:

Klicken Sie im Skill auf Komponenten .
Klicken .
Wählen Sie Oracle Mobile Cloud aus.
Geben Sie die eindeutige ID, die dem Mobile Hub-Backend zugewiesen ist, in das Feld Backend-ID ein. Diese ID wird im REST-Header jedes Aufrufs vom Skill übergeben.
Geben Sie im Feld MetadataURL den /components-Endpunkt aus der benutzerdefinierten Code-API ein. Beispiel: http://<server>:<port>/mobile/custom/ccPackage/components.
Wählen Sie Anonymen Zugriff verwenden aus, wenn der Service eine anonyme Anmeldung zulässt. Wenn Sie diese Option auswählen, geben Sie den anonymen Schlüssel ein. Dies ist eine eindeutige Zeichenfolge, mit der Ihre App auf anonyme APIs zugreifen kann, ohne einen verschlüsselten Benutzernamen und ein verschlüsseltes Kennwort zu senden. Stattdessen wird der anonyme Schlüssel übergeben. Sie finden den anonymen Schlüssel auf der Seite "Einstellungen" des Backends in Mobile Hub. (Möglicherweise müssen Sie auf Anzeigen klicken.)

Wenn der Komponentenservice eine Anmeldung erfordert (d.h. anonymer Zugriff ist nicht zulässig), geben Sie den Benutzernamen und das Kennwort ein.
Wenn der Service bestimmte Parameter erfordert, klicken Sie auf HTTP-Header hinzufügen, und definieren Sie die Schlüssel/Wert-Paare für die Header.
Klicken Sie auf Erstellen.
Stellen Sie sicher, dass die Option Service aktiviert aktiviert ist.

Nachdem Sie den Service erstellt haben, können Sie die benutzerdefinierten Komponenten wie unter Benutzerdefinierte Komponenten beschrieben aus dem Dialogablauf aufrufen.

Oracle Cloud Infrastructure - Dokumentation