Nejčastější dotazy týkající se příchozího zřizování řízeného rozhraním API

Tento článek odpovídá na nejčastější dotazy týkající se příchozího zřizování řízeného rozhraním API.

Jak se nové příchozí zřizování /bulkUpload API liší od rozhraní MS Graph Users API?

Mezi rozhraním API pro zřizování /bulkUpload a koncovým bodem rozhraní MS Graph Users API existují značné rozdíly.

• Formát datové části: Koncový bod rozhraní MS Graph Users API očekává data ve formátu OData. Formát datové části požadavku pro nové příchozí zřizování /bulkUpload API používá konstruktory schématu SCIM. Při vyvolání tohoto rozhraní API nastavte hlavičku Content-Type na application/scim+jsonhodnotu .
• Konečný výsledek operace:
  • Když se data identity odešlou do koncového bodu rozhraní MS Graph Users API, okamžitě se zpracuje a v profilu uživatele Microsoft Entra se provede operace Vytvoření/aktualizace/odstranění.
  • Požadavek na data odesílaná do rozhraní API pro zřizování /bulkUpload se zpracovává asynchronně službou zřizování Microsoft Entra. Úloha zřizování používá pravidla oborů, mapování atributů a transformaci nakonfigurované správcem IT. Tím se zahájí Create/Update/Delete operace v profilu uživatele Microsoft Entra nebo v místním profilu uživatele AD.
• Správce IT zachovává kontrolu: Při příchozím zřizování řízeném rozhraním API má správce IT větší kontrolu nad tím, jak se příchozí data identit zpracovávají a mapují na atributy Microsoft Entra. Mohou definovat pravidla rozsahu pro vyloučení určitých typů dat identity (například zhotovitelů) a použít transformační funkce k odvození nových hodnot před nastavením hodnot atributů v profilu uživatele.

Je příchozí zřizování /bulkUpload API standardním koncovým bodem SCIM?

Příchozí zřizování ms Graphu /bulkUpload API používá schéma SCIM v datové části požadavku, ale nejedná se o standardizovaný koncový bod rozhraní API SCIM. Tady jsou důvody.

Koncový bod služby SCIM obvykle zpracovává požadavky HTTP (POST, PUT, GET) s datovou částí SCIM a překládá je do příslušných operací (Create, Update, Lookup) v úložišti identit. Koncový bod služby SCIM umístí na klienta rozhraní API SCIM hodnotu onus určující sémantiku operace, zda se má vytvořit, aktualizovat nebo odstranit identitu. Tento mechanismus funguje dobře ve scénářích, kdy klient rozhraní API ví, jakou operaci by chtěl pro uživatele v úložišti identit provádět.

Příchozí zřizování /bulkUpload v MS Graphu je navržené tak, aby zpracovával jiný scénář integrace podnikové identity tvarovaný třemi jedinečnými požadavky:

1. Schopnost hromadně zpracovávat záznamy asynchronně (například zpracování záznamů o 50 tisících a více)
2. Možnost zahrnout do datové části jakýkoli atribut identity (například costCenter, platová známka, badgeId)
3. Klienti rozhraní API podpory neznají sémantiku operací. Tito klienti nejsou klienti rozhraní API SCIM, kteří mají přístup jenom k nezpracovaným zdrojovým datům (například záznamy v souboru CSV, tabulce SQL nebo záznamech HR). Tito klienti nemají schopnost zpracování číst každý záznam a určit sémantiku Create/Update/Delete operací v úložišti identit.

Hlavním cílem příchozího zřizování /bulkUpload API služby MS Graph je umožnit zákazníkům odesílat veškerá data identity (například costCenter, pay grade, badgeId) z libovolného zdroje dat identity (například CSV/SQL/HR) pro případné zpracování službou zřizování Microsoft Entra. Služba zřizování Microsoft Entra využívá data hromadné datové části přijatá v tomto koncovém bodu, používá pravidla mapování atributů nakonfigurovaná správcem IT a určuje, jestli datová část vede k operaci (Vytvoření, aktualizace, povolení, zákaz) v cílovém úložišti identit (Microsoft Entra ID / místní AD).

Podporuje rozhraní API pro zřizování /bulkUpload místní Active Directory domény jako cíl?

Ano, rozhraní API pro zřizování podporuje místní domény AD jako cíl.

Jak získáme koncový bod rozhraní API /bulkUpload pro naši aplikaci zřizování?

