API temelli gelen sağlama hakkında sık sorulan sorular

  • Makale

Bu makalede API temelli gelen sağlama hakkında sık sorulan sorular (SSS) yanıtlar.

Yeni gelen sağlama /bulkUpload API'sinin MS Graph Kullanıcıları API'sinden farkı nedir?

Sağlama /bulkUpload API'si ile MS Graph Kullanıcıları API'sinin uç noktası arasında önemli farklar vardır.

  • Yük biçimi: MS Graph Kullanıcıları API'sinin uç noktası verileri OData biçiminde bekler. Yeni gelen sağlama /bulkUpload API'si için istek yükü biçimi SCIM şema yapılarını kullanır. Bu API'yi çağırırken , 'Content-Type' üst bilgisini olarak application/scim+jsonayarlayın.
  • İşlem bitiş sonucu:
    • Kimlik verileri MS Graph Kullanıcıları API uç noktasına gönderildiğinde, hemen işlenir ve Microsoft Entra kullanıcı profilinde bir Oluşturma/Güncelleştirme/Silme işlemi gerçekleşir.
    • Sağlama /bulkUpload API'sine gönderilen istek verileri Microsoft Entra sağlama hizmeti tarafından zaman uyumsuz olarak işlenir. Sağlama işi, BT yöneticisi tarafından yapılandırılan kapsam kuralları, öznitelik eşlemesi ve dönüştürme uygular. Bu, Microsoft Entra kullanıcı profilinde veya şirket içi AD kullanıcı profilinde bir Create/Update/Delete işlem başlatır.
  • BT yöneticisi denetimi korur: API temelli gelen sağlama ile BT yöneticisi, gelen kimlik verilerinin nasıl işlendiği ve Microsoft Entra öznitelikleriyle nasıl eşlendiği konusunda daha fazla denetime sahiptir. Kullanıcı profilinde öznitelik değerlerini ayarlamadan önce belirli kimlik verisi türlerini (örneğin, yüklenici verileri) dışlamak için kapsam belirleme kuralları tanımlayabilir ve yeni değerler türetmek için dönüştürme işlevlerini kullanabilirler.

Gelen sağlama /bulkUpload API'si standart bir SCIM uç noktası mı?

MS Graph gelen sağlama /bulkUpload API'sinde istek yükünde SCIM şeması kullanılır, ancak standartlaştırılmış bir SCIM API uç noktası değildir . İşte nedeni.

Genellikle, SCIM hizmet uç noktası SCIM yükü ile HTTP isteklerini (POST, PUT, GET) işler ve bunları kimlik deposundaki ilgili işlemlerine (Oluşturma, Güncelleştirme, Arama) çevirir. SCIM hizmet uç noktası, SCIM API istemcisine işlem semantiğini belirtme, kimlik oluşturma/güncelleştirme/silme işlemleri gibi özellikleri yerleştirir. Bu mekanizma, API istemcisinin kimlik deposundaki kullanıcılar için hangi işlemi gerçekleştirmek istediğinin farkında olduğu senaryolar için iyi çalışır.

MS Graph gelen sağlama /bulkUpload, üç benzersiz gereksinime göre şekillendirilen farklı bir kurumsal kimlik tümleştirme senaryosını işleyecek şekilde tasarlanmıştır:

  1. Kayıtları toplu olarak zaman uyumsuz olarak işleyebilme (örneğin, 50K+ kayıtları işleme)
  2. Yüke herhangi bir kimlik özniteliği ekleme olanağı (örneğin, costCenter, ödeme notu, badgeId)
  3. İşlem semantiğinin farkında olmayan API istemcilerini destekleyin. Bu istemciler yalnızca ham kaynak verilere (örneğin, CSV dosyasındaki kayıtlar, SQL tablosu veya İk kayıtları) erişimi olan SCIM API olmayan istemcilerdir. Bu istemcilerin her kaydı okuyup kimlik deposundaki işlem semantiğini Create/Update/Delete belirleme özelliği yoktur.

