Microsoft Entra ID Abfrageaktivität

Einführung

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

Erstellen einer Microsoft Entra ID Abfrageaktivität

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

Um eine Instanz einer Aktivität zu erstellen, ziehen Sie den Aktivitätstyp auf die Entwurfstafel oder kopieren Sie den Aktivitätstyp und fügen Sie ihn auf der Entwurfstafel ein. Für Details siehe Erstellen einer Aktivitäts- oder Toolinstanz in Komponentenwiederverwendung.

Eine vorhandene Microsoft Entra ID Abfrage-Aktivität kann von diesen Orten aus bearbeitet werden:

• Die Entwurfstafel (siehe Komponentenaktionsmenü in Entwurfstafel).
• Der Komponenten-Tab im Projektbereich (siehe Komponentenaktionsmenü in Projektbereich Komponenten-Tab).

Konfigurieren einer Microsoft Entra ID Abfrageaktivität

Befolgen Sie diese Schritte, um eine Microsoft Entra ID Abfrage-Aktivität zu konfigurieren:

• Schritt 1: Geben Sie einen Namen ein und wählen Sie ein Objekt aus
  Geben Sie einen Namen für die Aktivität ein und wählen Sie ein Objekt aus.

• Schritt 2: Wählen Sie untergeordnete Objekte aus
  Wählen Sie untergeordnete Objekte zur Abfrage aus.

• Schritt 3: Definieren Sie eine Filterzeichenfolge
  Legen Sie Bedingungen für eine Abfrage der ausgewählten untergeordneten Objekte fest.

• Schritt 4: Überprüfen Sie die Datenschemas
  Alle Anforderungs- oder Antwortschemas, die von dem Endpunkt generiert wurden, werden angezeigt.

Schritt 1: Geben Sie einen Namen ein und wählen Sie ein Objekt aus

In diesem Schritt geben Sie einen Namen für die Aktivität ein und wählen ein Objekt aus. 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 Microsoft Entra ID Abfrage-Aktivität eindeutig sein und darf keine Schrägstriche / oder Doppelpunkte : enthalten.

• Objekt auswählen: In diesem Abschnitt werden die in dem Microsoft Entra ID-Endpunkt verfügbaren Objekte angezeigt.

  • Ausgewähltes Objekt: Nachdem ein Objekt ausgewählt wurde, wird es 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 beim Suchen vom Endpunkt neu zu laden, geben Sie Suchkriterien ein und aktualisieren Sie dann, wie unten beschrieben.

  • Aktualisieren: Klicken Sie auf das Aktualisierungs-Icon oder das Wort Aktualisieren, um Objekte vom Microsoft Entra ID-Endpunkt neu zu laden. Dies kann nützlich sein, wenn Objekte zu Microsoft Entra ID hinzugefügt wurden. Diese Aktion aktualisiert alle Metadaten, die zum Erstellen der in der Konfiguration angezeigten Objekttabelle verwendet werden.

• Objekt auswählen: Klicken Sie innerhalb der Tabelle auf eine beliebige Stelle in einer Zeile, um ein Objekt auszuwählen. Es kann nur ein Objekt ausgewählt werden. Die Informationen, die für jedes Objekt verfügbar sind, werden von dem Microsoft Entra ID-Endpunkt abgerufen:

  -   **Name:** Der Objektname von Microsoft Entra ID.
  
  -   **Beschreibung:** Die Objektbeschreibung von Microsoft Entra ID.
  

  Tipp

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