Rozhraní API /bulkUpload je k dispozici pouze pro aplikace typu: Příchozí zřizování řízené rozhraním API pro Microsoft Entra ID a příchozí zřizování řízené rozhraním API pro místní Active Directory. Jedinečný koncový bod rozhraní API pro každou aplikaci zřizování můžete načíst z domovské stránky okna Zřizování. V části Statistika k datu>Zobrazte technické informace, zkopírujte adresu URL koncového bodu rozhraní API zřizování.

Má formát:

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

Jak provádíme úplnou synchronizaci pomocí rozhraní API pro zřizování /bulkUpload?

Pokud chcete provést úplnou synchronizaci, pomocí klienta rozhraní API odešlete data všech uživatelů z důvěryhodného zdroje do koncového bodu rozhraní API jako hromadný požadavek. Jakmile odešlete všechna data do koncového bodu rozhraní API, další cyklus synchronizace zpracuje všechny záznamy uživatelů a umožňuje sledovat průběh pomocí koncového bodu rozhraní API protokolů zřizování.

Jak provádíme rozdílovou synchronizaci pomocí rozhraní API pro zřizování /bulkUpload?

Pokud chcete provést rozdílovou synchronizaci, použijte klienta rozhraní API k odesílání pouze informací o uživatelích, jejichž data se změnila v důvěryhodném zdroji. Jakmile odešlete všechna data do koncového bodu rozhraní API, další cyklus synchronizace zpracuje všechny záznamy uživatelů a umožňuje sledovat průběh pomocí koncového bodu rozhraní API protokolů zřizování.

Jak funguje restartování zřizování?

Možnost Restartovat zřizování použijte pouze v případě potřeby. Jak to funguje:

Scénář 1: Když kliknete na tlačítko Restartovat zřizování a úloha je aktuálně spuštěná, úloha bude dál zpracovávat existující data, která jsou již připravená. Operace restartování zřizování nepřeruší existující cyklus. V následujícím cyklu služba zřizování vymaže všechny escrows a vybere novou hromadnou žádost o zpracování.

Scénář 2: Když kliknete na tlačítko Pro restartování zřizování a úloha není spuštěná, modul zřizování vymaže data nahraná před restartováním, vymaže všechny escrows a zpracuje pouze nová příchozí data.

Jak vytvoříme uživatele pomocí koncového bodu rozhraní API pro zřizování /bulkUpload?

Tady je postup, jak úloha zřizování přidružená ke koncovému bodu rozhraní API /bulkUpload zpracovává příchozí datové části uživatelů:

1. Úloha načte mapování atributů pro úlohu zřizování a poznameneje si odpovídající dvojici atributů (ve výchozím nastavení externalId se atribut rozhraní API používá ke shodě s employeeId ID Microsoft Entra).
2. Tento výchozí pár porovnávání atributů můžete změnit.
3. Úloha extrahuje každou operaci, která se nachází v datové části hromadného požadavku.
4. Úloha zkontroluje identifikátor odpovídající hodnoty v požadavku (ve výchozím nastavení atribut externalId) a použije ho ke kontrole, jestli je uživatel v Microsoft Entra ID s odpovídající employeeId hodnotou.
5. Pokud úloha nenajde odpovídajícího uživatele, použije úloha pravidla synchronizace a vytvoří nového uživatele v cílovém adresáři.

Abyste měli jistotu, že se v ID Microsoft Entra vytvoří správný pár atributů, definujte ve svém mapování správný pár atributů, který jednoznačně identifikuje uživatele ve zdroji a v Microsoft Entra ID.

Jak vygenerujeme jedinečné hodnoty hlavního názvu uživatele (UPN)?

Služba zřizování neposkytuje možnost kontrolovat duplicitní ( userPrincipalName UPN) a zpracovávat konflikty. Pokud výchozí pravidlo synchronizace atributu UPN vygeneruje existující hodnotu hlavního názvu uživatele (UPN), operace vytvoření uživatele selže.

Tady je několik možností, které můžete zvážit při generování jedinečných hlavních názvů hlavních názvů (UPN):

1. Přidejte logiku pro jedinečné generování hlavního názvu uživatele (UPN) v klientovi rozhraní API.
2. Aktualizujte pravidlo synchronizace atributu UPN tak, aby používalo funkci RandomString a nastavil parametr apply mapping na On object creation only. Příklad:

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

3. Pokud zřizujete pro místní Active Directory, můžete použít funkci SelectUniqueValue a nastavit parametr použít mapování na On object creation only.

Jak do koncového bodu rozhraní API pro zřizování /bulkUpload odesíláme další atributy personálního oddělení?