MS Graph gelen sağlama /bulkUpload API'sinin birincil hedefi, müşterilerin Microsoft Entra sağlama hizmeti tarafından son işleme için herhangi bir kimlik veri kaynağından (örneğin, maliyet Merkezi, ödeme notu, badgeId) herhangi bir kimlik verisi (örneğin CSV/SQL/HR) göndermesini sağlamaktır. Microsoft Entra sağlama hizmeti bu uç noktada alınan toplu yük verilerini kullanır, BT yöneticisi tarafından yapılandırılan öznitelik eşleme kurallarını uygular ve veri yükünün hedef kimlik deposunda (Microsoft Entra Id / şirket içi AD) (Oluştur, Güncelleştir, Etkinleştir, Devre Dışı Bırak) işlemine yol açıp açmadığını belirler.

Sağlama /bulkUpload API'şirket içi Active Directory etki alanlarını hedef olarak destekliyor mu?

Evet, sağlama API'si hedef olarak şirket içi AD etki alanlarını destekler.

Sağlama uygulamamız için /bulkUpload API uç noktasını nasıl alacağız?

/bulkUpload API'si yalnızca şu tür uygulamalar için kullanılabilir: "Microsoft Entra Id'ye API temelli gelen sağlama" ve "şirket içi Active Directory'a API tabanlı gelen sağlama". Sağlama dikey penceresi giriş sayfasından her sağlama uygulaması için benzersiz API uç noktasını alabilirsiniz. İstatistiklerden bugüne kadarki>teknik bilgileri görüntüle bölümünde Sağlama API'si Uç Noktası URL'sini kopyalayın.

Şu biçime sahiptir:

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

Sağlama /bulkUpload API'sini kullanarak tam eşitlemeyi nasıl gerçekleştirebiliriz?

Tam eşitleme gerçekleştirmek için API istemcinizi kullanarak tüm kullanıcıların verilerini güvenilir kaynağınızdan API uç noktasına toplu istek olarak gönderin. Tüm verileri API uç noktasına gönderdikten sonra, sonraki eşitleme döngüsü tüm kullanıcı kayıtlarını işler ve sağlama günlükleri API uç noktasını kullanarak ilerleme durumunu izlemenize olanak tanır.

Sağlama /bulkUpload API'sini kullanarak delta eşitlemeyi nasıl gerçekleştiririz?

Delta eşitlemesi gerçekleştirmek için API istemcinizi kullanarak yalnızca verileri güvenilen kaynakta değiştirilen kullanıcılar hakkında bilgi gönderin. Tüm verileri API uç noktasına gönderdikten sonra, sonraki eşitleme döngüsü tüm kullanıcı kayıtlarını işler ve sağlama günlükleri API uç noktasını kullanarak ilerleme durumunu izlemenize olanak tanır.

Yeniden başlatma sağlama nasıl çalışır?

Sağlamayı yeniden başlat seçeneğini yalnızca gerekirse kullanın. İşleyişi şu şekildedir:

Senaryo 1: Sağlamayı yeniden başlat düğmesine tıkladığınızda ve iş şu anda çalışıyorsa, iş önceden hazırlanmış olan mevcut verileri işlemeye devam eder. Yeniden başlatma sağlama işlemi mevcut bir döngüyü kesintiye uğratmaz. Sonraki döngüde, sağlama hizmeti tüm emanetleri temizler ve işlenmek üzere yeni toplu isteği seçer.

Senaryo 2: Sağlamayıyeniden başlat düğmesine tıkladığınızda ve iş çalışmıyorsa, sonraki döngüyü çalıştırmadan önce sağlama altyapısı yeniden başlatmadan önce karşıya yüklenen verileri temizler, tüm emanetleri temizler ve yalnızca yeni gelen verileri işler.

Sağlama /bulkUpload API uç noktasını kullanarak kullanıcıları nasıl oluşturabiliriz?

