Dropbox-Connector-Tutorial für das Jitterbit Connector SDK

Einführung

Dieses Tutorial behandelt den Dropbox-Connector, einen vollständigen Connector, der mit dem Jitterbit Connector SDK erstellt wurde. Obwohl er voll funktionsfähig ist, ist dieser Connector nicht für den produktiven Einsatz gedacht. Er dient als Ausgangspunkt für die Entwicklung von Connectors, da er nicht über alle Tests und die Fehlerbehandlung verfügt, die in einem Produktionsconnector erwartet werden würden.

Vorausgesetzt, Sie haben die Voraussetzungen erfüllt, können Sie das Beispiel herunterladen, es erstellen und paketieren, es auf einem Jitterbit-Privatagenten installieren und in einem Projekt verwenden, um eine Verbindung zu Dropbox herzustellen und Dateien zu verschieben.

Das Tutorial setzt voraus, dass Sie mit Jitterbit und Jitterbit Integration Studio vertraut sind. Wenn Sie mit dem Integration Studio nicht vertraut sind, lesen Sie bitte unsere Integration Studio Dokumentation, insbesondere den Integration Studio Schnellstartleitfaden.

Beispiel-Dropbox-Connector abrufen

Wenn Sie dies noch nicht getan haben, besteht der erste Schritt darin, den Dropbox-Connector aus dem GitHub-Repository zu klonen. Sie können dies über die GitHub-Website oder durch Ausführen dieser Befehle tun:

git clone https://github.com/jitterbit/dropbox-connector.git
cd dropbox-connector

Registrieren Sie Ihren Beispiel-Dropbox-Connector

Sie benötigen bestimmte Informationen, bevor Sie den Connector erstellen und paketieren können: ein Dropbox-Login und eine Anwendung, einen Harmony-Kontobenutzernamen und ein Passwort sowie Werte aus der Jitterbit-Connector-Registrierung. Die aus der Connector-Registrierung erhaltenen Werte werden im Manifest vor dem Erstellen und Paketieren des Connectors verwendet.

Dropbox

Der erste Schritt erfolgt direkt bei Dropbox. Da der Connector eine Anwendung ist, die mit Dropbox interagiert, müssen Sie sich bei Dropbox als Entwickler registrieren und eine Dropbox-Anwendung mit der Dropbox-API erstellen. Die Anwendung kann beliebige Namen und Einstellungen haben. Dies kann mit einem kostenlosen Dropbox-Konto erfolgen. Gehen Sie auf die Dropbox-Website und erstellen Sie eine App:

Holen Sie sich den App-Schlüssel Ihrer neuen Anwendung von der Webseite und generieren Sie ein Zugriffstoken. Dieses Bild zeigt (rot umrandet), wo diese auf der Webseite zu finden sind:

In diesem Beispiel wurde eine Anwendung namens "Jitterbit Connector SDK Testing" erstellt. Der App-Schlüssel wird als "xxxxxxxxxxxxxxx" angezeigt. Das Zugriffstoken wird angezeigt, sobald der Button Generieren unter dem Label Generiertes Zugriffstoken verwendet wurde.

Klicken Sie auf die Schaltfläche Generieren, um das Zugriffstoken zu generieren, kopieren Sie sowohl den App-Schlüssel als auch das Zugriffstoken und bewahren Sie sie sicher auf, damit Sie sie bei der Konfiguration des Connectors abrufen können.

Beachten Sie die Einstellung des App-Ordnernamens (blau umrandet). In diesem Beispiel ist dies der Stammordner auf Dropbox, von dem aus alle Dateien, die Sie mit dem Connector hochladen oder abrufen, stammen werden.

Harmony