Koncový bod rozhraní API ve výchozím nastavení podporuje zpracování jakéhokoli atributu, který je součástí schématu uživatele SCIM Core a podnikového uživatele. Pokud chcete odeslat další atributy, můžete rozšířit schéma zřizovací aplikace, namapovat nové atributy na atributy Microsoft Entra a aktualizovat hromadný požadavek tak, aby tyto atributy odeslal. Projděte si kurz rozšíření zřizování řízeného rozhraním API pro synchronizaci vlastních atributů.

Jak vyloučíme určité uživatele z toku zřizování?

Můžete mít scénář, ve kterém chcete odeslat všechny uživatele do koncového bodu rozhraní API, ale zahrnout do toku zřizování jenom určité uživatele a vyloučit zbytek.

Toho dosáhnete pomocí filtru oborů. V konfiguraci zřizovací aplikace můžete definovat obor zdrojového objektu a vyloučit některé uživatele ze zpracování buď pomocí pravidla zahrnutí (například pouze zpracovat uživatele, kteří se shodují s prodejem oddělení) nebo "pravidlo vyloučení" (například vyloučit uživatele patřící k prodeji, oddělení NEROVNÁ PRODEJ).

Podívejte se na otázky týkající se uživatelů nebo skupin, které se mají zřídit pomocí filtrů oborů.

Jak aktualizujeme uživatele pomocí koncového bodu rozhraní API pro zřizování /bulkUpload?

Tady je postup, jak úloha zřizování přidružená ke koncovému bodu rozhraní API /bulkUpload zpracovává příchozí datové části uživatelů:

1. Úloha zřizování načte mapování atributů pro úlohu zřizování a poznameneje si odpovídající dvojici atributů (ve výchozím nastavení externalId se atribut rozhraní API používá ke shodě employeeId s id Microsoft Entra). Tento výchozí pár porovnávání atributů můžete změnit.
2. Úloha extrahuje operace z datové části hromadné žádosti.
3. Úloha zkontroluje identifikátor odpovídající hodnoty v požadavku SCIM (ve výchozím nastavení: atribut externalIdrozhraní API) a použije ho ke kontrole, jestli je uživatel v ID Microsoft Entra s odpovídající employeeId hodnotou.
4. Pokud úloha najde odpovídajícího uživatele, použije pravidla synchronizace a porovná zdrojové a cílové profily.
5. Pokud úloha zjistí, že se některé hodnoty změnily, aktualizuje odpovídající záznam uživatele v adresáři.

Abyste měli jistotu, že se správné uživatele aktualizují v Microsoft Entra ID, ujistěte se, že v mapování definujete správný pár atributů, který jednoznačně identifikuje uživatele ve zdroji a Id Microsoft Entra.

Můžeme vytvořit více než jednu aplikaci, která podporuje příchozí zřizování řízené rozhraním API?

Ano, můžete. Tady je několik scénářů, které můžou vyžadovat více než jednu aplikaci zřizování:

Scénář 1: Řekněme, že máte tři důvěryhodné zdroje dat: jeden pro zaměstnance, jeden pro dodavatele a jeden pro dodavatele. Můžete vytvořit tři samostatné aplikace pro zřizování – jednu pro každý typ identity s vlastním jedinečným mapováním atributů. Každá aplikace zřizování má jedinečný koncový bod rozhraní API a příslušné datové části můžete odeslat do každého koncového bodu.

Jedinečný koncový bod rozhraní API pro každou úlohu můžete načíst z domovské stránky okna Zřizování. Přejděte na Statistika k datu>Zobrazte technické informace a zkopírujte adresu URL koncového bodu rozhraní API zřizování.

Scénář 2: Řekněme, že máte více zdrojů pravdy, z nichž každá má vlastní sadu atributů. Hr například poskytuje atributy informací o zaměstnání (například jobTitle, employeeType) a Badging System poskytuje atributy informací o odznáčku (například badgeId reprezentované pomocí atributu rozšíření). V tomto scénáři můžete nakonfigurovat dvě zřizovací aplikace:

• Zřizování aplikace č. 1 , která přijímá atributy z vašeho zdroje lidských zdrojů a vytváří uživatele.

• Zřizování aplikace č. 2 , která přijímá atributy ze systému Badging a aktualizuje pouze atributy uživatele. Mapování atributů v této aplikaci je omezeno na atributy Informace o odznaku a v části Akce cílového objektu je povolena pouze aktualizace.

• Obě aplikace používají stejný pár shodných identifikátorů (externalId<->employeeId).

Jak zpracováváme ukončení pomocí koncového bodu rozhraní API /bulkUpload?