• Erweiterte HTTP-Eigenschaften: Klicken Sie auf das Hinzufügen-Symbol, um eine Zeile in der Tabelle unten hinzuzufügen und ein Schlüssel-Wert-Paar für jeden Anforderungsparameter einzugeben.

  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 {{ no such element: dict object['trash'] }} Löschen-Symbol.

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

  Wichtig

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

  Felder in der Erweiterten HTTP-Eigenschaften-Tabelle 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 {"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 auf die Schaltfläche Fertig im letzten Schritt klicken.

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

Schritt 2: Kindobjekte auswählen

In diesem Schritt wählen Sie das Kindobjekt aus, das abgefragt werden soll. Jedes Benutzeroberflächenelement dieses Schrittes wird im Folgenden beschrieben.

• Objektklassen: Dieser Abschnitt zeigt die verfügbaren und ausgewählten Kindobjektklassen an, mit denen im Microsoft Entra ID-Endpunkt interagiert werden kann.

  • Verfügbare Kindobjekte: Dieser Abschnitt zeigt eine Liste der in Microsoft Entra ID verfügbaren Kindobjektklassen an.

    • Suche: Geben Sie den Wert einer 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 beim Suchen vom Endpunkt neu zu laden, geben Sie Suchkriterien ein und aktualisieren Sie dann, wie unten beschrieben.

    • Aktualisieren: Klicken Sie auf das Aktualisierungssymbol oder das Wort Aktualisieren, um Objekte vom Microsoft Entra ID-Endpunkt neu zu laden. Dies kann nützlich sein, wenn Objekte zu Microsoft Entra ID hinzugefügt wurden. Diese Aktion aktualisiert alle Metadaten, die zum Erstellen der in der Konfiguration angezeigten Objekttabelle verwendet werden.

    • Hinzufügen eines Kindobjekts: Klicken Sie innerhalb der Spalte Verfügbare Kindobjekte irgendwo auf eine Zeile, um eine oder mehrere Kindobjektklassen auszuwählen. Klicken Sie dann auf das Hinzufügen-Symbol , um die ausgewählten Klassen zur Spalte Ausgewählte Kindobjekte hinzuzufügen.

  • Ausgewählte Kindobjekte: Nachdem eine Kindobjektklasse hinzugefügt wurde, wird sie hier aufgelistet.

    • Entfernen eines Kindobjekts: Klicken Sie innerhalb der Spalte Ausgewähltes Kindobjekt irgendwo auf eine Zeile, um eine oder mehrere Kindobjektklassen auszuwählen. Klicken Sie dann auf das Entfernen-Symbol , um die ausgewählten Klassen zur 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 die Schaltfläche Fertig im letzten Schritt klicken.

• Änderungen verwerfen: Nach Änderungen klicken Sie, um die Konfiguration zu schließen, ohne die an einem Schritt 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 in diesem Schritt der Konfiguration einer Microsoft Entra ID Abfrage-Aktivität verwendete Benutzeroberfläche hängt von der ausgewählten Registerkarte ab:

• Basis: Diese Option ermöglicht es Ihnen, die Filterzeichenfolge mit geführten Feldern zu erstellen.

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

Basis

Wenn die Registerkarte Basis ausgewählt ist, wird diese Benutzeroberfläche angezeigt:

• 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 Aktualisieren-Symbol oder das Wort Aktualisieren, um die Felder des Objekts vom Microsoft Entra ID-Endpunkt neu zu laden.

  • Alle im 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 eine Seitenanzahl ein, um die Ergebnis-Paginierung zu aktivieren. Die Anzahl der Ergebnisse auf einer Seite wird die angegebene Größe insgesamt erreichen. Ein Link zur nächsten Seite der Ergebnisse wird ebenfalls in der Antwort enthalten sein.

  Hinweis

  Wenn ein Wert für dieses Feld eingegeben wird, muss das Feld Top leer gelassen werden. Andernfalls tritt ein Fehler auf.

• Anzahl einbeziehen: Wählen Sie aus, um die Anzahl der Ergebnisse aus einer Abfrage als Teil der Antwort einzubeziehen.

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

• Überspringen: Geben Sie eine Anzahl von Ergebnissen an, die in der Abfrageantwort übersprungen werden sollen.

  Wichtig

  Die Microsoft Graph API unterstützt den skip-Parameter nicht für Verzeichnisobjekte, einschließlich Benutzer und Gruppen.

• Top: Geben Sie eine maximale Anzahl von Ergebnissen an, die Sie in der Abfrageantwort erhalten möchten. Wenn für dieses Feld kein Wert eingegeben wird, erhält die Abfrage standardmäßig 100 Ergebnisse. Der maximal zulässige Wert beträgt 999. Um mehr als 999 Ergebnisse zu erhalten, verwenden Sie stattdessen das Feld Seitenanzahl.

  Hinweis

  Wenn ein Wert für dieses Feld eingegeben wird, muss das Feld Seitenanzahl leer gelassen werden. Andernfalls tritt ein Fehler auf.

• 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 auf das Löschsymbol , um die Bedingung aus der Tabelle zu entfernen.

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

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

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

  Wichtig

  Wenn _odata.nextLink in der Anforderungsumwandlung bereitgestellt wird, werden alle Parameter, die in der Filterzeichenfolgenanweisung vorhanden sind, ignoriert. Wenn vorhanden, wird auch ein top-Parameter, der in der Anforderungsumwandlung bereitgestellt wird, ignoriert.

• Abfrage testen: Klicken Sie, um die Abfrage zu validieren. Diese Schaltfläche muss angeklickt 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 Änderungen an einem Schritt zu speichern. Eine Nachricht fragt Sie, ob Sie die Änderungen verwerfen möchten.

Erweitert

Wenn der Erweitert-Tab ausgewählt ist, wird diese Schnittstelle angezeigt:

• Seitenzahl: Geben Sie eine Seitenzahl ein, um die Ergebnis-Paginierung zu aktivieren. Die Anzahl der Ergebnisse auf einer Seite wird die angegebene Größe nicht überschreiten. Ein Link zur nächsten Seite der Ergebnisse wird ebenfalls in der Antwort enthalten sein. Wenn ein Wert für dieses Feld eingegeben wird, kann kein top-Filter bereitgestellt werden. Andernfalls tritt ein Fehler auf.

• Filterzeichenfolge: Bearbeiten Sie die Filterzeichenfolgen-Anweisung direkt.

  Important

  Beim Bearbeiten der Filterzeichenfolgen-Anweisung beachten Sie Folgendes:

  • Eine Abfrage kann keinen Wert sowohl für den top-Parameter als auch für das Feld Seitenzahl enthalten. Wenn eine Abfrage beide Parameter enthält, tritt ein Fehler auf.
  • Standardmäßig erhält die Abfrage 100 Ergebnisse. Bei Verwendung des top-Parameters beträgt der maximal zulässige Wert 999. Um mehr als 999 Ergebnisse zu erhalten, verwenden Sie stattdessen das Feld Seitenzahl.
  • Wenn _odata.nextLink in der Anforderungs-Transformation bereitgestellt wird, werden alle Parameter, die in der Filterzeichenfolgen-Anweisung vorhanden sind, ignoriert.

• Testabfrage: 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 nicht gü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 auf die Schaltfläche Fertig im letzten Schritt klicken.

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

Schritt 4: Überprüfen der Datenschemas

Alle Anforderungs- oder Antwortschemas, die vom Endpunkt generiert werden, werden angezeigt. Jedes Benutzeroberflächenelement dieses Schrittes wird im Folgenden beschrieben.

• Datenschemas: Diese Datenschemas werden von benachbarten Transformationen übernommen und während der Transformationszuordnung erneut angezeigt.

  Hinweis

  Daten, die in einer Transformation bereitgestellt werden, haben Vorrang vor der Aktivierungskonfiguration.

  Der Microsoft Entra ID Connector verwendet die Microsoft Graph API v1.0. Weitere Informationen zu den Schema-Knoten und -Feldern finden Sie in der API-Dokumentation.

  Wichtig

  Wenn _odata.nextLink in der Anforderungs-Transformation bereitgestellt wird, werden alle Parameter, die in der Filterzeichenfolgenanweisung in Schritt 3 vorhanden sind, ignoriert. Wenn vorhanden, wird auch ein top-Parameter, der in der Anforderungs-Transformation bereitgestellt wird, ignoriert.

• Bearbeiten: Klicken Sie auf das Bearbeitungssymbol über dem Antwortdatenschema, um in den Bearbeitungsmodus für dieses Datenschema zu gelangen. Der Editor ermöglicht es Ihnen, Knoten und Felder hinzuzufügen, zu löschen und neu anzuordnen sowie deren Datentypen zu ändern. Alle Vorkommen von Knoten und Feldern sind auf [0, 1] Kardinalität eingestellt. Änderungen an den Datenschemas müssen für den Endpunkt akzeptabel sein und sollten nur nach Konsultation der verfügbaren Dokumentation für den Endpunkt vorgenommen werden. Nach dem Bearbeiten des Schemas wird ein Datum der letzten Bearbeitung oben im entsprechenden Schema angezeigt, um anzuzeigen, dass das Schema manuelle Änderungen erfahren hat. Das Aktualisieren der Schemata setzt die Schemata auf ihre Standardstrukturen zurück.

  Hinweis

  Änderungen werden direkt an der Aktivität ohne Bestätigung vorgenommen. Wenn Sie Änderungen rückgängig machen oder zurücksetzen müssen, stellen Sie diese entweder im Bearbeitungsmodus erneut her oder erstellen Sie die Aktivität mit einer neuen Instanz der Aktivität neu.

• Aktualisieren: Klicken Sie auf das Aktualisierungs-Icon oder das Wort Aktualisieren, um Schemata vom Microsoft Entra ID-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 angrenzenden 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: Nachdem Sie Änderungen vorgenommen haben, 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 Microsoft Entra ID Abfrage-Aktivität konfiguriert haben, vervollständigen Sie die Konfiguration des Vorgangs, indem Sie andere Aktivitäten oder Werkzeuge als Vorgangsschritte hinzufügen und konfigurieren. Sie können auch die Betriebseinstellungen konfigurieren, die die Möglichkeit umfassen, Vorgänge zusammenzuführen, die sich in denselben oder unterschiedlichen Workflows befinden.

Menüaktionen für eine Aktivität sind über das Projektfenster und die Entwurfskanvas zugänglich. Weitere Details finden Sie im Aktivitätsaktionsmenü in Connector-Grundlagen.

Microsoft Entra ID Abfrage-Aktivitäten können als Quelle mit diesen Vorgangsmustern 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, setzen Sie die Operation ein und führen Sie sie aus und validieren Sie das Verhalten, indem Sie die Betriebsprotokolle überprüfen.