Teilen über

Häufig gestellte Fragen zur API-gesteuerten eingehenden Bereitstellung

  • Artikel

Dieser Artikel beantwortet häufig gestellte Fragen (FAQs) zur API-gesteuerten eingehenden Bereitstellung.

Wie unterscheidet sich die neue /bulkUpload-API für die Bereitstellung von der MS Graph Benutzer-API?

Es gibt erhebliche Unterschiede zwischen dem /bulkUpload-API-Endpunkt für die Bereitstellung und dem MS Graph Benutzer-API-Endpunkt.

  • Nutzdatenformat: Der MS Graph Benutzer-API-Endpunkt erwartet Daten im OData-Format. Das Anforderungsnutzdatenformat für die neue /bulkUpload-API für die eingehende Bereitstellung verwendet SCIM-Schemakonstrukte. Legen Sie den „Content-Type“-Header beim Aufrufen dieser API auf application/scim+json fest.
  • Endergebnis des Vorgangs:
    • Wenn Identitätsdaten an den MS Graph Benutzer-API-Endpunkt gesendet werden, werden sie sofort verarbeitet, und im Microsoft Entra-Benutzerprofil wird ein Vorgang zum Erstellen/Aktualisieren/Löschen durchgeführt.
    • Anforderungsdaten, die an die /bulkUpload-API für die Bereitstellung gesendet werden, werden vom Microsoft Entra-Bereitstellungsdienst asynchron verarbeitet. Der Bereitstellungsauftrag wendet Bereichsregeln, Attributzuordnung und Transformation an, die vom IT-Administrator konfiguriert wurden. Dadurch wird ein Create/Update/Delete-Vorgang für das Microsoft Entra/Benutzerprofil oder das lokale AD-Benutzerprofil initiiert.
  • Der IT-Administrator behält die Kontrolle: Mit der API-gesteuerten eingehenden Bereitstellung hat der IT-Administrator mehr Kontrolle darüber, wie die eingehenden Identitätsdaten verarbeitet und Microsoft Entra-Attributen zugeordnet werden. Sie können Bereichsregeln zum Ausschließen bestimmter Arten von Identitätsdaten (z. B. Auftragnehmerdaten) definieren und Transformationsfunktionen verwenden, um neue Werte abzuleiten, bevor Sie die Attributwerte im Benutzerprofil festlegen.

Ist die /bulkUpload-API für die eingehende Bereitstellung ein Standard-SCIM-Endpunkt?

Die MS Graph-/bulkUpload-API für die eingehende Bereitstellung verwendet das SCIM-Schema in den Anforderungsnutzdaten, ist aber kein standardisierter SCIM-API-Endpunkt. Die Begründung hierfür finden Sie unten.

In der Regel verarbeitet ein SCIM-Dienstendpunkt HTTP-Anforderungen (POST, PUT, GET) mit SCIM-Nutzdaten und übersetzt sie in die jeweiligen Vorgänge (Erstellen, Aktualisieren, Lookup) im Identitätsspeicher. Der SCIM-Dienstendpunkt legt die Pflicht zur Angabe der Vorgangssemantik, ob eine Identität erstellt/aktualisiert/gelöscht werden soll, auf den SCIM-API-Client. Dieser Mechanismus eignet sich gut für Szenarien, in denen der API-Client weiß, welchen Vorgang er für Benutzer im Identitätsspeicher ausführen will.

Der MS Graph-/bulkUpload für die eingehende Bereitstellung ist für die Verarbeitung eines anderen Szenarios für die Integration von Unternehmensidentitäten konzipiert, das durch drei eindeutige Anforderungen geprägt ist:

  1. Möglichkeit zur asynchronen Massenverarbeitung von Datensätzen (z. B. Verarbeitung von mehr als 50 000 Datensätzen)
  2. Möglichkeit, ein beliebiges Identitätsattribut in die Nutzdaten einzuschließen (z. B. costCenter, pay grade, badgeId)
  3. Unterstützung von API-Clients, die sich nicht mit der Vorgangsemantik auskennen. Bei diesen Clients handelt es sich um Nicht-SCIM-API-Clients, die nur Zugriff auf rohe Quelldaten haben (z. B. Datensätze in einer CSV-Datei, einer SQL-Tabelle oder in HR-Datensätzen). Diese Clients haben nicht die Prozessfähigkeit, jeden Datensatz zu lesen und die Vorgangsemantik von Create/Update/Delete auf dem Identitätsspeichers zu bestimmen.

