OData-Abfrageaktivität

Einführung

Eine OData Abfrage-Aktivität, die ihre OData-Verbindung verwendet, fragt Objektdaten von einem OData-Endpunkt ab und ist dazu gedacht, als Quelle für die Bereitstellung von Daten in einem Vorgang verwendet zu werden.

Erstellen einer OData-Abfrageaktivität

Eine Instanz einer OData Abfrage-Aktivität wird aus einer OData-Verbindung unter Verwendung des Aktivitätstyps Abfrage erstellt.

Um eine Instanz einer Aktivität zu erstellen, ziehen Sie den Aktivitätstyp auf die Entwurfsfläche oder kopieren Sie den Aktivitätstyp und fügen Sie ihn auf der Entwurfsfläche ein. Weitere Informationen finden Sie unter Erstellen einer Aktivitäts- oder Toolinstanz in Komponentenwiederverwendung.

Eine vorhandene OData Abfrage-Aktivität kann von diesen Orten aus bearbeitet werden:

• Die Entwurfsfläche (siehe Komponentenaktionsmenü in Entwurfsfläche).
• Der Komponenten-Tab im Projektbereich (siehe Komponentenaktionsmenü in Projektbereich Komponenten-Tab).

Konfigurieren einer OData-Abfrageaktivität

Befolgen Sie diese Schritte, um eine OData Abfrage-Aktivität zu konfigurieren:

• Schritt 1: Geben Sie einen Namen ein und spezifizieren Sie die Einstellungen
  Geben Sie einen Namen für die Aktivität an, spezifizieren Sie die Objektklasse, die abgefragt werden soll, und geben Sie alle erforderlichen HTTP-Header an.

• Schritt 2: Wählen Sie untergeordnete Objekte aus
  Wählen Sie untergeordnete Objektklassen aus, die basierend auf der im vorherigen Schritt ausgewählten Objektklasse abgefragt werden sollen.

• Schritt 3: Definieren Sie eine Filterzeichenfolge
  Der Abfrage-Builder wird verwendet, um Bedingungen für eine Abfrage mithilfe der Objektfelder festzulegen und die Paginierung für eine Abfrage anzuwenden.

• Schritt 4: Überprüfen des Datenschemas
  Alle Antwortschemata, die vom Endpunkt generiert werden, werden angezeigt.

Schritt 1: Geben Sie einen Namen ein und spezifizieren Sie die Einstellungen

In diesem Schritt geben Sie einen Namen für die Aktivität ein und spezifizieren die Objektklasse, die abgefragt werden soll, sowie alle erforderlichen HTTP-Header. Jedes Benutzeroberflächenelement dieses Schrittes wird im Folgenden beschrieben.

• Name: Geben Sie einen Namen ein, um die Aktivität zu identifizieren. Der Name muss für jede OData Abfrage-Aktivität eindeutig sein und darf keine Schrägstriche (/) oder Doppelpunkte (:) enthalten.

• Objekt auswählen: Dieser Abschnitt zeigt die Objektklassen an, die im OData-Endpunkt verfügbar sind.

  • Ausgewähltes Objekt: Nachdem eine Objektklasse ausgewählt wurde, wird sie hier aufgelistet.

  • Suche: Geben Sie den Wert einer beliebigen Spalte in das Suchfeld ein, um die Liste der Objekte zu filtern. Die Suche ist nicht groß-/kleinschreibungsempfindlich. Wenn Objekte bereits in der Tabelle angezeigt werden, werden die Tabellenergebnisse in Echtzeit mit jedem Tastendruck gefiltert. Um Objekte vom Endpunkt beim Suchen neu zu laden, geben Sie Suchkriterien ein und aktualisieren Sie dann, wie unten beschrieben.

  • Aktualisieren: Klicken Sie auf das Aktualisierungs-Icon oder auf das Wort Aktualisieren, um die Objektklassen vom OData-Endpunkt neu zu laden. Dies kann nützlich sein, wenn das Schema des OData-Endpunkts aktualisiert wurde, um neue Objekttypen zu unterstützen. Diese Aktion aktualisiert alle Metadaten, die zum Erstellen der Tabelle der in der Konfiguration angezeigten Objekte verwendet werden.

  • Auswählen eines Objekts: Klicken Sie innerhalb der Tabelle auf eine beliebige Stelle in einer Zeile, um eine Objektklasse auszuwählen. Es kann nur eine Objektklasse ausgewählt werden. Die Informationen, die für jedes Objekt verfügbar sind, werden vom OData-Endpunkt abgerufen:

    • Name: Der Objektklassennamen vom OData-Endpunkt.

    • Description: Die Objektklassendefinition vom OData-Endpunkt.

  Tipp

  Wenn die Tabelle nicht mit verfügbaren Objektklassen gefüllt wird, könnte die OData-Verbindung nicht erfolgreich sein. Stellen Sie sicher, dass Sie verbunden sind, indem Sie die Verbindung erneut öffnen und die Anmeldeinformationen erneut testen.

