Udostępnij za pośrednictwem

Często zadawane pytania dotyczące aprowizacji przychodzącej opartej na interfejsie API

  • Artykuł

Ten artykuł zawiera odpowiedzi na często zadawane pytania dotyczące aprowizacji przychodzącej opartej na interfejsie API.

W jaki sposób nowa aprowizacja ruchu przychodzącego /bulkUpload API różni się od interfejsu API użytkowników programu MS Graph?

Istnieją znaczące różnice między aprowizowaniem /bulkUpload API i punktem końcowym interfejsu API użytkowników programu MS Graph.

  • Format ładunku: punkt końcowy interfejsu API użytkowników programu MS Graph oczekuje danych w formacie OData. Format ładunku żądania dla nowej aprowizacji ruchu przychodzącego /bulkUpload API używa konstrukcji schematu SCIM. Podczas wywoływania tego interfejsu API ustaw nagłówek "Content-Type" na application/scim+jsonwartość .
  • Wynik końcowy operacji:
    • Gdy dane tożsamości są wysyłane do punktu końcowego interfejsu API użytkowników programu MS Graph, są one natychmiast przetwarzane, a operacja Tworzenia/aktualizowania/usuwania odbywa się w profilu użytkownika firmy Microsoft Entra.
    • Żądanie danych wysyłanych do interfejsu API aprowizacji /bulkUpload jest przetwarzane asynchronicznie przez usługę aprowizacji firmy Microsoft. Zadanie aprowizacji stosuje reguły określania zakresu, mapowanie atrybutów i przekształcanie skonfigurowane przez administratora IT. Spowoduje to zainicjowanie Create/Update/Delete operacji w profilu użytkownika microsoft Entra lub lokalnego profilu użytkownika usługi AD.
  • Administrator IT zachowuje kontrolę: dzięki aprowizacji przychodzącej opartej na interfejsie API administrator IT ma większą kontrolę nad tym, jak są przetwarzane i mapowane na atrybuty usługi Microsoft Entra. Mogą zdefiniować reguły określania zakresu, aby wykluczyć niektóre typy danych tożsamości (na przykład dane wykonawcy) i użyć funkcji przekształcania, aby uzyskać nowe wartości przed ustawieniem wartości atrybutów w profilu użytkownika.

Czy aprowizacja ruchu przychodzącego /bulkUpload API jest standardowym punktem końcowym SCIM?

Interfejs API inicjowania obsługi ruchu przychodzącego /bulkUpload programu MS Graph używa schematu SCIM w ładunku żądania, ale nie jest to ustandaryzowany punkt końcowy interfejsu API SCIM. Oto przyczyny.

Zazwyczaj punkt końcowy usługi SCIM przetwarza żądania HTTP (POST, PUT, GET) z ładunkiem SCIM i tłumaczy je na odpowiednie operacje (Create, Update, Lookup) w magazynie tożsamości. Punkt końcowy usługi SCIM umieszcza na komputerze klienckim interfejsu API SCIM możliwość określania semantyki operacji, czy należy utworzyć/zaktualizować/usunąć tożsamość. Ten mechanizm działa dobrze w scenariuszach, w których klient interfejsu API zdaje sobie sprawę z tego, jaką operację ma wykonać dla użytkowników w magazynie tożsamości.

Aprowizacja ruchu przychodzącego /bulkUpload programu MS Graph została zaprojektowana w celu obsługi innego scenariusza integracji tożsamości przedsiębiorstwa w kształcie trzech unikatowych wymagań:

  1. Możliwość asynchronicznego przetwarzania rekordów zbiorczo (na przykład przetwarzania rekordów 50K+ )
  2. Możliwość uwzględnienia dowolnego atrybutu tożsamości w ładunku (na przykład costCenter, pay grade, badgeId)
  3. Obsługa klientów interfejsu API nieświadomych semantyki operacji. Ci klienci są klientami interfejsu API innych niż SCIM, którzy mają dostęp tylko do nieprzetworzonych danych źródłowych (na przykład rekordów w pliku CSV, tabeli SQL lub rekordach HR). Ci klienci nie mają możliwości przetwarzania do odczytywania każdego rekordu i określania semantyki Create/Update/Delete operacji w magazynie tożsamości.