Das primäre Ziel der MS Graph-/bulkUpload-API für die eingehende Bereitstellung besteht darin, Kunden das Senden beliebiger Identitätsdaten (z. B. costCenter, pay grade, badgeId) aus einer beliebigen Identitätsdatenquelle (z. B. CSV/SQL/HR) für die eventuelle Verarbeitung durch den Microsoft Entra-Bereitstellungsdienst zu ermöglichen. Der Microsoft Entra-Bereitstellungsdienst nutzt die Massennutzdaten, die an diesem Endpunkt empfangen werden, wendet Regeln zur Attributzuordnung an, die vom IT-Administrator konfiguriert wurden, und bestimmt, ob die Datennutzdaten zum Vorgang (Erstellen, Aktualisieren, Aktivieren, Deaktivieren) im Zielidentitätsspeicher (Microsoft Entra ID /lokales AD) führt.

Unterstützt die /bulkUpload-API für die Bereitstellung lokale Active Directory-Domänen als Ziel?

Ja, die API für die Bereitstellung unterstützt lokale AD-Domänen als Ziel.

Wie erhalten wir den /bulkUpload-API-Endpunkt für unsere Bereitstellungs-App?

Die /bulkUpload-API ist nur für Apps des Typs „API-gesteuerte eingehende Bereitstellung in Microsoft Entra ID“ und „API-gesteuerte eingehende Bereitstellung für lokales Active Directory“ verfügbar. Sie können den eindeutigen API-Endpunkt für jede Bereitstellungs-App auf dem Blatt „Bereitstellung“ der Homepage abrufen. Gehen Sie zu Statistiken bis heute>Technische Informationen anzeigen und kopieren Sie die URL für den API-Endpunkt für die Bereitstellung .

Er weist folgendes Format auf:

https://graph.microsoft.com/beta/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/bulkUpload

Wie führen wir eine vollständige Synchronisierung mithilfe der /bulkUpload-API für die Bereitstellung durch?

Um eine vollständige Synchronisierung durchzuführen, verwenden Sie Ihren API-Client, um die Daten aller Benutzer aus Ihrer vertrauenswürdigen Quelle als Massenanforderung an den API-Endpunkt zu senden. Nachdem Sie alle Daten an den API-Endpunkt gesendet haben, verarbeitet der nächste Synchronisierungszyklus alle Benutzerdatensätze und ermöglicht es Ihnen, den Fortschritt mithilfe des API-Endpunkts der Bereitstellungsprotokolle nachzuverfolgen.

Wie führen wir die Deltasynchronisierung mithilfe der /bulkUpload-API für die Bereitstellung durch?

Um eine Deltasynchronisierung durchzuführen, verwenden Sie Ihren API-Client, um nur Informationen über Benutzern zu senden, deren Daten sich in der vertrauenswürdigen Quelle geändert haben. Nachdem Sie alle Daten an den API-Endpunkt gesendet haben, verarbeitet der nächste Synchronisierungszyklus alle Benutzerdatensätze und ermöglicht es Ihnen, den Fortschritt mithilfe des API-Endpunkts der Bereitstellungsprotokolle nachzuverfolgen.

Wie funktioniert der Neustart der Bereitstellung?

Verwenden Sie die Option Bereitstellung neu starten nur bei Bedarf. Funktionsweise:

Szenario 1: Wenn Sie auf die Schaltfläche Bereitstellung neu starten klicken und der Auftrag derzeit ausgeführt wird, wird die Verarbeitung der sich bereits in der Stage befindlichen Daten fortgesetzt. Der Vorgang Bereitstellung neu starten unterbricht keinen vorhandenen Zyklus. Im nachfolgenden Zyklus löscht der Bereitstellungsdienst alle Hinterlegungen und wählt die neue Massenanforderung für die Verarbeitung aus.

Szenario 2: Wenn Sie auf die Schaltfläche Bereitstellung neu starten klicken und der Auftrag nicht ausgeführt wird, löscht das Bereitstellungsmodul vor dem Ausführen des nachfolgenden Zyklus die vor dem Neustart hochgeladenen Daten, löscht alle Hinterlegungen und verarbeitet nur neue eingehende Daten.

Wie erstellen wir Benutzer mithilfe des /bulkUpload-API-Endpunkts für die Bereitstellung?