• Advanced HTTP Properties: Definieren Sie HTTP-Header für die Abfrage. Das OData-Protokoll akzeptiert standardmäßige HTTP-Header, die in Rfc 2616 (Abschnitt 14) definiert sind, sowie benutzerdefinierte Header, die spezifisch für den Endpunkt sind. Klicken Sie auf das Hinzufügen-Symbol , um einen Header zur Tabelle unten hinzuzufügen, und geben Sie ein Schlüssel-Wert-Paar für jeden Anforderungsparameter ein.

  Um die Zeile zu speichern, klicken Sie auf das Senden-Symbol in der rechten Spalte.

  Um eine einzelne Zeile zu bearbeiten oder zu löschen, fahren Sie mit der Maus über die rechte Spalte und verwenden Sie das Bearbeiten-Symbol oder das Löschen-Symbol .

  Um alle Zeilen zu löschen, klicken Sie auf Alle löschen.

  Hinweis

  Benutzerdefinierte Header müssen im Endpunkt konfiguriert werden, damit sie als Teil dieser Anfrage akzeptiert werden. Wenn Sie Microsoft Azure verwenden, um Ihren OData-Endpunkt zu verwalten, lesen Sie die Microsoft-Dokumentation zu Benutzerdefinierten Headern in Zugriff auf Endpunkte, die Authentifizierung erfordern.

  Wichtig

  Felder in der Tabelle Advanced HTTP Properties zeigen das Variablen-Symbol nur im Bearbeitungsmodus an. Damit die Variablenwerte dieser Felder zur Laufzeit gefüllt werden, muss die Agenten-Version mindestens 10.75 / 11.13 sein.

  Felder in der Tabelle Advanced HTTP Properties unterstützen nicht die Verwendung von Variablen, um rohes JSON zu übergeben. Wenn Ihr Anwendungsfall nicht unterstützt, rohes JSON direkt in den Feldern zu definieren, entkommen Sie den JSON-Inhalt, bevor Sie ihn mit einer Variablen übergeben. Zum Beispiel wird das Entkommen von {"success": "true"}; zu {\"success\": \"true\"};.

• Speichern & Beenden: Wenn aktiviert, klicken Sie, um die Konfiguration für diesen Schritt zu speichern und die Aktivitätskonfiguration zu schließen.

• Weiter: Klicken Sie, um die Konfiguration für diesen Schritt vorübergehend zu speichern und zum nächsten Schritt fortzufahren. Die Konfiguration wird nicht gespeichert, bis Sie die Schaltfläche Fertig im letzten Schritt klicken.

• Änderungen verwerfen: Nach Änderungen klicken Sie, um die Konfiguration zu schließen, ohne die Änderungen an einem Schritt zu speichern. Eine Nachricht fragt Sie, ob Sie die Änderungen wirklich verwerfen möchten.

Schritt 2: Wählen Sie untergeordnete Objekte

In diesem Schritt wählen Sie die untergeordneten Objektklassen aus, die in die Abfrage einbezogen werden sollen, basierend auf der im vorherigen Schritt ausgewählten Objektklasse. Jedes Benutzeroberflächenelement dieses Schrittes wird im Folgenden beschrieben.

• Untergeordnete Objekte auswählen: Dieser Abschnitt wird verwendet, um untergeordnete Objektklassen für die Abfrage auszuwählen. Dieser Abschnitt ist optional und kann übersprungen werden, indem Weiter ausgewählt wird.

  • Verfügbare untergeordnete Objekte: Diese Spalte zeigt die zur Auswahl stehenden untergeordneten Objektklassen an.

    • Suchen: Geben Sie den Wert einer Spalte in das Suchfeld ein, um die Liste der untergeordneten Objektklassen zu filtern. Die Suche ist nicht groß-/kleinschreibungsempfindlich. Wenn Objektklassen bereits in der Tabelle angezeigt werden, werden die Tabellenergebnisse in Echtzeit mit jedem Tastendruck gefiltert. Um untergeordnete Objektklassen von dem Endpunkt beim Suchen neu zu laden, geben Sie Suchkriterien ein und aktualisieren Sie dann, wie unten beschrieben.

    • Aktualisieren: Klicken Sie auf das Aktualisierungssymbol , um die untergeordneten Objektklassen vom OData-Endpunkt neu zu laden. Dies kann nützlich sein, wenn Sie kürzlich untergeordnete Objektklassen zum OData-Endpunkt hinzugefügt haben.

    • Hinzufügen eines untergeordneten Objekts: Klicken Sie innerhalb der Spalte auf eine beliebige Stelle in einer Zeile, um eine oder mehrere untergeordnete Objektklassen auszuwählen. Klicken Sie dann auf das Hinzufügen-Symbol , um die ausgewählten Klassen zur Spalte Ausgewählte untergeordnete Objekte hinzuzufügen.

  • Ausgewählte untergeordnete Objekte: Diese Spalte zeigt die ausgewählten untergeordneten Objektklassen an.

• Entfernen eines Kindobjekts: Klicken Sie innerhalb der Spalte auf eine beliebige Stelle in einer Zeile, um eine oder mehrere Klassen von Kindobjekten auszuwählen. Klicken Sie dann auf das Entfernen-Symbol , um die ausgewählten Klassen in die Spalte Verfügbare Kindobjekte zurückzugeben.

• Zurück: Klicken Sie, um die Konfiguration für diesen Schritt vorübergehend zu speichern und zum vorherigen Schritt zurückzukehren.

• Weiter: Klicken Sie, um die Konfiguration für diesen Schritt vorübergehend zu speichern und mit dem nächsten Schritt fortzufahren. Die Konfiguration wird nicht gespeichert, bis Sie auf die Schaltfläche Fertig im letzten Schritt klicken.

• Änderungen verwerfen: Nach Änderungen klicken Sie, um die Konfiguration zu schließen, ohne die vorgenommenen Änderungen zu speichern. Eine Nachricht fordert Sie auf, zu bestätigen, dass Sie die Änderungen verwerfen möchten.

Schritt 3: Definieren Sie eine Filterzeichenfolge

In diesem Schritt wird eine Filterzeichenfolge für eine Abfrage unter Verwendung verfügbarer Objektfelder und Abfrageeinstellungen definiert. Jedes Benutzeroberflächenelement dieses Schrittes wird im Folgenden beschrieben.

Die Filterzeichenfolge kann in den Registerkarten Basis oder Erweitert konfiguriert werden.

• Basis: Ermöglicht es Ihnen, die Filterzeichenfolge mit geführten Feldern zu erstellen:

  

  • Objektfelder: Wählen Sie die Felder aus, die in der Abfrage basierend auf der ausgewählten Objektklasse verwendet werden sollen.

    • Suche: Geben Sie einen Teil eines Feldnamens in das Suchfeld ein, um die Liste der Felder für das ausgewählte Objekt zu filtern. Die Suche ist nicht groß-/kleinschreibungsempfindlich. Die aufgelisteten Ergebnisse werden in Echtzeit mit jedem Tastendruck gefiltert.

    • Aktualisieren: Klicken Sie auf das Aktualisierungssymbol oder das Wort Aktualisieren, um die Felder des Objekts vom OData-Endpunkt neu zu laden.

    • Alle in der Objektklasse auswählen: Wenn Sie das Suchfeld verwenden, um zu filtern, können Sie dieses Kontrollkästchen verwenden, um alle sichtbaren Felder auf einmal auszuwählen.

    • Felder auswählen: Wählen Sie die Kontrollkästchen der Felder aus, die Sie in die Abfrage einbeziehen möchten, damit sie automatisch zur Filterzeichenfolge hinzugefügt werden. Sie können auch alle Felder auf einmal mit dem übergeordneten Kontrollkästchen auswählen.

  • Seitenanzahl: Geben Sie die maximale Anzahl von Ergebnissen an, die für jede Seite in der Abfrageantwort abgerufen werden sollen. Wenn dieses Feld leer bleibt, enthält jede Seite 100 Ergebnisse.

    Hinweis

    Wenn eine clientseitige Paginierung erforderlich ist, verwenden Sie die Felder Skip und Top.

  • Anzahl einbeziehen: Wählen Sie aus, um die Anzahl der Ergebnisse aus einer Abfrage als Teil der Antwort einzuschließen. Wenn eine Abfrage beispielsweise insgesamt 5 Ergebnisse zurückgibt, enthält die Antwort auch "_odata.count": 5.

  • Volltextsuche: Geben Sie Suchbegriffe ein, um nach Objekten in der ausgewählten Objektklasse zu suchen. Der OData-Endpunkt verarbeitet, wie die Suche für eine Objektklasse interpretiert wird.

  • Überspringen: Geben Sie die Anzahl der Ergebnisse an, die in der Abfrageantwort übersprungen werden sollen. Wird für die clientseitige Paginierung verwendet.

  • Top: Geben Sie die maximale Anzahl von Ergebnissen an, die in der Abfrageantwort empfangen werden sollen. Wird für die clientseitige Paginierung verwendet.

  • Bedingte Klauseln: Um Bedingungen hinzuzufügen, verwenden Sie diese Felder als Eingabe, um die Klauseln zu erstellen, die dann in der Filterzeichenfolge erscheinen.

    • Objekt: Verwenden Sie das Dropdown-Menü, um die Objektklasse auszuwählen, die für die Bedingung verwendet werden soll.

    • Feld: Verwenden Sie das Dropdown-Menü, um das Feld aus der Objektklasse auszuwählen, das für die Bedingung verwendet werden soll.

    • Operator: Verwenden Sie das Dropdown-Menü, um einen geeigneten Operator auszuwählen:

      Vergleich
      Gleich
      Größer als
      Größer als oder gleich
      Kleiner als
      Kleiner als oder gleich

    • Wert: Geben Sie den gewünschten Wert ein, um ihn mit den vorherigen Dropdown-Auswahlen zu vergleichen.

    • Entfernen: Klicken Sie, um die Bedingung zu entfernen.

    • Hinzufügen: Klicken Sie, um eine neue Bedingung zur Tabelle Bedingte Klauseln und Filterzeichenfolge hinzuzufügen.

    • Alle Entfernen: Klicken Sie, um alle Bedingungen aus der Tabelle Bedingte Klauseln und Filterzeichenfolge zu entfernen.

  • Filterzeichenfolge: Während Sie die anderen Felder im Tab Basis ausfüllen, wird die Filterzeichenfolgenanweisung in diesem Textfeld automatisch mit den ausgewählten Feldern, Bedingungen und Abfrageoptionen ausgefüllt.

• Erweitert: Blendet die geführten Felder aus und ermöglicht es Ihnen, die Filterzeichenfolge direkt zu ändern:

  

  • Seitenanzahl: Geben Sie die maximale Anzahl von Ergebnissen ein, die für jede Seite in der Abfrageantwort abgerufen werden sollen. Wenn dieses Feld leer bleibt, enthält jede Seite 100 Ergebnisse.

    Hinweis

    Wenn eine clientseitige Paginierung erforderlich ist, verwenden Sie die Abfrageoptionen $skip und $top im Feld Filterzeichenfolge.

  • Filterzeichenfolge: Bearbeiten Sie die Filterzeichenfolgenanweisung direkt.

• Abfrage testen: Klicken Sie, um die Abfrage zu validieren. Wenn die Abfrage gültig ist, wird eine Stichprobe von bis zu 10 Datensätzen, die aus der Abfrage abgerufen wurden, in einer Tabelle angezeigt. Wenn die Abfrage ungültig ist, werden relevante Fehlermeldungen angezeigt. Wenn Sie die Filterzeichenfolge im Erweitert-Modus bearbeiten, muss die Abfrage gültig sein und über diese Schaltfläche validiert werden, um die Schaltfläche Weiter zu aktivieren.

  

• Zurück: Klicken Sie, um die Konfiguration für diesen Schritt vorübergehend zu speichern und zum vorherigen Schritt zurückzukehren.

• Weiter: Klicken Sie, um die Konfiguration für diesen Schritt vorübergehend zu speichern und mit dem nächsten Schritt fortzufahren. Die Konfiguration wird nicht gespeichert, bis Sie die Schaltfläche Fertig im letzten Schritt klicken.

• Änderungen verwerfen: Nach Änderungen klicken Sie, um die Konfiguration zu schließen, ohne die vorgenommenen Änderungen zu speichern. Eine Nachricht fordert Sie auf, zu bestätigen, dass Sie die Änderungen verwerfen möchten.

Schritt 4: Überprüfen des Datenschemas

Das Antwortschema, das von dem Endpunkt generiert wurde, wird angezeigt. Jedes Benutzeroberflächenelement dieses Schrittes wird im Folgenden beschrieben.

• Datenschema: Dieses Datenschema wird von benachbarten Transformationen geerbt und wird während der Transformationszuordnung erneut angezeigt.

  Hinweis

  Die in einer Transformation bereitgestellten Daten haben Vorrang vor der Aktivitätskonfiguration.

  • Antwort:

    Antwortschema-Feld/Knoten	Beschreibung
    queryresponse	Antwort auf die Abfrage von Objekten (Entitäten)
    response	Knoten, der die Abfrageantwort darstellt
    item	Knoten, der die Antwortelemente darstellt
    Objektliste	Knoten, der die abgefragte Objektliste (Entitätensatz) darstellt; zum Beispiel den Knoten Person
    _odata.nextLink	Zeichenfolge des OData-Anmerkungsfelds mit einer URL, die verwendet wird, um die nächste Teilmenge von Ergebnissen aus der angeforderten Abfrageantwort abzurufen
    _odata.count	Zeichenfolge des OData-Anmerkungsfelds mit der Gesamtanzahl der Objekte, die aus der Abfrage zurückgegeben wurden
    _odata.context	Zeichenfolge des OData-Anmerkungsfelds mit einer URL, die den Standort der abgefragten Objektliste enthält
    value	Knoten, der die Liste der übereinstimmenden Objekte aus der Abfrage darstellt
    item	Knoten, der ein übereinstimmendes Objekt aus der Abfrage darstellt
    Objektfelder ...	Felder, die spezifisch für die Objektklasse (Entitätstyp) der Objekte in der Objektliste sind; zum Beispiel Felder im Knoten item, wie UserName und Concurrency
    _odata.etag	Zeichenfolge des OData-Anmerkungsfelds mit einem Wert, der in einer nachfolgenden Anfrage verwendet werden kann, um festzustellen, ob sich der Wert des Objekts geändert hat
    error	Knoten, der die Fehlermeldungen aus der Abfrage darstellt
    code	Zeichenfolge des Codes, der mit dem Fehler verbunden ist
    message	Zeichenfolge der Nachricht, die mit dem Fehler verbunden ist

  Der OData-Connector verwendet die Apache Olingo OData 4.0 Java-Bibliothek. Weitere Informationen zur Unterstützung des OData-Protokolls finden Sie in der Bibliotheksdokumentation. Allgemeine Informationen zum OData-Protokoll sind auch auf OData's Dokumentationsseite verfügbar.

• Aktualisieren: Klicken Sie auf das Aktualisierungssymbol oder das Wort Aktualisieren, um Schemata vom OData-Endpunkt neu zu generieren. Diese Aktion regeneriert auch ein Schema an anderen Stellen im Projekt, an denen dasselbe Schema referenziert wird, wie z. B. in einer benachbarten Transformation.

• Zurück: Klicken Sie, um die Konfiguration für diesen Schritt vorübergehend zu speichern und zum vorherigen Schritt zurückzukehren.

• Fertig: Klicken Sie, um die Konfiguration für alle Schritte zu speichern und die Aktivitätskonfiguration zu schließen.

• Änderungen verwerfen: Nach Änderungen klicken Sie, um die Konfiguration zu schließen, ohne die an einem Schritt vorgenommenen Änderungen zu speichern. Eine Nachricht fragt Sie, ob Sie die Änderungen wirklich verwerfen möchten.

Nächste Schritte

Nachdem Sie eine OData Abfrage-Aktivität konfiguriert haben, vervollständigen Sie die Konfiguration der Operation, indem Sie andere Aktivitäten oder Werkzeuge als Operation Schritte hinzufügen und konfigurieren. Sie können auch die Betriebseinstellungen konfigurieren, die die Möglichkeit umfassen, Operationen zusammenzuführen, die sich in denselben oder unterschiedlichen Workflows befinden.

Menüaktionen für eine Aktivität sind im Projektbereich und auf der Entwurfsgrafik zugänglich. Weitere Einzelheiten finden Sie im Aktivitätsaktionsmenü in Connector-Grundlagen.

OData Abfrage-Aktivitäten können als Quelle mit diesen Betriebsmustern verwendet werden:

• Transformationsmuster
• Zwei-Ziel-Archivmuster (nur als erste Quelle)
• Zwei-Ziel-HTTP-Archivmuster (nur als erste Quelle)
• Zwei-Transformationsmuster (nur als erste Quelle)

Um die Aktivität mit Skriptfunktionen zu verwenden, schreiben Sie die Daten an einen temporären Speicherort und verwenden Sie dann diesen temporären Speicherort in der Skriptfunktion.

Wenn Sie bereit sind, bereitstellen und ausführen Sie die Operation und validieren Sie das Verhalten, indem Sie die Betriebsprotokolle überprüfen.