Pokud chcete zpracovat ukončení, identifikujte ve zdroji atribut, který se použije k nastavení příznaku accountEnabled v ID Microsoft Entra. Pokud zřizujete místní Active Directory, namapujte tento zdrojový atribut na accountDisabled atribut.

Ve výchozím nastavení hodnota přidružená k atributu active schématu uživatele SCIM Core určuje stav účtu uživatele v cílovém adresáři.

Pokud je atribut nastaven na true, výchozí pravidlo mapování povolí účet. Pokud je atribut nastaven na false, výchozí pravidlo mapování účet zakáže.

Jak můžeme zabránit náhodnému zakázání nebo odstranění uživatelů?

Pokud chcete zabránit náhodnému odstranění a obnovit je, doporučujeme v aplikaci zřizování nakonfigurovat prahovou hodnotu náhodného odstranění a povolit koš místní Active Directory. V okně Mapování atributů vaší aplikace zřizování v části Akce cílového objektu zakažte operaci Odstranit.

Obnovení odstraněných účtů

• Pokud je cílovým adresářem pro operaci Microsoft Entra ID, je spárovaný uživatel obnovitelně odstraněn. Uživatel se může zobrazit na stránce Microsoft Entra admin center Odstranění uživatelé po dobu následujících 30 dnů a během této doby je možné ho obnovit.
• Pokud je cílový adresář operace místní Active Directory, je spárovaný uživatel pevně odstraněn. Pokud je povolen koš služby Active Directory, můžete odstraněný místní objekt uživatele AD obnovit.

Potřebujeme v každé žádosti odeslat všechny uživatele ze systému lidských zdrojů?

Ne, v každém požadavku nemusíte posílat všechny uživatele ze systému lidských zdrojů nebo "zdroj pravdy". Stačí poslat uživatele, které chcete vytvořit nebo aktualizovat.

Podporuje rozhraní API všechny akce HTTP (GET/POST/PUT/PATCH)?

Ne, koncový bod rozhraní API pro zřizování /bulkUpload podporuje pouze akci POST HTTP.

Pokud chci aktualizovat uživatele, musím odeslat požadavek PUT/PATCH?

Ne, koncový bod rozhraní API nepodporuje požadavek PUT/PATCH. Pokud chcete aktualizovat uživatele, odešlete data přidružená k uživateli v datové části hromadné žádosti POST.

Úloha zřizování, která zpracovává data přijatá koncovým bodem rozhraní API, automaticky zjistí, jestli musí být uživatel přijatý v datové části požadavku POST na základě nakonfigurovaných pravidel synchronizace, vytvoření, aktualizace, povolení nebo zakázání. Jako klient rozhraní API nemusíte provádět žádné další kroky, pokud chcete aktualizovat profil uživatele.

Jak se podporuje zpětný zápis?

Aktuální rozhraní API podporuje pouze příchozí data. Tady je několik možností, jak zvážit implementaci zpětného zápisu atributů, jako je e-mail, uživatelské jméno nebo telefon vygenerovaný id Microsoft Entra, které můžete vrátit zpět do systému lidských zdrojů:

• Možnost 1 – Připojení SCIM ke koncovému bodu hr nebo proxy službě, která zase aktualizuje zdroj lidských zdrojů

  • Pokud systém záznamu poskytuje koncový bod SCIM pro aktualizace uživatelů, můžete vytvořit vlastní aplikaci SCIM v galerii podnikových aplikací a nakonfigurovat zřizování podle dokumentu.
  • Pokud systém záznamu neposkytuje koncový bod SCIM, prozkoumejte možnost nastavení služby proxy SCIM, která obdrží aktualizaci a rozšíří změnu do systému personálního oddělení.

• Možnost 2 – Použití konektoru Microsoft Entra ECMA pro scénář zpětného zápisu

  • V závislosti na požadavku zákazníka se podívejte, jestli se dá použít některý z konektorů ECMA (PowerShell, SQL nebo webové služby).

• Možnost 3 – Použití vlastní úlohy rozšíření Pracovních postupů životního cyklu v pracovním postupu Joiner

  • V pracovních postupech životního cyklu definujte pracovní postup joineru a definujte vlastní úlohu rozšíření, která vyvolá proces Logic Apps, který aktualizuje systém lidských zdrojů nebo vygeneruje soubor CSV využívaný systémem personálního oddělení.

Další kroky

• Konfigurace příchozí aplikace příchozího zřizování řízeného rozhraním API
• Další informace o příchozím zřizování řízeném rozhraním API najdete v konceptech rozhraní API pro zřizování příchozích uživatelů.