Hier erfahren Sie, wie der Bereitstellungsauftrag, der dem /bulkUpload-API-Endpunkt zugeordnet ist, eingehende Benutzernutzdaten verarbeitet:

  1. Der Auftrag ruft die Attributzuordnung für den Bereitstellungsauftrag ab und notiert sich das übereinstimmende Attributpaar (standardmäßig wird das externalId-API-Attribut verwendet, um mit employeeId in Microsoft Entra ID abzugleichen).
  2. Sie können dieses Standard-Attributabgleichspaar ändern.
  3. Der Auftrag extrahiert jeden Vorgang, der in den Massenanforderungsnutzdaten vorhanden ist.
  4. Der Auftrag überprüft den Bezeichner für den Wertabgleich in der Anforderung (standardmäßig das Attribut externalId) und verwendet ihn, um zu überprüfen, ob in Microsoft Entra ID ein Benutzer mit übereinstimmendem employeeId-Wert vorhanden ist.
  5. Wenn der Auftrag keinen übereinstimmenden Benutzer findet, wendet der Auftrag die Synchronisierungsregeln an und erstellt einen neuen Benutzer im Zielverzeichnis.

Um sicherzustellen, dass die richtigen Benutzer in Microsoft Entra ID erstellt werden, definieren Sie das passende übereinstimmende Attributpaar in Ihrer Zuordnung, das Benutzer in Ihrer Quelle und Microsoft Entra ID eindeutig identifiziert.

Wie generieren wir eindeutige Werte für den UPN?

Der Bereitstellungsdienst bietet nicht die Möglichkeit, nach doppelten userPrincipalName (UPN) zu suchen und Konflikte zu behandeln. Wenn die Standardsynchronisierungsregel für das UPN-Attribut einen vorhandenen UPN-Wert generiert, schlägt der Benutzererstellungsvorgang fehl.

Hier sind einige Optionen, die Sie zum Generieren eindeutiger UPNs in Betracht ziehen können:

  1. Fügen Sie die Logik für die Generierung eindeutiger UPNs in Ihrem API-Client hinzu.
  2. Aktualisieren Sie die Synchronisierungsregel für das UPN-Attribut, um die RandomString-Funktion zu verwenden, und legen Sie den Zuordnungsparameter „zuweisen“ auf On object creation only fest. Beispiel:

Join("", Replace([userName], , "(?<Suffix>@(.)*)", "Suffix", "", , ), RandomString(3, 3, 0, 0, 0, ), "@", DefaultDomain())

  1. Wenn Sie für lokales Active Directory bereitstellen, können Sie die SelectUniqueValue-Funktion verwenden und den Zuordnungsparameter „zuordnen“ auf On object creation only festlegen.

Wie senden wir weitere HR-Attribute an den /bulkUpload-API-Endpunkt für die Bereitstellung?

Standardmäßig unterstützt der API-Endpunkt die Verarbeitung jedes Attributs, das Teil des Schemas für SCIM Core-Benutzer und Enterprise-Benutzer ist. Wenn Sie weitere Attribute senden möchten, können Sie das Bereitstellungs-App-Schema erweitern, die neuen Attribute Microsoft Entra-Attributen zuordnen und die Massenanforderung aktualisieren, um diese Attribute zu senden. Weitere Informationen finden Sie im Tutorial Erweitern der API-gesteuerten Bereitstellung zur Synchronisierung benutzerdefinierter Attribute.

Wie schließen wir bestimmte Benutzer aus dem Bereitstellungsflow aus?

Möglicherweise haben Sie ein Szenario, in dem Sie alle Benutzer an den API-Endpunkt senden möchten, aber nur bestimmte Benutzer in den Bereitstellungsflow einbeziehen und den Rest ausschließen möchten.

Sie können dies mithilfe des Bereichsfilters erreichen. In der Konfiguration der Bereitstellungs-App können Sie einen Quellobjektbereich definieren und bestimmte Benutzer von der Verarbeitung ausschließen, indem Sie entweder eine „Einschlussregel“ (z. B. nur Benutzer verarbeiten, bei denen die Abteilung GLEICH Sales ist) oder eine „Ausschlussregel“ (z. B. Ausschließen von Benutzern aus dem Vertrieb, Abteilung NICHT GLEICH Vertrieb) verwenden.

Siehe Eingrenzen von Benutzern oder Gruppen für die Bereitstellung mit Bereichsfiltern.

Wie aktualisieren wir Benutzer mithilfe des /bulkUpload-API-Endpunkts für die Bereitstellung?