Głównym celem aprowizacji ruchu przychodzącego /bulkUpload INTERFEJSu API MS Graph jest umożliwienie klientom wysyłania dowolnych danych tożsamości (na przykład costCenter, pay grade, badgeId) z dowolnego źródła danych tożsamości (na przykład CSV/SQL/HR) na potrzeby przetwarzania końcowego przez usługę aprowizacji firmy Microsoft Entra. Usługa aprowizacji firmy Microsoft korzysta z danych ładunku zbiorczego odebranych w tym punkcie końcowym, stosuje reguły mapowania atrybutów skonfigurowane przez administratora IT i określa, czy ładunek danych prowadzi do operacji (Tworzenie, aktualizowanie, włączanie, wyłączanie) w docelowym magazynie tożsamości (Microsoft Entra ID / lokalna usługa AD).

Czy aprowizacja /bulkUpload API obsługuje domeny lokalna usługa Active Directory jako obiekt docelowy?

Tak, interfejs API aprowizacji obsługuje lokalne domeny usługi AD jako obiekt docelowy.

Jak uzyskać punkt końcowy interfejsu API /bulkUpload dla naszej aplikacji aprowizacji?

Interfejs API /bulkUpload jest dostępny tylko dla aplikacji tego typu: "Aprowizowanie przychodzące oparte na interfejsie API do identyfikatora Entra firmy Microsoft" i "inicjowanie obsługi ruchu przychodzącego opartego na interfejsie API w celu lokalna usługa Active Directory". Unikatowy punkt końcowy interfejsu API dla każdej aplikacji aprowizacji można pobrać ze strony głównej bloku Aprowizacja. W obszarze Statystyki do daty>Wyświetl informacje techniczne skopiuj adres URL punktu końcowego interfejsu API aprowizacji.

Ma on format:

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

Jak przeprowadzić pełną synchronizację przy użyciu interfejsu API aprowizacji /bulkUpload?

Aby przeprowadzić pełną synchronizację, użyj klienta interfejsu API, aby wysłać dane wszystkich użytkowników z zaufanego źródła do punktu końcowego interfejsu API jako żądanie zbiorcze. Po wysłaniu wszystkich danych do punktu końcowego interfejsu API następny cykl synchronizacji przetwarza wszystkie rekordy użytkowników i umożliwia śledzenie postępu przy użyciu punktu końcowego interfejsu API dzienników aprowizacji.

Jak przeprowadzić synchronizację różnicy przy użyciu interfejsu API aprowizacji /bulkUpload?

Aby przeprowadzić synchronizację różnicową, użyj klienta interfejsu API, aby wysyłać tylko informacje o użytkownikach, których dane uległy zmianie w zaufanym źródle. Po wysłaniu wszystkich danych do punktu końcowego interfejsu API następny cykl synchronizacji przetwarza wszystkie rekordy użytkowników i umożliwia śledzenie postępu przy użyciu punktu końcowego interfejsu API dzienników aprowizacji.

Jak działa ponowne inicjowanie obsługi administracyjnej?

Użyj opcji Ponowne uruchamianie aprowizacji tylko w razie potrzeby. Oto, jak to działa:

Scenariusz 1: Po kliknięciu przycisku Ponowne uruchamianie aprowizacji i aktualnie uruchomione zadanie kontynuuje przetwarzanie istniejących danych, które są już przygotowane. Operacja ponownego inicjowania obsługi administracyjnej nie przerywa istniejącego cyklu. W kolejnym cyklu usługa aprowizacji czyści wszelkie depozyty i wybiera nowe żądanie zbiorcze do przetworzenia.

Scenariusz 2: Po kliknięciu przycisku Ponowne uruchamianie aprowizacji i nie jest uruchomione zadanie, przed uruchomieniem kolejnego cyklu aparat aprowizacji czyści dane przekazane przed ponownym uruchomieniem, czyści wszelkie depozyty i przetwarza tylko nowe dane przychodzące.

Jak utworzyć użytkowników przy użyciu punktu końcowego interfejsu API aprowizacji /bulkUpload?