/bulkUpload API uç noktasıyla ilişkili sağlama işi gelen kullanıcı yüklerini şu şekilde işler:

  1. İş, sağlama işi için öznitelik eşlemesini alır ve eşleşen öznitelik çiftini not eder (varsayılan olarak externalId API özniteliği Microsoft Entra Id ile eşleşmek employeeId için kullanılır).
  2. Bu varsayılan öznitelik eşleştirme çifti değiştirebilirsiniz.
  3. İş, toplu istek yükünde mevcut olan her işlemi ayıklar.
  4. İş, istekteki değer eşleştirme tanımlayıcısını (varsayılan olarak özniteliği externalId) denetler ve Microsoft Entra Id'de eşleşen employeeId değere sahip bir kullanıcı olup olmadığını denetlemek için bunu kullanır.
  5. İş eşleşen bir kullanıcı bulamazsa, iş eşitleme kurallarını uygular ve hedef dizinde yeni bir kullanıcı oluşturur.

Microsoft Entra Id'de doğru kullanıcıların oluşturulduğundan emin olmak için, eşlemenizde kaynağınızdaki ve Microsoft Entra Id'nizdeki kullanıcıları benzersiz olarak tanımlayan doğru eşleşen öznitelik çiftini tanımlayın.

UPN için benzersiz değerleri nasıl oluştururuz?

Sağlama hizmeti yinelenen userPrincipalName (UPN) olup olmadığını denetleme ve çakışmaları işleme olanağı sağlamaz. UPN özniteliği için varsayılan eşitleme kuralı mevcut bir UPN değeri oluşturuyorsa, kullanıcı oluşturma işlemi başarısız olur.

Benzersiz UPN'ler oluşturmak için göz önünde bulundurabileceğiniz bazı seçenekler şunlardır:

  1. API istemcinize benzersiz UPN oluşturma mantığını ekleyin.
  2. RANDOMString işlevini kullanmak için UPN özniteliği için eşitleme kuralını güncelleştirin ve eşleme parametresini uygula olarak On object creation onlyayarlayın. Örnek:

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

  1. şirket içi Active Directory'a sağlamayı kullanıyorsanız SelectUniqueValue işlevini kullanabilir ve eşlemeyi uygula parametresini olarak On object creation onlyayarlayabilirsiniz.

Sağlama /bulkUpload API uç noktasına nasıl daha fazla İk özniteliği gönderebiliriz?

Varsayılan olarak, API uç noktası SCIM Çekirdek Kullanıcı ve Kurumsal Kullanıcı şemasının parçası olan tüm özniteliklerin işlenmesini destekler. Daha fazla öznitelik göndermek isterseniz sağlama uygulaması şemasını genişletebilir, yeni öznitelikleri Microsoft Entra öznitelikleriyle eşleyebilir ve toplu isteği güncelleştirerek bu öznitelikleri gönderebilirsiniz. Özel öznitelikleri eşitlemek için API temelli sağlamayı genişletme öğreticisine bakın.

Belirli kullanıcıları sağlama akışından nasıl dışlarız?

Tüm kullanıcıları API uç noktasına göndermek, ancak yalnızca belirli kullanıcıları sağlama akışına dahil etmek ve kalanları hariç tutmak istediğiniz bir senaryonuz olabilir.