Wenn Sie noch keinen Harmony-Benutzernamen und kein Passwort erhalten haben, benötigen Sie diese, bevor Sie fortfahren. (Eine Testlizenz ist ausreichend: Gehen Sie zu https://jitterbit.com und klicken Sie auf die Schaltfläche Test anfordern, um sich anzumelden.)

Jitterbit-Connector-Registrierung

Alle Jitterbit-Connectoren erfordern eine Registrierung, die die Verwendung einer Jitterbit-API zur Registrierung des Connectors mit Ihren Harmony-Anmeldeinformationen umfasst.

Um den Connector zu registrieren und die Registrierungswerte zu erhalten, verwenden Sie die in der Dropbox-Connector enthaltene Postman-Sammlung als postman/JitterbitConnectorManagerAPI.collection.json.

Bevor Sie die REST-API ausführen, importieren Sie die Umgebungsvariablen aus postman/jitterbit-env-variable-postman.json in Postman und verknüpfen Sie sie mit der Sammlung.

Bearbeiten Sie die Umgebung und geben Sie die Host-Umgebungsvariablen (wie von Ihrer Region definiert; siehe Meine Region finden), E-Mail (your-jitterbit-harmony-username@example.com), Passwort (Ihr Harmony-Passwort) und Connector-Namen entsprechend ein:

Der Name, unter dem der Connector registriert ist, muss mit dem Wert in der Datei adapter.json übereinstimmen, die zur Beschreibung der UI verwendet wird. Für dieses Tutorial ist der im Dropbox adapter.json angegebene Connector name Dropbox. Für Details zur UI-Datei siehe Connector-Implementierung und Connector SDK UI-Komponenten.

Führen Sie nun in Postman diese beiden APIs in der angegebenen Reihenfolge aus:

1. Log In User
2. Register a Connector

(Die anderen APIs in der Sammlung können verwendet werden, um vorhandene Connectoren aufzulisten und zu löschen, die Sie zuvor registriert haben, sowie um die Gültigkeit des Schlüssels und des Geheimnisses eines Connectors zu bestätigen.)

Die Antwort, die von der API Register Connector zurückgegeben wird, enthält die Schlüssel-Werte, die für das Manifest des Connectors benötigt werden, um die Registrierung des Connectors abzuschließen. Sie sollten eine Antwort wie die folgende erhalten:

{
  "status": true,
  "operation": "Register a connector",
  "id": "3691",
  "key": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "secret": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "endpointEntityId": "20101",
  "functionEntityStartId": "20102",
  "functionEntityEndId": "20200"
}

Wie aus diesem Beispiel ersichtlich ist, wurde ein Connector registriert, hat eine Endpoint-Entity-ID von 20101 und kann Funktionsaktivitäts-Entity-IDs im Bereich von 20102 bis 20200 haben.

Der zurückgegebene Schlüssel und das Geheimnis werden gemäß der obigen Tabelle zu Jitterbit-Connector-Key und Jitterbit-Connector-Secret im Manifest für den Connector.

Der Connector hat eine Endpunkt-ID und einen Bereich von Aktivitäts- (Funktions-) Endpunkt-IDs zugewiesen bekommen, von der ersten bis zur letzten. Im Fall des Dropbox-Connectors, der vier Aktivitäten (Datei abrufen, Datei erhalten, Datei verarbeiten und Datei hochladen) hat, würden Sie einzelnen IDs für jede Aktivität zuweisen, sodass sie innerhalb des zugewiesenen Bereichs liegen. Maximal 99 Aktivitäten können einem einzelnen Connector zugewiesen werden.

Manifestdatei vervollständigen

Mit den erhaltenen Informationen können Sie nun die Werte in der Manifestdatei MANIFEST.MF festlegen, die sich im geklonten Dropbox-Connector GitHub-Repository unter src/main/resources/META-INF befindet:

Author: Jitterbit
Version: 1.0.0
Jitterbit-Connector-Key: <key>
Jitterbit-Connector-Secret: <secret>
Jitterbit-Connector-Endpoint-EntityTypeId: <endpoint_type_id>
Jitterbit-Activity-EntityTypeId-fetch: <id-1>
Jitterbit-Activity-EntityTypeId-put: <id-2>
Jitterbit-Activity-EntityTypeId-process: <id-3>
Jitterbit-Activity-EntityTypeId-get: <id-4>
Jitterbit-Connector-UI: adapter.json
Class-Path: lib/dropbox-core-sdk-3.0.6.jar

Der Schlüssel, das Geheimnis und die IDs wurden bei der Registrierung des Connectors zurückgegeben. Da der Dropbox-Connector vier Aktivitäten hat, können Sie die Start-ID für Jitterbit-Activity-EntityTypeId-fetch (die Aktivität Datei abrufen) verwenden und dann die IDs für die anderen drei Aktivitäten inkrementieren. Die letzte Aktivität muss kleiner oder gleich der functionEntityEndId sein. Vervollständigen Sie diese Werte, bevor Sie den Connector erstellen. Beachten Sie, dass zwischen dem Doppelpunkt des Labels und dem Wert in jeder Zeile der Manifestdatei ein Leerzeichen stehen muss.

Dropbox-Connector erstellen

Nachdem Sie die Manifesteinträge bearbeitet und gespeichert haben, sind Sie nun bereit, den Connector zu erstellen. Führen Sie diese Befehle im Verzeichnis dropbox-connector aus, das das geklonte Repository mit dem bearbeiteten Manifest enthält:

export APP_KEY=<dropbox-app-key>
export ACCESS_TOKEN=<dropbox-access-token>
mvn jaxb2:xjc compile install

JAVA_HOME="/Path/to/JDK/jdk-1.8.jdk/Contents/Home" mvn jaxb2:xjc compile install

Dies wird den Connector kompilieren, testen, erstellen, paketieren und installieren. Die fertige JAR-Datei befindet sich unter:

dropbox-connector/target/jitterbit-connector-dropbox-1.0.0.jar

Installieren Sie den Connector

Der fertige Connector kann jetzt auf einem privaten Agenten installiert werden. (Für Details zur Installation von Agenten siehe Systemanforderungen für private Agenten).

Damit der Agent den Connector finden kann, muss die Connector-JAR im Verzeichnis der Connectoren des Agenten platziert werden. Typischerweise befindet sich dieses Verzeichnis unter:

• Linux: /opt/jitterbit/Connectors
• Windows: C:\Program Files (x86)\Jitterbit Agent\Connectors (Administratorrechte erforderlich)
• Docker: das Verzeichnis, das im Docker-Befehl auf /opt/jitterbit/Connectors gemappt ist, wie --volume "$(pwd)/dropbox-connector:/opt/jitterbit/Connectors"

Wenn Sie das Harmony Docker private Agenten-Image verwenden, erlaubt es Ihnen, ein Hostverzeichnis an ein Containerverzeichnis wie /connectors zu mounten. Innerhalb des Docker-Containers wird der Agent das Verzeichnis /opt/jitterbit/Connectors nach JAR-Dateien durchsuchen, die eine Connector-Implementierung enthalten (nur eine Connector-Implementierung ist in jeder JAR-Datei erlaubt). Um die Dropbox-Connector-JAR nach dem Bau bereitzustellen, kopieren Sie die JAR-Datei aus dem Build-target-Verzeichnis in das Verzeichnis, das als Connectorenverzeichnis gemountet ist, und starten Sie den Container neu. Wenn der Docker-Container startet, kopiert er den Inhalt des gemounteten Verzeichnisses in das Verzeichnis /opt/jitterbit/Connectors.

In allen Fällen verwenden Sie nicht das Maven-Build-Verzeichnis als Connectorenverzeichnis, da die Durchsuchung des Verzeichnisses verwirrt wird, wenn es auf die Zwischenstufen des Maven-Build-Prozesses stößt. Kopieren Sie stattdessen die fertige JAR in das Connectorenverzeichnis, wenn der Build-Prozess abgeschlossen ist. Dies kann entweder manuell durchgeführt oder als Schritt nach einem erfolgreichen Build integriert werden.

Der Agent scannt kontinuierlich das Verzeichnis der Connectoren nach Änderungen und lädt automatisch alle Connector-JARs neu, die neu sind oder geändert wurden. Das bedeutet, dass Sie, während Sie Ihren Connector entwickeln, einfach jeden neuen Build in das Verzeichnis der Connectoren kopieren können, damit er automatisch vom Agenten neu geladen wird.

Docker-Beispiel

Zum Beispiel, auf einem Linux-System, das einen privaten Docker-Agenten ausführt, startet das Ausführen dieses Befehls im übergeordneten Verzeichnis des dropbox-connector einen Docker-Agenten mit dem target-Verzeichnis, das auf das Verzeichnis /opt/jitterbit/Connectors des Agenten abgebildet ist:

docker run --interactive --tty --name=jitterbit-agent --publish 3000:3000 \
           --volume "$(pwd)/dropbox-connector/target:/opt/jitterbit/Connectors" \
           --env-file "$(pwd)/private-agent.env" \
           jitterbit/agent

wobei private-agent.env die Umgebungsvariablen enthält, die für die Verbindung zu Harmony verwendet werden.

Die Datei private-agent.env würde so aussehen; ersetzen Sie die entsprechenden Werte:

HARMONY_USERNAME="<email_address>"
HARMONY_PASSWORD="<password>"
HARMONY_ORG="<your_organization_name>"
HARMONY_AGENT_GROUP="<your_agent_group_name>"
HARMONY_AGENT="<your_agent_name>"

In einer anderen Eingabeaufforderung (oder PowerShell, für Windows-Betriebssysteme) können Sie überprüfen, ob der Docker-Container läuft, indem Sie Folgendes verwenden:

docker ps -a

CONTAINER ID IMAGE                  COMMAND                CREATED       STATUS       PORTS                                              NAMES
xxxxxxxxxxxx jitterbit/agent:latest "/entrypoint.sh /ag…" 2 minutes ago Up 2 minutes 46908-46909/tcp, 0.0.0.0:3000->3000/tcp, 46912/tcp jitterbit-agent

In einer anderen Eingabeaufforderung (oder PowerShell, für Windows-Betriebssysteme) können Sie auf den Container zugreifen, indem Sie einen Befehl verwenden, um eine Shell im Docker-Container zu öffnen:

docker exec -ti jitterbit-agent /bin/bash

root@b3160de34840:/opt/jitterbit#

An diesem Punkt haben Sie vollen Zugriff auf den Agenten-Container. Sie können den Agenten mit dem Dienstprogramm /opt/jitterbit/bin/jitterbit stoppen und neu starten. Für eine Hilfenachricht verwenden Sie innerhalb des Containers:

/opt/jitterbit/bin/jitterbit help

Innerhalb des Containers können Sie die Tomcat-Protokolle verfolgen, um die Connector-Protokolle zu überprüfen:

tail -f tomcat/logs/catalina.out

. . .
2018-04-26 13:28:48,957 INFO com.jitterbit.integration.server.api.ws.connectorframework.ConnectorLoader:63 - Loading connectors...
. . .
2018-04-26 13:28:49,185 WARN com.jitterbit.integration.server.api.ws.connectorframework.ConnectorClassLoader:96 - Could not load Jitterbit Connector via manifest.mf; no Main-Class or Jitterbit-Connector-Factory-Class attributes defined.
2018-04-26 13:28:49,186 WARN com.jitterbit.integration.server.api.ws.connectorframework.ConnectorClassLoader:97 - Falling back to annotation system
2018-04-26 13:28:49,187 INFO com.jitterbit.integration.server.api.ws.connectorframework.ConnectorClassLoader:440 - Temporary Directory for undeploying connectors bundle: /opt/jitterbit/tomcat/temp
2018-04-26 13:28:49,517 INFO com.jitterbit.integration.server.api.ws.connectorframework.ConnectorClassLoader:377 - Loading annotated class java.lang.Class
2018-04-26 13:28:49,527 INFO com.jitterbit.integration.server.api.ws.connectorframework.ConnectorClassLoader:395 - Register Activity Factory with id: 200500 name: put factory: org.jitterbit.connector.dropbox.activities.PutFileActivity$PutFileActivityFactory
2018-04-26 13:28:49,530 INFO com.jitterbit.integration.server.api.ws.connectorframework.ConnectorClassLoader:395 - Register Activity Factory with id: 200402 name: fetch factory: org.jitterbit.connector.dropbox.activities.FetchFileActivity$FetchFileActivityFactory
. . .
26-Apr-2018 13:29:22.615 INFO [pool-1-thread-1] org.jitterbit.connector.ConnectorRegistry.registerConnector Connector Name: Dropbox Author: Jitterbit Connector Key: 929f90...52562 Endpoint Entity Type Id: 200401 Internal Connector: false Activities Id: {fetch=200402, put=200500}
26-Apr-2018 13:29:22.617 INFO [pool-1-thread-1] org.jitterbit.connector.sdk.BaseJitterbitConnector.onInit onInit() connector name: Dropbox
. . .

Wenn Sie Nachrichten sehen, die diesen im Protokoll ähnlich sind, bedeutet das, dass der Dropbox-Connector erfolgreich geladen und gestartet wurde. Sie können sich jetzt im Harmony-Portal anmelden und auf Integration Studio zugreifen, um den Connector zu verwenden.

In einem Projekt innerhalb der Umgebung, mit der der private Agent verbunden ist, sollten Sie den Dropbox-Connector in der Design-Komponentenpalette sehen. Sie können dann den Endpunkt so konfigurieren, wie Sie es mit jedem anderen Connector in Cloud Studio tun würden.

Verwenden Sie den Dropbox-Connector

Sie sollten den Connector jetzt in Projekten sehen, die die mit Ihrem privaten Agenten und dem Connector verbundene Umgebung verwenden. Er sollte im Connectivity-Tab der Design-Komponentenpalette erscheinen, wenn das Dropdown-Menü Show auf Connectors oder All eingestellt ist:

Falls nicht, siehe den Fehlerbehebungsabschnitt am Ende dieses Dokuments für Vorschläge, bevor Sie fortfahren.

Konfigurieren Sie eine Dropbox-Verbindung

Die erste Aufgabe besteht darin, den Dropbox-Connector zu verwenden, um eine Dropbox-Verbindung zu konfigurieren, um die Konnektivität mit dem Endpunkt herzustellen. In der Komponentenpalette, wobei sichergestellt wird, dass das Dropdown-Menü Show auf Connectors oder All eingestellt ist, klicken Sie auf den Dropbox-Connector, um die Verbindungs-Konfiguration zu öffnen. Geben Sie der Verbindung einen Namen (zum Beispiel "Dropbox") und geben Sie den Dropbox App Key und Dropbox Access Token ein, die Sie zuvor gespeichert haben:

Klicken Sie auf die Schaltfläche Test, um zu bestätigen, dass die Verbindung erfolgreich ist, und klicken Sie dann auf die Schaltfläche Änderungen speichern, um die Konfiguration zu speichern und zum Workflow zurückzukehren.

Sie sollten jetzt vier Aktivitäten unter der konfigurierten Dropbox-Verbindung in der Komponentenpalette sehen: Process File, Fetch File, Get File und Put File. Diese Aktivitäten können jetzt zu Operationen auf der Design-Leinwand hinzugefügt und als Quellen oder Ziele in einer Operation konfiguriert werden. Zusammen werden eine spezifische Verbindung und ihre Aktivitäten als Endpunkt bezeichnet:

Tutorialszenarien

Diese Tutorialszenarien demonstrieren jeweils eine andere Aktivität des Connectors:

• Szenario 1: Datei abrufen: Eine Textdatei von Dropbox abrufen und als XML-Datei auf einen FTP-Server schreiben.
• Szenario 2: Datei abrufen: Eine Textdatei von Dropbox abrufen und als Textdatei auf einen FTP-Server schreiben.
• Szenario 3: Datei hochladen: Eine Textdatei von einem FTP-Server lesen und als Textdatei in Dropbox hochladen.
• Szenario 4: Datei verarbeiten: Eine XML-Datei von Dropbox abrufen, verarbeiten und als JSON-Datei auf einen FTP-Server schreiben.
• Szenario 5: Datei abrufen: Eine Datei von Dropbox abrufen und auf einen FTP-Server schreiben.

Um die Tutorialszenarien abzuschließen, benötigen Sie Anmeldeinformationen (Host, Benutzername und Passwort) für einen FTP-Server. Wenn Sie kürzlich das Jitterbit University Training abgeschlossen haben und gültige Anmeldeinformationen besitzen, können Sie den FTP-Server aus diesem Kurs verwenden. Konfigurieren Sie einen FTP-Endpunkt, indem Sie den Host, den Benutzernamen und das Passwort eingeben. In diesen Tutorials wird der FTP-Endpunkt mit dem Namen "FTP" benannt:

Fehlerbehebung

Wenn Sie den Connector nicht laden oder ihn im Integration Studio nicht sehen können, schauen Sie sich die Tipps auf der Seite Fehlerbehebung beim Connector SDK an.