Oto jak zadanie aprowizacji skojarzone z punktem końcowym interfejsu API /bulkUpload przetwarza przychodzące ładunki użytkownika:

  1. Zadanie pobiera mapowanie atrybutów dla zadania aprowizacji i zanotuje zgodną parę atrybutów (domyślnie externalId atrybut interfejsu API jest używany do dopasowania z identyfikatorem employeeId Entra firmy Microsoft).
  2. Tę domyślną parę dopasowania atrybutów można zmienić.
  3. Zadanie wyodrębnia każdą operację obecną w ładunku żądania zbiorczego.
  4. Zadanie sprawdza identyfikator dopasowania wartości w żądaniu (domyślnie atrybut externalId) i używa go do sprawdzania, czy w identyfikatorze Entra firmy Microsoft istnieje użytkownik z pasującą employeeId wartością.
  5. Jeśli zadanie nie znajdzie pasującego użytkownika, zadanie stosuje reguły synchronizacji i tworzy nowego użytkownika w katalogu docelowym.

Aby upewnić się, że odpowiedni użytkownicy są utworzeni w identyfikatorze Entra firmy Microsoft, zdefiniuj odpowiednią zgodną parę atrybutów w mapowaniu, która unikatowo identyfikuje użytkowników w źródle i identyfikatorze Entra firmy Microsoft.

Jak generować unikatowe wartości dla nazwy UPN?

Usługa aprowizacji nie zapewnia możliwości sprawdzania pod kątem zduplikowanych userPrincipalName (UPN) i obsługi konfliktów. Jeśli domyślna reguła synchronizacji atrybutu nazwy UPN generuje istniejącą wartość nazwy UPN, operacja tworzenia użytkownika zakończy się niepowodzeniem.

Poniżej przedstawiono kilka opcji, które można wziąć pod uwagę podczas generowania unikatowych nazw UPN:

  1. Dodaj logikę unikatowej generacji nazwy UPN w kliencie interfejsu API.
  2. Zaktualizuj regułę synchronizacji atrybutu nazwy UPN, aby użyć funkcji RandomString i ustawić zastosuj parametr mapowania na On object creation onlywartość . Przykład:

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

  1. Jeśli aprowizujesz lokalna usługa Active Directory, możesz użyć funkcji SelectUniqueValue i ustawić parametr zastosuj mapowanie na On object creation onlywartość .

Jak wysyłać więcej atrybutów hr do punktu końcowego interfejsu API aprowizacji /bulkUpload?

Domyślnie punkt końcowy interfejsu API obsługuje przetwarzanie dowolnego atrybutu będącego częścią schematu użytkownika podstawowego SCIM i użytkownika przedsiębiorstwa. Jeśli chcesz wysłać więcej atrybutów, możesz rozszerzyć schemat aplikacji aprowizacji, zamapować nowe atrybuty na atrybuty firmy Microsoft Entra i zaktualizować żądanie zbiorcze, aby wysłać te atrybuty. Zapoznaj się z samouczkiem Rozszerzanie aprowizacji opartej na interfejsie API w celu synchronizacji atrybutów niestandardowych.

Jak wykluczyć niektórych użytkowników z przepływu aprowizacji?

Może istnieć scenariusz, w którym chcesz wysłać wszystkich użytkowników do punktu końcowego interfejsu API, ale uwzględnić tylko niektórych użytkowników w przepływie aprowizacji i wykluczyć resztę.

Można to osiągnąć przy użyciu filtru określania zakresu. W konfiguracji aplikacji aprowizacji można zdefiniować zakres obiektu źródłowego i wykluczyć niektórych użytkowników z przetwarzania przy użyciu "reguły dołączania" (na przykład tylko przetwarzać użytkowników, gdzie dział EQUALS Sales) lub "regułę wykluczania" (na przykład wykluczać użytkowników należących do działu Sprzedaż, dział NIE RÓWNA sprzedaży).

Zobacz Określanie zakresu użytkowników lub grup do aprowizacji przy użyciu filtrów określania zakresu.

Jak zaktualizować użytkowników przy użyciu punktu końcowego interfejsu API aprowizacji /bulkUpload?