Hier erfahren Sie, wie der Bereitstellungsauftrag, der dem /bulkUpload-API-Endpunkt zugeordnet ist, eingehende Benutzernutzdaten verarbeitet:

  1. Der Bereitstellungsauftrag ruft die Attributzuordnung für den Bereitstellungsauftrag ab und notiert sich das übereinstimmende Attributpaar (standardmäßig wird das externalId-API-Attribut verwendet, um mit employeeId in Microsoft Entra ID abzugleichen). Sie können dieses Standard-Attributabgleichspaar ändern.
  2. Der Auftrag extrahiert die Vorgänge aus den Massenanforderungsnutzdaten.
  3. Der Auftrag überprüft den Bezeichner für den Wertabgleich in der SCIM-Anforderung (standardmäßig das API-Attribut externalId) und verwendet ihn, um zu überprüfen, ob in Microsoft Entra ID ein Benutzer mit übereinstimmendem employeeId-Wert vorhanden ist.
  4. Wenn der Auftrag einen übereinstimmenden Benutzer findet, wendet er die Synchronisierungsregeln an und vergleicht die Quell- und Zielprofile.
  5. Wenn der Auftrag feststellt, dass sich einige Werte geändert haben, aktualisiert er den entsprechenden Benutzerdatensatz im Verzeichnis.

Um sicherzustellen, dass die richtigen Benutzer in Microsoft Entra ID aktualisiert werden, stellen Sie sicher, dass Sie das passende übereinstimmende Attributpaar in Ihrer Zuordnung definieren, das Benutzer in Ihrer Quelle und Microsoft Entra ID eindeutig identifiziert.

Können wir mehr als eine App erstellen, welche die API-gesteuerte eingehende Bereitstellung unterstützt?

Ja, das ist möglich. Hier sind einige Szenarien aufgeführt, die möglicherweise mehr als eine Bereitstellungs-App erfordern:

Szenario 1: Angenommen, Sie verfügen über drei vertrauenswürdige Datenquellen: eine für Mitarbeiter, eine für Auftragnehmer und eine für Lieferanten. Sie können drei separate Bereitstellungs-Apps erstellen – eine für jeden Identitätstyp mit ihrer eigenen Attributzuordnung. Jede Bereitstellungs-App verfügt über einen eindeutigen API-Endpunkt, und Sie können die jeweiligen Nutzdaten an jeden Endpunkt senden.

Sie können den eindeutigen API-Endpunkt für jeden Auftrag auf dem Blatt „Bereitstellung“ der Homepage abrufen. Navigieren Sie zu Statistiken bis heute>Technische Informationen anzeigen, und kopieren Sie dann die URL für den API-Endpunkt für die Bereitstellung .

Szenario 2: Angenommen, Sie verfügen über mehrere Quellen der Wahrheit, jede mit ihrem eigenen Attributsatz. Beispielsweise stellt HR Stelleninformationsattribute bereit (z. B. jobTitle, employeeType), und das Badgeverleihungssystem stellt Badgeinformationsattribute bereit (z. B badgeId, die mithilfe eines Erweiterungsattributs dargestellt wird). In diesem Szenario können Sie zwei Bereitstellungs-Apps konfigurieren:

  • Bereitstellungs-App Nr. 1, die Attribute von Ihrer HR-Quelle empfängt und den Benutzer erstellt.

  • Bereitstellungs-App Nr. 2, die Attribute vom Badgeverleihungssystem empfängt und nur die Benutzerattribute aktualisiert. Die Attributzuordnung in dieser App ist auf die Badgeinformationsattribute beschränkt, und unter Zielobjektaktionen ist nur „Aktualisieren“ aktiviert.

  • Beide Apps verwenden dasselbe übereinstimmende Bezeichnerpaar (externalId<–>employeeId)

Wie verarbeiten wir Terminierungen mithilfe des /bulkUpload-API-Endpunkts?

Um Terminierungen zu verarbeiten, identifizieren Sie ein Attribut in Ihrer Quelle, das zum Festlegen des accountEnabled-Flags in Microsoft Entra ID verwendet wird. Wenn Sie für lokales Active Directory bereitstellen, ordnen Sie dieses Quellattribute dem accountDisabled-Attribut zu.

Standardmäßig bestimmt der Wert, der dem SCIM Core User-Schemaattribut active zugeordnet ist, den Status des Kontos des Benutzers im Zielverzeichnis.

