Udostępnij przez

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

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

W jaki sposób nowa usługa aprowizacji przychodzącej /bulkUpload API różni się od interfejsu API użytkowników 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 zawartości żądania dla nowego prowizjonowania przychodzącego API /bulkUpload używa konstrukcji schematu SCIM. Podczas wywoływania tego interfejsu API ustaw nagłówek "Content-Type" na application/scim+json.
  • 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 przesłania danych do interfejsu aprowizacji API /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 dane tożsamości są przetwarzane i przypisywane do atrybutów 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 API do aprowizacji w ruchu przychodzącym /bulkUpload 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 dlaczego.

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 nakłada na klienta interfejsu API SCIM odpowiedzialność za określenie semantyki operacji, czy należy utworzyć, zaktualizować, czy 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 danych w celu odczytu każdego rekordu i określania semantyki operacji Create/Update/Delete w repozytorium 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 Microsoft Entra przetwarza dane zbiorcze odebrane w tym endpointzie, stosuje reguły mapowania atrybutów skonfigurowane przez administratora IT i określa, czy dane prowadzą do operacji (tworzenie, aktualizowanie, włączanie, wyłączanie) w docelowym repozytorium tożsamości (Microsoft Entra ID / lokalna usługa AD).

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

Tak, interfejs API aprowizacji obsługuje lokalne domeny Active Directory jako cel.

Jak uzyskać punkt końcowy interfejsu API /bulkUpload dla naszej aplikacji do zarządzania zasobami?

Interfejs API /bulkUpload jest dostępny tylko dla aplikacji typu: "Aprowizowanie przychodzące oparte na interfejsie API do Microsoft Entra ID" oraz "aprowizowanie przychodzące oparte na interfejsie API do lokalnego Active Directory". Unikatowy punkt końcowy interfejsu API dla każdej aplikacji aprowizacji można pobrać ze strony głównej bloku Aprowizacja. W sekcji Statystyki do tej pory>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 wykonać pełną synchronizację, korzystając z 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ę delta przy użyciu interfejsu API aprowizacji /bulkUpload?

Aby przeprowadzić synchronizację różnicową, użyj klienta 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 uruchomienie konfiguracji?

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 ponownej konfiguracji 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, gdy zadanie nie jest wykonywane, przed uruchomieniem kolejnego cyklu silnik aprowizacji usuwa dane przekazane przed ponownym uruchomieniem, czyści wszelkie zabezpieczenia 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 danych żądania zbiorczego.
  4. Zadanie sprawdza identyfikator dopasowujący wartość w żądaniu (domyślnie atrybut externalId), i używa go do sprawdzania, czy w Microsoft Entra ID istnieje użytkownik z pasującą wartością employeeId.
  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ć unikalne wartości dla UPN?

Usługa aprowizacji nie zapewnia możliwości sprawdzania duplikatów userPrincipalName (UPN) i zarządzania konfliktami. 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ę przy generowaniu unikatowych UPN.

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

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

  1. Jeśli aprowizujesz lokalny Active Directory, możesz użyć funkcji SelectUniqueValue i ustawić parametr "zastosuj mapowanie" na On object creation only.

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 procesu uzyskiwania dostępu?

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 włączania" (na przykład przetwarzać tylko tych użytkowników, dla których dział RÓWNA SIĘ Sprzedaż) lub "reguły wykluczania" (na przykład wykluczyć użytkowników należących do działu Sprzedaż, gdzie dział NIE RÓWNA SIĘ Sprzedaż).

Zobacz Określanie zakresu użytkowników lub grup do aprowizacji za pomocą 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ść odpowiadającą identyfikatorowi w żądaniu SCIM (domyślnie: atrybut externalId interfejsu API) i używa go do sprawdzenia, czy istnieje użytkownik w Microsoft Entra ID z odpowiadającą wartością employeeId.
  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 wysył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 na dzień dzisiejszy>Wyświetl informacje techniczne, a następnie skopiuj adres URL punktu końcowego interfejsu API konfiguracji.

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 pracy (na przykład jobTitle, employeeType), a system identyfikacji udostępnia atrybuty informacji o odznakach (na przykład badgeId, które są reprezentowane przy użyciu atrybutu rozszerzenia). W tym scenariuszu można skonfigurować dwie aplikacje aprowizacji:

  • Udostępnienie aplikacji nr 1, która otrzymuje atrybuty ze źródła kadr i tworzy użytkownika.

  • Aplikacja Aprowizacyjna nr 2, która odbiera atrybuty z systemu Badging i aktualizuje wyłącznie atrybuty użytkownika. Mapowanie atrybutów w tej aplikacji jest ograniczone do atrybutów Informacje o odznace, i w obszarze Akcje obiektów docelowych włączona jest tylko aktualizacja.

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

Jak przetwarzamy zakończenia procesów za pomocą 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 udostępniasz zasoby do lokalnej usługi Active Directory, przypisz ten atrybut źródłowy do atrybutu accountDisabled.

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 lokalnego kosza usługi Active Directory. W sekcji 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 lokalną usługą 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 w każdym żądaniu wysyłać wszystkich użytkowników z systemu HR?

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 atrybutów z powrotem, takich jak adres e-mail/nazwa użytkownika/telefon wygenerowany przez firmę Microsoft Entra ID, które można przekazać z powrotem do systemu HR.

  • Opcja 1 — łączność SCIM z punktem końcowym HR/usługą proxy, która następnie 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 ewidencji nie zapewnia punktu końcowego SCIM, rozważ możliwość skonfigurowania serwera proxy SCIM, który aktualizuje i wprowadza zmiany do systemu 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

Dalsze kroki

  • Last updated on