Oto jak zadanie aprowizacji skojarzone z punktem końcowym interfejsu API /bulkUpload przetwarza przychodzące ładunki użytkownika:

  1. Zadanie aprowizacji pobiera mapowanie atrybutów dla zadania aprowizacji i zanotuje zgodną parę atrybutów (domyślnie externalId atrybut interfejsu API jest używany do dopasowania z identyfikatorem employeeId Entra firmy Microsoft). Tę domyślną parę dopasowania atrybutów można zmienić.
  2. Zadanie wyodrębnia operacje z ładunku żądania zbiorczego.
  3. Zadanie sprawdza wartość pasującą identyfikator w żądaniu SCIM (domyślnie: atrybut externalIdinterfejsu API) i używa go do sprawdzenia, czy istnieje użytkownik w usłudze Microsoft Entra ID z pasującą employeeId wartością.
  4. Jeśli zadanie znajdzie pasującego użytkownika, stosuje reguły synchronizacji i porównuje profile źródłowe i docelowe.
  5. Jeśli zadanie określi, że niektóre wartości uległy zmianie, zaktualizuje odpowiedni rekord użytkownika w katalogu.

Aby upewnić się, że odpowiedni użytkownicy są aktualizowani w identyfikatorze Entra firmy Microsoft, upewnij się, że w mapowaniu zdefiniowano odpowiednią parę atrybutów pasujących, która jednoznacznie identyfikuje użytkowników w źródle i identyfikatorze Entra firmy Microsoft.

Czy można utworzyć więcej niż jedną aplikację, która obsługuje aprowizację przychodzącą opartą na interfejsie API?

Tak, możesz. Poniżej przedstawiono niektóre scenariusze, które mogą wymagać więcej niż jednej aplikacji aprowizacji:

Scenariusz 1: Załóżmy, że masz trzy zaufane źródła danych: jeden dla pracowników, jeden dla wykonawców i jeden dla dostawców. Możesz utworzyć trzy oddzielne aplikacje aprowizacji — po jednym dla każdego typu tożsamości z własnym odrębnym mapowaniem atrybutów. Każda aplikacja aprowizacji ma unikatowy punkt końcowy interfejsu API i można wysłać odpowiednie ładunki do każdego punktu końcowego.

Unikatowy punkt końcowy interfejsu API dla każdego zadania można pobrać ze strony głównej bloku Aprowizacja. Przejdź do pozycji Statystyki do daty>Wyświetl informacje techniczne, a następnie skopiuj adres URL punktu końcowego interfejsu API aprowizacji.

Scenariusz 2: Załóżmy, że masz wiele źródeł prawdy, z których każdy ma własny zestaw atrybutów. Na przykład dział kadr udostępnia atrybuty informacji o zadaniu (na przykład jobTitle, employeeType), a system badging udostępnia atrybuty informacji o znaczek (na przykład badgeId reprezentowane przy użyciu atrybutu rozszerzenia). W tym scenariuszu można skonfigurować dwie aplikacje aprowizacji:

  • Aprowizacja aplikacji nr 1 , która odbiera atrybuty ze źródła kadr i tworzy użytkownika.

  • Aprowizacja aplikacji nr 2 , która odbiera atrybuty z systemu Badging i aktualizuje tylko atrybuty użytkownika. Mapowanie atrybutów w tej aplikacji jest ograniczone do atrybutów informacje o wskaźniku i w obszarze Akcje obiektów docelowych jest włączona tylko aktualizacja.

  • Obie aplikacje używają tej samej zgodnej pary identyfikatorów (externalId<->employeeId)

Jak przetwarzamy zakończenia przy użyciu punktu końcowego interfejsu API /bulkUpload?

Aby przetworzyć zakończenia, zidentyfikuj atrybut w źródle, który będzie używany do ustawiania accountEnabled flagi w identyfikatorze Entra firmy Microsoft. Jeśli aprowizujesz lokalna usługa Active Directory, zamapuj accountDisabled ten atrybut źródłowy na atrybut .

Domyślnie wartość skojarzona z atrybutem active schematu użytkownika podstawowego SCIM określa stan konta użytkownika w katalogu docelowym.