Bunu, Kapsam belirleme filtresini kullanarak gerçekleştirebilirsiniz. Sağlama uygulaması yapılandırmasında, bir kaynak nesne kapsamı tanımlayabilir ve belirli kullanıcıları "ekleme kuralı" (örneğin, yalnızca departman EQUALS Satışları olan kullanıcıları işleme) veya bir "dışlama kuralı" (örneğin, Sales'e ait kullanıcıları hariç tutma, EŞIT DEĞİl Satışlar bölümü) kullanarak işlemeden hariç tutabilirsiniz.

Bkz . Kapsam filtreleri ile sağlanacak kullanıcıların veya grupların kapsamını belirleme.

Sağlama /bulkUpload API uç noktasını kullanarak kullanıcıları nasıl güncelleştirebiliriz?

/bulkUpload API uç noktasıyla ilişkili sağlama işi gelen kullanıcı yüklerini şu şekilde işler:

  1. Sağlama işi, sağlama işi için öznitelik eşlemesini alır ve eşleşen öznitelik çiftini not alır (varsayılan olarak externalId , Microsoft Entra Id'de ile employeeId eşleştirmek için API özniteliği kullanılır). Bu varsayılan öznitelik eşleştirme çifti değiştirebilirsiniz.
  2. İş, toplu istek yükünden işlemleri ayıklar.
  3. İş, SCIM isteğindeki değer eşleştirme tanımlayıcısını (varsayılan olarak: API özniteliği externalId) denetler ve Microsoft Entra Id'de eşleşen employeeId değere sahip bir kullanıcı olup olmadığını denetlemek için bunu kullanır.
  4. İş eşleşen bir kullanıcı bulursa, eşitleme kurallarını uygular ve kaynak ve hedef profilleri karşılaştırır.
  5. İş bazı değerlerin değiştiğini belirlerse dizindeki ilgili kullanıcı kaydını güncelleştirir.

Microsoft Entra Id'de doğru kullanıcıların güncelleştirildiğinden emin olmak için, eşlemenizde kaynağınızdaki ve Microsoft Entra Id'nizdeki kullanıcıları benzersiz olarak tanımlayan doğru eşleşen öznitelik çiftini tanımladığınızdan emin olun.

API temelli gelen sağlamayı destekleyen birden fazla uygulama oluşturabilir miyiz?

Evet, sürdürebilirsiniz. Birden fazla sağlama uygulaması gerektirebilecek bazı senaryolar şunlardır:

Senaryo 1: Üç güvenilir veri kaynağınız olduğunu varsayalım: biri çalışanlar, biri yükleniciler ve biri satıcılar için. Kendi benzersiz öznitelik eşlemesine sahip her kimlik türü için bir tane olan üç ayrı sağlama uygulaması oluşturabilirsiniz. Her sağlama uygulamasının benzersiz bir API uç noktası vardır ve ilgili yükleri her uç noktaya gönderebilirsiniz.

Her iş için benzersiz API uç noktasını Sağlama dikey penceresi giriş sayfasından alabilirsiniz. Bugüne>kadarki İstatistikler Teknik bilgileri görüntüle'ye gidin, ardından Sağlama API'si Uç Noktası URL'sini kopyalayın.

Senaryo 2: Her biri kendi öznitelik kümesine sahip olan birden fazla gerçek kaynağınız olduğunu varsayalım. Örneğin İk, iş bilgisi öznitelikleri (örneğin jobTitle, employeeType) sağlar ve Badging Sistemi rozet bilgisi öznitelikleri sağlar (örneğin badgeId , bir uzantı özniteliği kullanılarak temsil edilir). Bu senaryoda, iki sağlama uygulaması yapılandırabilirsiniz:

  • İk kaynağınızdan öznitelikleri alan ve kullanıcıyı oluşturan Sağlama Uygulaması #1 .

  • Badging sisteminden öznitelikleri alan ve yalnızca kullanıcı özniteliklerini güncelleştiren Sağlama Uygulaması #2 . Bu uygulamadaki öznitelik eşlemesi Rozet Bilgileri öznitelikleriyle sınırlıdır ve Yalnızca Hedef Nesne Eylemleri güncelleştirmesinin altında etkinleştirilir.

  • Her iki uygulama da aynı eşleşen tanımlayıcı çiftini (externalId<->employeeId) kullanır

/bulkUpload API uç noktasını kullanarak sonlandırmaları nasıl işleriz?

Sonlandırmaları işlemek için kaynağınızda Microsoft Entra Id bayrağını accountEnabled ayarlamak için kullanılacak bir özniteliği tanımlayın. şirket içi Active Directory'a sağlamayı kullanıyorsanız, bu kaynak özniteliği özniteliğiyle eşleyinaccountDisabled.

Varsayılan olarak, SCIM Core User şema özniteliğiyle active ilişkili değer, hedef dizindeki kullanıcı hesabının durumunu belirler.

Öznitelik true olarak ayarlanırsa, varsayılan eşleme kuralı hesabı etkinleştirir. Öznitelik false olarak ayarlanırsa, varsayılan eşleme kuralı hesabı devre dışı bırakır.

Kullanıcıların yanlışlıkla devre dışı bırakılmasını/silinmesini nasıl önleyebiliriz?

Yanlışlıkla silmeleri önlemek ve kurtarmak için sağlama uygulamasında yanlışlıkla silme eşiğini yapılandırmanızı ve şirket içi Active Directory geri dönüşüm kutusunu etkinleştirmenizi öneririz. Sağlama uygulamanızın Öznitelik Eşleme dikey penceresinde, Hedef nesne eylemleri'nin altında Delete işlemini devre dışı bırakın.

Silinen hesapları kurtarma

  • İşlemin hedef dizini Microsoft Entra Id ise, eşleşen kullanıcı geçici olarak silinir. Kullanıcı, Microsoft Entra yönetim merkezi Silinmiş kullanıcılar sayfasında önümüzdeki 30 gün boyunca görülebilir ve bu süre boyunca geri yüklenebilir.
  • İşlemin hedef dizini şirket içi Active Directory ise, eşleşen kullanıcı sabit olarak silinir. Active Directory Geri Dönüşüm Kutusu etkinse, silinen şirket içi AD kullanıcı nesnesini geri yükleyebilirsiniz.

her istekte İk sistemindeki tüm kullanıcıları göndermemiz gerekiyor mu?

Hayır, tüm kullanıcıları her istekte İk sisteminden / "doğruluk kaynağından" göndermeniz gerekmez. Oluşturmak veya güncelleştirmek istediğiniz kullanıcıları göndermeniz yeter.

API tüm HTTP eylemlerini (GET/POST/PUT/PATCH) destekliyor mu?

Hayır, /bulkUpload sağlama API'sinin uç noktası yalnızca POST HTTP eylemini destekler.

Bir kullanıcıyı güncelleştirmek istersem PUT/PATCH isteği göndermem gerekir mi?

Hayır, API uç noktası PUT/PATCH isteğini desteklemez. Kullanıcıyı güncelleştirmek için post toplu istek yükünde kullanıcıyla ilişkili verileri gönderin.

API uç noktası tarafından alınan verileri işleyen sağlama işi, POST isteği yükünde alınan kullanıcının yapılandırılmış eşitleme kurallarına göre oluşturulması/güncelleştirilmesi/etkinleştirilmesi/devre dışı bırakılması gerekip gerekmediğini otomatik olarak algılar. API istemcisi olarak, bir kullanıcı profilinin güncelleştirilmesini istiyorsanız daha fazla adım uygulamanız gerekmez.

Geri yazma nasıl desteklenir?

Geçerli API yalnızca gelen verileri destekler. aşağıda, microsoft Entra ID tarafından oluşturulan ve İk sistemine geri dönebileceğiniz e-posta / kullanıcı adı / telefon gibi özniteliklerin geri yazılması için dikkate alınacak bazı seçenekler vardır:

  • Seçenek 1 – İk uç noktasına/ara sunucu hizmetine SCIM bağlantısı ve bu da İk kaynağını güncelleştirir

    • Kayıt sistemi kullanıcı güncelleştirmeleri için bir SCIM uç noktası sağlıyorsa, kurumsal uygulama galerisinde özel bir SCIM uygulaması oluşturabilir ve sağlamayı belgelendiği gibi yapılandırabilirsiniz.
    • Kayıt sistemi bir SCIM uç noktası sağlamıyorsa, güncelleştirmeyi alan ve değişikliği İk sistemine yayan bir proxy SCIM hizmeti ayarlama olasılığını keşfedin.

  • 2. Seçenek – Geri yazma senaryosu için Microsoft Entra ECMA bağlayıcısını kullanma

    • Müşteri gereksinimine bağlı olarak ECMA bağlayıcılarından birinin kullanılıp kullanılamayabileceğini keşfedin (PowerShell / SQL / Web Hizmetleri).

  • 3. Seçenek – Joiner iş akışında Yaşam Döngüsü İş Akışları özel uzantı görevini kullanma

Sonraki adımlar