Wenn das Attribut auf WAHR festgelegt ist, aktiviert die Standardzuordnungsregel das Konto. Wenn das Attribut auf FALSCH festgelegt ist, deaktiviert die Standardzuordnungsregel das Konto.

Wie können wir verhindern, dass Benutzer versehentlich deaktiviert/gelöscht werden?

Um versehentliches Löschen zu verhindern und versehentlich gelöschte Daten wiederherzustellen, empfehlen wir, in der Bereitstellungs-App den Schwellenwert für versehentliches Löschen zu konfigurieren und den Papierkorb für lokales Active Directory zu aktivieren. Deaktivieren Sie auf dem Blatt Attributzuordnung Ihrer Bereitstellungs-App unter Zielobjektaktionen den Vorgang Löschen.

Wiederherstellen gelöschter Konten

  • Wenn das Zielverzeichnis für den Vorgang Microsoft Entra ID ist, wird der übereinstimmende Benutzer bzw. die übereinstimmende Benutzerin vorläufig gelöscht. Sie können den Benutzer oder die Benutzerin die nächsten 30 Tage im Microsoft Entra-Portal auf der Seite Gelöschte Benutzer anzeigen und während dieses Zeitraums wiederherstellen.
  • Wenn das Zielverzeichnis für den Vorgang lokales Active Directory ist, wird der übereinstimmende Benutzer bzw. die übereinstimmende Benutzerin endgültig gelöscht. Wenn der Active Directory-Papierkorb aktiviert ist, können Sie das gelöschte lokale AD-Benutzerobjekt wiederherstellen.

Müssen wir alle Benutzer aus dem HR-System bei jeder Anforderung senden?

Nein, Sie müssen nicht alle Benutzer aus dem HR-System/der „Quelle der Wahrheit“ in jeder Anforderung senden. Senden Sie einfach die Benutzer, die Sie erstellen oder aktualisieren möchten.

Unterstützt die API alle HTTP-Aktionen (GET/POST/PUT/PATCH)?

Nein, der /bulkUpload-API-Endpunkt für die Bereitstellung unterstützt nur die POST-HTTP-Aktion.

Wenn ich einen Benutzer aktualisieren möchte, muss ich eine PUT/PATCH-Anforderung senden?

Nein, der API-Endpunkt unterstützt keine PUT/PATCH-Anforderung. Um einen Benutzer zu aktualisieren, senden Sie die dem Benutzer zugeordneten Daten in den POST-Massenanforderungsnutzdaten.

Der Bereitstellungsauftrag, der vom API-Endpunkt empfangene Daten verarbeitet, erkennt automatisch, ob der in den POST-Anforderungsnutzdaten empfangene Benutzer basierend auf den konfigurierten Synchronisierungsregeln erstellt/aktualisiert/aktiviert/deaktiviert werden muss. Als API-Client müssen Sie keine weiteren Schritte ausführen, wenn Sie möchten, dass ein Benutzerprofil aktualisiert wird.

Wie wird das Rückschreiben unterstützt?

Die aktuelle API unterstützt nur eingehende Daten. Hier sind einige Optionen, die Sie für die Implementierung des Rückschreibens von Attributen wie E-Mail-Adresse/Benutzername/Telefon berücksichtigen sollten, die von Microsoft Entra ID generiert wurden und die Sie an das HR-System zurückführen können:

  • Option 1 – SCIM-Konnektivität zum HR-Endpunkt/Proxydienst, der wiederum die HR-Quelle aktualisiert

    • Wenn das Aufzeichnungssystem einen SCIM-Endpunkt für Benutzerupdates bereitstellt, können Sie eine benutzerdefinierte SCIM-Anwendung im Unternehmens-App-Katalog erstellen und die Bereitstellung wie dokumentiert konfigurieren.
    • Wenn das Aufzeichnungssystem keinen SCIM-Endpunkt bereitstellt, untersuchen Sie die Möglichkeit, einen SCIM-Proxydienst einzurichten, der das Update empfängt und die Änderung an das HR-System weitergibt.

  • Option 2 – Verwenden des Microsoft Entra Ecma International Konnektors für das Rückschreibszenario

    • Untersuchen Sie je nach Kundenanforderung, ob einer der Ecma International-Konnektoren verwendet werden könnte (PowerShell/SQL/Webdienste).

  • Option 3 – Verwenden der benutzerdefinierten Erweiterungsaufgabe für Lebenszyklus-Workflow in einem Beitritts-Workflow

Nächste Schritte