Jeśli atrybut ma wartość true, domyślna reguła mapowania włącza konto. Jeśli atrybut ma wartość false, domyślna reguła mapowania wyłącza konto.

Jak można zapobiec przypadkowemu wyłączeniu/usunięciu użytkowników?

Aby zapobiec przypadkowemu usunięciu i odzyskać je, zalecamy skonfigurowanie progu przypadkowego usunięcia w aplikacji aprowizacji i włączenie kosza lokalna usługa Active Directory. W bloku Mapowanie atrybutów aplikacji aprowizacji w obszarze Akcje obiektu docelowego wyłącz operację Usuń.

Odzyskiwanie usuniętych kont

  • Jeśli katalog docelowy operacji to Microsoft Entra ID, dopasowany użytkownik zostanie usunięty nietrwale. Użytkownik może być widoczny na stronie Microsoft Entra Admin Center Deleted users (Usunięte użytkownicy ) przez następne 30 dni i można go przywrócić w tym czasie.
  • Jeśli katalog docelowy operacji jest lokalna usługa Active Directory, dopasowany użytkownik zostanie trwale usunięty. Jeśli Kosz usługi Active Directory jest włączony, możesz przywrócić usunięty obiekt użytkownika lokalnej usługi AD.

Czy musimy wysłać wszystkich użytkowników z systemu KADR w każdym żądaniu?

Nie, nie musisz wysyłać wszystkich użytkowników z systemu HR / "źródła prawdy" w każdym żądaniu. Wystarczy wysłać użytkowników, których chcesz utworzyć lub zaktualizować.

Czy interfejs API obsługuje wszystkie akcje HTTP (GET/POST/PUT/PATCH)?

Nie, punkt końcowy interfejsu API aprowizacji /bulkUpload obsługuje tylko akcję POST HTTP.

Jeśli chcę zaktualizować użytkownika, czy muszę wysłać żądanie PUT/PATCH?

Nie, punkt końcowy interfejsu API nie obsługuje żądania PUT/PATCH. Aby zaktualizować użytkownika, wyślij dane skojarzone z użytkownikiem w ładunku żądania zbiorczego POST.

Zadanie aprowizacji, które przetwarza dane odebrane przez punkt końcowy interfejsu API, automatycznie wykrywa, czy użytkownik otrzymany w ładunku żądania POST musi zostać utworzony/zaktualizowany/włączony/wyłączony na podstawie skonfigurowanych reguł synchronizacji. Jako klient interfejsu API nie musisz wykonywać kolejnych kroków, jeśli chcesz zaktualizować profil użytkownika.

Jak jest obsługiwana funkcja zapisywania zwrotnego?

Bieżący interfejs API obsługuje tylko dane przychodzące. Poniżej przedstawiono kilka opcji, które należy wziąć pod uwagę w przypadku implementowania zapisywania zwrotnego atrybutów, takich jak adres e-mail/ nazwa użytkownika/ telefon wygenerowany przez firmę Microsoft Entra ID, które można wrócić do systemu HR:

  • Opcja 1 — łączność SCIM z punktem końcowym HR/usługą proxy, która z kolei aktualizuje źródło hr

    • Jeśli system rekordów udostępnia punkt końcowy SCIM dla aktualizacji użytkowników, możesz utworzyć niestandardową aplikację SCIM w galerii aplikacji dla przedsiębiorstw i skonfigurować aprowizację zgodnie z dokumentacją.
    • Jeśli system rekordów nie zapewnia punktu końcowego SCIM, zapoznaj się z możliwością skonfigurowania usługi SCIM serwera proxy, która odbiera aktualizację i propaguje zmianę w systemie HR.

  • Opcja 2 — używanie łącznika Microsoft Entra ECMA na potrzeby scenariusza zapisywania zwrotnego

    • W zależności od wymagania klienta sprawdź, czy można użyć jednego z łączników ECMA (PowerShell / SQL / Web Services).

  • Opcja 3 — użyj niestandardowego zadania rozszerzenia przepływów pracy cyklu życia w przepływie pracy narzędzia joiner

Następne kroki