Aprowizowanie przychodzące oparte na interfejsie API za pomocą skryptu programu PowerShell

Artykuł
02/28/2024

W tym samouczku opisano sposób użycia skryptu programu PowerShell do implementowania aprowizacji przychodzącej opartej na interfejsie API entra firmy Microsoft. Wykonując kroki opisane w tym samouczku, możesz przekonwertować plik CSV zawierający dane HR na ładunek żądania zbiorczego i wysłać go do punktu końcowego interfejsu API aprowizacji /bulkUpload firmy Microsoft. Artykuł zawiera również wskazówki dotyczące sposobu użycia tego samego wzorca integracji z dowolnym systemem rekordów.

Scenariusz integracji

Wymagania biznesowe

System rekordów okresowo generuje eksporty plików CSV zawierające dane procesu roboczego. Chcesz zaimplementować integrację, która odczytuje dane z pliku CSV i automatycznie aprowizuje konta użytkowników w katalogu docelowym (lokalna usługa Active Directory dla użytkowników hybrydowych i identyfikatora Entra firmy Microsoft dla użytkowników korzystających tylko z chmury).

Wymaganie implementacji

Z perspektywy implementacji:

Chcesz użyć nienadzorowanego skryptu programu PowerShell, aby odczytywać dane z eksportów plików CSV i wysyłać je do punktu końcowego interfejsu API aprowizacji dla ruchu przychodzącego.
W skryscie programu PowerShell nie chcesz implementować złożonej logiki porównywania danych tożsamości między systemem rekordu i katalogu docelowego.
Chcesz użyć usługi aprowizacji firmy Microsoft, aby zastosować reguły aprowizacji zarządzanej przez it do automatycznego tworzenia/aktualizowania/włączania/wyłączania kont w katalogu docelowym (lokalna usługa Active Directory lub Microsoft Entra ID).

Odmiany scenariusza integracji

Chociaż w tym samouczku używany jest plik CSV jako system rekordów, możesz dostosować przykładowy skrypt programu PowerShell do odczytywania danych z dowolnego systemu rekordów. Oto lista odmian scenariusza integracji dla przedsiębiorstw, w których można zaimplementować aprowizację przychodzącą oparte na interfejsie API za pomocą skryptu programu PowerShell.

#	System rekordu	Wskazówki dotyczące integracji dotyczące odczytywania danych źródłowych przy użyciu programu PowerShell
1	Tabela bazy danych	Jeśli używasz bazy danych Azure SQL Database lub lokalnego programu SQL Server, możesz użyć polecenia cmdlet Read-SqlTableData do odczytywania danych przechowywanych w tabeli bazy danych SQL. Możesz użyć polecenia cmdlet Invoke-SqlCmd , aby uruchomić skrypty języka Transact-SQL lub XQuery. Jeśli używasz bazy danych Oracle/MySQL/Postgres, możesz znaleźć moduł programu PowerShell opublikowany przez dostawcę lub dostępny w Galeria programu PowerShell. Użyj modułu , aby odczytywać dane z tabeli bazy danych.
2	Serwer LDAP	Użyj interfejsu `System.DirectoryServices.Protocols` API platformy .NET lub jednego z modułów LDAP dostępnych w Galeria programu PowerShell, aby wysłać zapytanie do serwera LDAP. Zapoznaj się ze schematem LDAP i hierarchią pobierania danych użytkownika z serwera LDAP.
3	Każdy system, który uwidacznia interfejsy API REST	Aby odczytać dane z punktu końcowego interfejsu API REST przy użyciu programu PowerShell, możesz użyć polecenia cmdlet Invoke-RestMethod z modułu `Microsoft.PowerShell.Utility` . Zapoznaj się z dokumentacją interfejsu API REST i dowiedz się, jakich parametrów i nagłówków oczekuje, jakiego formatu zwraca oraz jakiej metody uwierzytelniania używa. Następnie możesz odpowiednio dostosować polecenie `Invoke-RestMethod` .
100	Dowolny system, który uwidacznia interfejsy API protokołu SOAP	Aby odczytać dane z punktu końcowego interfejsu API protokołu SOAP przy użyciu programu PowerShell, możesz użyć polecenia cmdlet New-WebServiceProxy z modułu `Microsoft.PowerShell.Management` . Zapoznaj się z dokumentacją interfejsu API protokołu SOAP i dowiedz się, jakich parametrów i nagłówków oczekuje, jakiego formatu zwraca oraz jakiej metody uwierzytelniania używa. Następnie możesz odpowiednio dostosować polecenie `New-WebServiceProxy` .

Po odczytaniu danych źródłowych zastosuj reguły przetwarzania wstępnego i przekonwertuj dane wyjściowe z systemu rekordu na żądanie zbiorcze, które można wysłać do punktu końcowego interfejsu API zbiorczego aprowizacji firmy Microsoft.

Ważne

Jeśli chcesz udostępnić skrypt integracji programu PowerShell społeczności, opublikuj go w witrynie Galeria programu PowerShell i powiadom nas w repozytorium entra-id-inbound-provisioningGitHub, abyśmy mogli dodać odwołanie.

Jak używać tego samouczka

Przykładowy skrypt programu PowerShell opublikowany w repozytorium GitHub in provisioning dla ruchu przychodzącego firmy Microsoft automatyzuje kilka zadań. Ma logikę obsługi dużych plików CSV i fragmentowania żądania zbiorczego w celu wysyłania 50 rekordów w każdym żądaniu. Poniżej przedstawiono sposób testowania i dostosowywania go zgodnie z wymaganiami dotyczącymi integracji.

Uwaga

Przykładowy skrypt programu PowerShell jest dostarczany jako "as-is" na potrzeby dokumentacji implementacji. Jeśli masz pytania związane ze skryptem lub jeśli chcesz go ulepszyć, skorzystaj z repozytorium projektu GitHub.

#	Zadanie automatyzacji	Wskazówki dotyczące implementacji	Dostosowanie zaawansowane
1	Odczytywanie danych procesu roboczego z pliku CSV.	Pobierz skrypt programu PowerShell. Zawiera on wbudowaną logikę odczytu danych z dowolnego pliku CSV. Zapoznaj się z CSV2SCIM szczegóły użycia programu PowerShell, aby zapoznać się z różnymi trybami wykonywania tego skryptu.	Jeśli system rekordów jest inny, zapoznaj się ze wskazówkami podanymi w sekcji Scenariusz integracji odmiany sposobu dostosowywania skryptu programu PowerShell.
2	Wstępne przetwarzanie i konwertowanie danych na format SCIM.	Domyślnie skrypt programu PowerShell konwertuje każdy rekord w pliku CSV na reprezentację użytkownika podstawowego SCIM + użytkownika enterprise. Wykonaj kroki opisane w sekcji Generowanie ładunku żądania zbiorczego ze standardowym schematem , aby zapoznać się z tym procesem.	Jeśli plik CSV ma różne pola, dostosuj plik AttributeMapping.psd, aby wygenerować prawidłowego użytkownika SCIM. Możesz również wygenerować żądanie zbiorcze przy użyciu niestandardowego schematu SCIM. Zaktualizuj skrypt programu PowerShell, aby uwzględnić dowolną niestandardową logikę sprawdzania poprawności danych CSV.
3	Użyj certyfikatu do uwierzytelniania do identyfikatora Entra firmy Microsoft.	Utwórz jednostkę usługi, która może uzyskać dostęp do interfejsu API aprowizacji ruchu przychodzącego. Zapoznaj się z krokami w sekcji Konfigurowanie certyfikatu klienta na potrzeby uwierzytelniania jednostki usługi, aby dowiedzieć się, jak używać certyfikatu klienta do uwierzytelniania.	Jeśli chcesz użyć tożsamości zarządzanej zamiast jednostki usługi do uwierzytelniania, zapoznaj się z użyciem `Connect-MgGraph` przykładowego skryptu i zaktualizuj ją, aby korzystała z tożsamości zarządzanych.
100	Aprowizuj konta w identyfikatorze lokalna usługa Active Directory lub Microsoft Entra ID.	Konfigurowanie aplikacji aprowizacji przychodzącej opartej na interfejsie API. Spowoduje to wygenerowanie unikatowego punktu końcowego interfejsu API /bulkUpload . Zapoznaj się z krokami w sekcji Generowanie i przekazywanie ładunku żądania zbiorczego jako użytkownik administracyjny, aby dowiedzieć się, jak przekazywać dane do tego punktu końcowego. Zweryfikuj przepływ atrybutów i dostosuj mapowania atrybutów zgodnie z wymaganiami dotyczącymi integracji. Aby uruchomić skrypt przy użyciu jednostki usługi z uwierzytelnianiem opartym na certyfikatach, zapoznaj się z krokami w sekcji Przekazywanie ładunku żądania zbiorczego przy użyciu uwierzytelniania certyfikatu klienta	Jeśli planujesz używać żądania zbiorczego z niestandardowym schematem SCIM, rozszerz schemat aplikacji aprowizacji, aby uwzględnić niestandardowe elementy schematu SCIM.
5	Przeskanuj dzienniki aprowizacji i ponów próbę aprowizacji dla rekordów, które zakończyły się niepowodzeniem.	Zapoznaj się z krokami w sekcji Uzyskiwanie dzienników aprowizacji najnowszych cykli synchronizacji, aby dowiedzieć się, jak pobierać i analizować dane dziennika aprowizacji. Zidentyfikuj nieudane rekordy użytkowników i uwzględnij je w następnym cyklu przekazywania.	-
6	Wdróż automatyzację opartą na programie PowerShell w środowisku produkcyjnym.	Po zweryfikowaniu przepływu aprowizacji opartego na interfejsie API i dostosowaniu skryptu programu PowerShell w celu spełnienia wymagań możesz wdrożyć automatyzację jako element runbook przepływu pracy programu PowerShell w usłudze Azure Automation lub jako proces serwera zaplanowany do uruchomienia na serwerze z systemem Windows.	-

Pobieranie skryptu programu PowerShell

Uzyskaj dostęp do repozytorium entra-id-inbound-provisioningGitHub .
Użyj opcji Kod ->Klonuj lub Kod ->Pobierz plik ZIP, aby skopiować zawartość tego repozytorium do folderu lokalnego.
Przejdź do folderu PowerShell/CSV2SCIM. Ma następującą strukturę katalogów:
- Src
  - CSV2SCIM.ps1 (skrypt główny)
  - ScimSchemaRepresentations (folder zawierający standardowe definicje schematu SCIM do sprawdzania poprawności plików AttributeMapping.psd1)
    - EnterpriseUser.json, Group.json, Schema.json, User.json
- Próbki
  - AttributeMapping.psd1 (przykładowe mapowanie kolumn w pliku CSV na standardowe atrybuty SCIM)
  - csv-with-2-records.csv (przykładowy plik CSV z dwoma rekordami)
  - csv-with-1000-records.csv (przykładowy plik CSV z 1000 rekordami)
  - Test-ScriptCommands.ps1 (przykładowe polecenia użycia)
  - UseClientCertificate.ps1 (skrypt do generowania certyfikatu z podpisem własnym i przekazywania go jako poświadczenia jednostki usługi do użycia w przepływie OAuth)
  - Sample1 (folder zawierający więcej przykładów sposobu mapowania kolumn plików CSV na standardowe atrybuty SCIM. Jeśli otrzymujesz różne pliki CSV dla pracowników, wykonawców, stażystów, możesz utworzyć oddzielny plik AttributeMapping.psd1 dla każdej jednostki.
Pobierz i zainstaluj najnowszą wersję programu PowerShell.
Uruchom polecenie , aby włączyć wykonywanie skryptów podpisanych zdalnie:
```
set-executionpolicy remotesigned
```

Zainstaluj następujące moduły wymagań wstępnych:

Install-Module -Name Microsoft.Graph.Applications,Microsoft.Graph.Reports

Generowanie ładunku żądania zbiorczego przy użyciu standardowego schematu

W tej sekcji wyjaśniono, jak wygenerować ładunek żądania zbiorczego przy użyciu standardowych atrybutów użytkownika podstawowego SCIM i użytkownika przedsiębiorstwa z pliku CSV. Aby zilustrować procedurę, użyjmy pliku Samples/csv-with-2-records.csvCSV .

Otwórz plik Samples/csv-with-2-records.csv CSV w programie Notatnik++ lub Excel, aby sprawdzić kolumny obecne w pliku.

W Notatnik++ lub edytorze kodu źródłowego, takim jak Visual Studio Code, otwórz plik Samples/AttributeMapping.psd1 danych programu PowerShell, który umożliwia mapowanie kolumn plików CSV na standardowe atrybuty schematu SCIM. Plik, który jest dostarczany poza polem, ma już wstępnie skonfigurowane mapowanie kolumn plików CSV na odpowiednie atrybuty schematu SCIM.

    @{
    externalId   = 'WorkerID'
    name         = @{
        familyName = 'LastName'
        givenName  = 'FirstName'
    }
    active       = { $_.'WorkerStatus' -eq 'Active' }
    userName     = 'UserID'
    displayName  = 'FullName'
    nickName     = 'UserID'
    userType     = 'WorkerType'
    title        = 'JobTitle'
    addresses    = @(
        @{
            type          = { 'work' }
            streetAddress = 'StreetAddress'
            locality      = 'City'
            postalCode    = 'ZipCode'
            country       = 'CountryCode'
        }
    )
    phoneNumbers = @(
        @{
            type  = { 'work' }
            value = 'OfficePhone'
        }
    )
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" = @{
        employeeNumber = 'WorkerID'
        costCenter     = 'CostCenter'
        organization   = 'Company'
        division       = 'Division'
        department     = 'Department'
        manager        = @{
            value = 'ManagerID'
        }
    }
}

Otwórz program PowerShell i przejdź do katalogu CSV2SCIM\src.

Uruchom następujące polecenie, aby zainicjować zmienną AttributeMapping .

$AttributeMapping = Import-PowerShellDataFile '..\Samples\AttributeMapping.psd1'

Uruchom następujące polecenie, aby sprawdzić, czy AttributeMapping plik ma prawidłowe atrybuty schematu SCIM. To polecenie zwraca wartość True , jeśli walidacja zakończy się pomyślnie.
```
.\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping -ValidateAttributeMapping
```
Załóżmy, że AttributeMapping plik ma nieprawidłowy atrybut SCIM o nazwie userId, a następnie tryb ValidateAttributeMapping wyświetla następujący błąd.
Po sprawdzeniu, czy AttributeMapping plik jest prawidłowy, uruchom następujące polecenie, aby wygenerować żądanie zbiorcze w pliku zawierającym dwa rekordy obecne w pliku BulkRequestPayload.json CSV.
```
.\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping > BulkRequestPayload.json
```
Możesz otworzyć zawartość pliku BulkRequestPayload.json , aby sprawdzić, czy atrybuty SCIM są ustawione zgodnie z mapowaniem zdefiniowanym w pliku AttributeMapping.psd1.
Plik wygenerowany powyżej można opublikować jako punkt końcowy interfejsu API /bulkUpload skojarzony z aplikacją aprowizacji przy użyciu Eksploratora programu Graph lub narzędzia Postman lub cURL. Reference:
Aby bezpośrednio przekazać wygenerowany ładunek do punktu końcowego interfejsu API przy użyciu tego samego skryptu programu PowerShell, zapoznaj się z następną sekcją.

Generowanie i przekazywanie ładunku żądania zbiorczego jako użytkownik administracyjny

W tej sekcji wyjaśniono, jak wysłać wygenerowany ładunek żądania zbiorczego do punktu końcowego interfejsu API aprowizacji dla ruchu przychodzącego.

Zaloguj się do centrum administracyjnego firmy Microsoft Entra jako co najmniej Administracja istrator aplikacji.
Przejdź do identyfikatora obiektu Właściwości>aplikacji>aprowizacji i skopiuj ServicePrincipalId skojarzony z aplikacją aprowizacji.
Jako użytkownik z rolą Global Administracja istrator uruchom następujące polecenie, podając poprawne wartości dla ServicePrincipalId i TenantId. Zostanie wyświetlony monit o uwierzytelnienie, jeśli uwierzytelniona sesja jeszcze nie istnieje dla tej dzierżawy. Podaj zgodę na uprawnienia wyświetlane podczas uwierzytelniania.
```
.\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping -ServicePrincipalId <servicePrincipalId> -TenantId "contoso.onmicrosoft.com"
```
Odwiedź blok Dzienniki aprowizacji aplikacji aprowizacji, aby zweryfikować przetwarzanie powyższego żądania.

Konfigurowanie certyfikatu klienta na potrzeby uwierzytelniania jednostki usługi

Uwaga

W poniższych instrukcjach pokazano, jak wygenerować certyfikat z podpisem własnym. Certyfikaty z podpisem własnym nie są domyślnie zaufane i mogą być trudne do utrzymania. Ponadto mogą używać nieaktualnych zestawów skrótów i szyfrów, które mogą nie być silne. Aby uzyskać lepsze zabezpieczenia, kup certyfikat podpisany przez dobrze znany urząd certyfikacji.

Uruchom następujący skrypt programu PowerShell, aby wygenerować nowy certyfikat z podpisem własnym. Ten krok można pominąć, jeśli zakupiono certyfikat podpisany przez dobrze znany urząd certyfikacji.
```
$ClientCertificate = New-SelfSignedCertificate -Subject 'CN=CSV2SCIM' -KeyExportPolicy 'NonExportable' -CertStoreLocation Cert:\CurrentUser\My
$ThumbPrint = $ClientCertificate.ThumbPrint
```
Wygenerowany certyfikat jest przechowywany w folderze Current User\Personal\Certificates. Można go wyświetlić przy użyciu opcji Panel sterowania ->Manage user certificates (Zarządzanie certyfikatami użytkowników).
Aby skojarzyć ten certyfikat z prawidłową jednostką usługi, zaloguj się do centrum administracyjnego firmy Microsoft Entra jako Administracja istrator aplikacji.
Otwórz jednostkę usługi skonfigurowaną w obszarze Rejestracje aplikacji.
Skopiuj identyfikator obiektu z bloku Przegląd. Użyj wartości , aby zastąpić ciąg <AppObjectId>. Skopiuj identyfikator aplikacji (klienta). Użyjemy go później i zostanie on przywołyny jako <AppClientId>.

Uruchom następujące polecenie, aby przekazać certyfikat do zarejestrowanej jednostki usługi.

Connect-MgGraph -Scopes "Application.ReadWrite.All"
Update-MgApplication -ApplicationId '<AppObjectId>' -KeyCredentials @{
   Type = "AsymmetricX509Cert"
   Usage = "Verify"
   Key = $ClientCertificate.RawData
}

Certyfikat powinien zostać wyświetlony w bloku Certyfikaty i wpisy tajne zarejestrowanej aplikacji.

Dodaj następujące dwa zakresy uprawnień aplikacji do aplikacji głównej usługi: Application.Read.All i Synchronization.Read.All. Są one wymagane, aby skrypt programu PowerShell wyszukał aplikację ServicePrincipalId aprowizacji, pobierając aprowizację JobId.

Przekazywanie ładunku żądania zbiorczego przy użyciu uwierzytelniania certyfikatu klienta

W tej sekcji wyjaśniono, jak wysłać wygenerowany ładunek żądania zbiorczego do punktu końcowego interfejsu API aprowizacji dla ruchu przychodzącego przy użyciu zaufanego certyfikatu klienta.

Otwórz skonfigurowaną aplikację aprowizacji opartą na interfejsie API. ServicePrincipalId Skopiuj skojarzony z aplikacją aprowizacji identyfikator obiektu Właściwości>aplikacji>aprowizacji.

Uruchom następujące polecenie, podając poprawne wartości dla ServicePrincipalIdparametrów i ClientIdTenantId.

$ClientCertificate = Get-ChildItem -Path cert:\CurrentUser\my\ | Where-Object {$_.Subject -eq "CN=CSV2SCIM"}  
$ThumbPrint = $ClientCertificate.ThumbPrint

.\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping -TenantId "contoso.onmicrosoft.com" -ServicePrincipalId "<ProvisioningAppObjectId>" -ClientId "<AppClientId>" -ClientCertificate (Get-ChildItem Cert:\CurrentUser\My\$ThumbPrint)

Odwiedź blok Dzienniki aprowizacji aplikacji aprowizacji, aby zweryfikować przetwarzanie powyższego żądania.

Generowanie żądania zbiorczego przy użyciu niestandardowego schematu SCIM

W tej sekcji opisano sposób generowania żądania zbiorczego za pomocą niestandardowej przestrzeni nazw schematu SCIM składającej się z pól w pliku CSV.

W Notatnik++ lub edytorze kodu źródłowego, takim jak Visual Studio Code, otwórz plik Samples/AttributeMapping.psd1 danych programu PowerShell, który umożliwia mapowanie kolumn plików CSV na standardowe atrybuty schematu SCIM. Plik, który jest dostarczany poza polem, ma już wstępnie skonfigurowane mapowanie kolumn plików CSV na odpowiednie atrybuty schematu SCIM.
Otwórz program PowerShell i przejdź do katalogu CSV2SCIM\src.

Uruchom następujące polecenie, aby zainicjować zmienną AttributeMapping .

$AttributeMapping = Import-PowerShellDataFile '..\Samples\AttributeMapping.psd1'

Uruchom następujące polecenie, aby sprawdzić, czy AttributeMapping plik ma prawidłowe atrybuty schematu SCIM. To polecenie zwraca wartość True , jeśli walidacja zakończy się pomyślnie.
```
.\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping -ValidateAttributeMapping
```
Oprócz atrybutów użytkownika podstawowego SCIM i użytkownika przedsiębiorstwa, aby uzyskać płaską listę wszystkich pól CSV w niestandardowej przestrzeni urn:ietf:params:scim:schemas:extension:contoso:1.0:Usernazw schematu SCIM, uruchom następujące polecenie.
```
 .\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping -ScimSchemaNamespace "urn:ietf:params:scim:schemas:extension:contoso:1.0:User"  > BulkRequestPayloadWithCustomNamespace.json
```
Pola CSV będą wyświetlane w niestandardowej przestrzeni nazw schematu SCIM.

Rozszerzanie schematu zadania aprowizacji

Często plik danych wysyłany przez zespoły HR zawiera więcej atrybutów, które nie mają bezpośredniej reprezentacji w standardowym schemacie SCIM. Aby reprezentować takie atrybuty, zalecamy utworzenie schematu rozszerzenia SCIM i dodanie atrybutów w tej przestrzeni nazw.

Skrypt CSV2SCIM zapewnia tryb wykonywania o nazwie UpdateSchema , który odczytuje wszystkie kolumny w pliku CSV, dodaje je w przestrzeni nazw schematu rozszerzenia i aktualizuje schemat aplikacji aprowizacji.

Uwaga

Jeśli rozszerzenia atrybutów są już obecne w schemacie aplikacji aprowizacji, ten tryb emituje tylko ostrzeżenie, że rozszerzenie atrybutu już istnieje. Dlatego nie ma problemu z uruchomieniem skryptu CSV2SCIM w trybie UpdateSchema , jeśli nowe pola zostaną dodane do pliku CSV i chcesz dodać je jako rozszerzenie.

Aby zilustrować procedurę, użyjemy pliku Samples/csv-with-2-records.csv CSV dostępnego w folderze CSV2SCIM .

Otwórz plik Samples/csv-with-2-records.csv CSV w Notatnik, Excel lub TextPad, aby sprawdzić kolumny obecne w pliku.

Uruchom następujące polecenie:

.\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -UpdateSchema -ServicePrincipalId <servicePrincipalId> -TenantId "contoso.onmicrosoft.com" -ScimSchemaNamespace "urn:ietf:params:scim:schemas:extension:contoso:1.0:User"

Możesz zweryfikować aktualizację schematu aplikacji aprowizacji, otwierając stronę Mapowanie atrybutów i korzystając z opcji Edytuj atrybuty dla interfejsu API w obszarze Opcje zaawansowane.
Lista atrybutów zawiera atrybuty w nowej przestrzeni nazw.

Pobieranie dzienników aprowizacji najnowszych cykli synchronizacji

Po wysłaniu żądania zbiorczego można wykonać zapytanie dotyczące dzienników najnowszych cykli synchronizacji przetworzonych przez identyfikator firmy Microsoft Entra. Możesz pobrać statystyki synchronizacji i szczegóły przetwarzania za pomocą skryptu programu PowerShell i zapisać je do analizy.

Aby wyświetlić szczegóły dziennika i statystyki synchronizacji w konsoli programu , uruchom następujące polecenie:
```
.\CSV2SCIM.ps1 -ServicePrincipalId <servicePrincipalId> -TenantId "contoso.onmicrosoft.com" -GetPreviousCycleLogs -NumberOfCycles 1
```
Uwaga

Parametr NumberOfCycles jest domyślnie 1. Określ liczbę, aby pobrać więcej cykli synchronizacji.
Aby wyświetlić statystyki synchronizacji w konsoli programu i zapisać szczegóły dzienników w zmiennej, uruchom następujące polecenie:
```
$logs=.\CSV2SCIM.ps1 -ServicePrincipalId <servicePrincipalId> -TenantId "contoso.onmicrosoft.com" -GetPreviousCycleLogs
```
Aby uruchomić polecenie przy użyciu uwierzytelniania certyfikatu klienta, uruchom polecenie, podając poprawne wartości dla ServicePrincipalIdparametrów i TenantIdClientId :
```
$ClientCertificate = Get-ChildItem -Path cert:\CurrentUser\my\ | Where-Object {$_.Subject -eq "CN=CSV2SCIM"}  
$ThumbPrint = $ClientCertificate.ThumbPrint

$logs=.\CSV2SCIM.ps1 -ServicePrincipalId "<ProvisioningAppObjectId>" -TenantId "contoso.onmicrosoft.com" -ClientId "<AppClientId>" -ClientCertificate (Get-ChildItem Cert:\CurrentUser\My\$ThumbPrint) -GetPreviousCycleLogs -NumberOfCycles 1
```
- Aby wyświetlić szczegóły określonego rekordu, możemy umieścić w pętli w kolekcji lub wybrać określony indeks, na przykład: $logs[0]
- Możemy również użyć instrukcji where-object , aby wyszukać określony rekord przy użyciu identyfikatora sourceID lub DisplayName. We właściwości ProvisioningLogs można znaleźć wszystkie szczegóły operacji wykonanej dla tego konkretnego rekordu.
```
$user = $logs | where sourceId -eq '1222'
$user.ProvisioningLogs | fl
```
- W atrybucie ModifiedProperties można zobaczyć określonego użytkownika, którego dotyczy problem. $user.ProvisioningLogs.ModifiedProperties

Dodatek

CSV2SCIM szczegóły użycia programu PowerShell

Oto lista parametrów wiersza polecenia akceptowanych przez skrypt programu CSV2SCIM PowerShell.

PS > CSV2SCIM.ps1 -Path <path-to-csv-file> 
[-ScimSchemaNamespace <customSCIMSchemaNamespace>] 
[-AttributeMapping $AttributeMapping] 
[-ServicePrincipalId <spn-guid>] 
[-ValidateAttributeMapping]
[-UpdateSchema]
[-ClientId <client-id>]
[-ClientCertificate <certificate-object>]
[-RestartService]

Uwaga

Parametry AttributeMapping wiersza polecenia i ValidateAttributeMapping odwołują się do mapowania atrybutów kolumny CSV na standardowe elementy schematu SCIM. Nie odnosi się do mapowań atrybutów, które są wykonywane w aplikacji aprowizacji centrum administracyjnego firmy Microsoft Entra między źródłowymi elementami schematu SCIM i docelowymi atrybutami Microsoft Entra/lokalna usługa Active Directory.

Parametr	Opis	Przetwarzanie uwag
Ścieżka	Pełna lub względna ścieżka do pliku CSV. Na przykład: `.\Samples\csv-with-1000-records.csv`.	Obowiązkowe: Tak
ScimSchemaNamespace	Niestandardowa przestrzeń nazw schematu SCIM używana do wysyłania wszystkich kolumn w pliku CSV jako niestandardowych atrybutów SCIM należących do określonej przestrzeni nazw. Na przykład `urn:ietf:params:scim:schemas:extension:csv:1.0:User`	Obowiązkowe: tylko wtedy, gdy chcesz: - Zaktualizuj schemat aplikacji aprowizacji lub Jeśli chcesz uwzględnić niestandardowe atrybuty SCIM w ładunku.
Mapowanie atrybutów	Wskazuje plik danych programu PowerShell (rozszerzenie psd1), który mapuje kolumny w pliku CSV na atrybuty użytkownika podstawowego SCIM i użytkownika przedsiębiorstwa. Zobacz przykład: AttributeMapping.psd plik dla skryptu CSV2SCIM. Na przykład: powershell $AttributeMapping = Import-PowerShellDataFile '.\Samples\AttributeMapping.psd1'`-AttributeMapping $AttributeMapping	Obowiązkowe: Tak Jedynym scenariuszem, w którym nie trzeba określać tego w przypadku korzystania z przełącznika `UpdateSchema` .
ValidateAttributeMapping	Użyj tej flagi przełącznika, aby sprawdzić, czy plik AttributeMapping zawiera atrybuty zgodne ze schematem użytkownika SCIM Core i Enterprise.	Obowiązkowe: Nie zaleca się używania go w celu zapewnienia zgodności.
ServicePrincipalId	Wartość identyfikatora GUID jednostki usługi aprowizacji aplikacji, którą można pobrać z identyfikatora obiektu właściwości>aplikacji>aprowizacji	Obowiązkowe: tylko wtedy, gdy chcesz: — zaktualizuj schemat aplikacji aprowizacji lub wyślij wygenerowane żądanie zbiorcze do punktu końcowego interfejsu API.
UpdateSchema	Użyj tego przełącznika, aby poinstruować skrypt o odczytaniu kolumn CSV i dodaniu ich jako niestandardowych atrybutów SCIM w schemacie aplikacji aprowizacji.
ClientId	Identyfikator klienta zarejestrowanej aplikacji Firmy Microsoft do użycia na potrzeby przepływu uwierzytelniania OAuth. Ta aplikacja musi mieć prawidłowe poświadczenia certyfikatu.	Obowiązkowe: tylko podczas przeprowadzania uwierzytelniania opartego na certyfikatach.
Clientcertificate	Certyfikat uwierzytelniania klienta do użycia podczas przepływu OAuth.	Obowiązkowe: tylko podczas przeprowadzania uwierzytelniania opartego na certyfikatach.
GetPreviousCycleLogs	Aby uzyskać dzienniki aprowizacji najnowszych cykli synchronizacji.
NumberOfCycles	Aby określić liczbę cykli synchronizacji, które mają zostać pobrane. Ta wartość jest domyślnie 1.
RestartService	Dzięki tej opcji skrypt tymczasowo wstrzymuje zadanie aprowizacji przed przekazaniem danych, przekazuje dane, a następnie ponownie uruchamia zadanie, aby zapewnić natychmiastowe przetwarzanie ładunku.	Użyj tej opcji tylko podczas testowania.

plik AttributeMapping.psd

Ten plik służy do mapowania kolumn w pliku CSV na standardowe elementy schematu atrybutów SCIM Core User i Enterprise User. Plik generuje również odpowiednią reprezentację zawartości pliku CSV jako ładunku żądania zbiorczego.

W następnym przykładzie zamapowaliśmy następujące kolumny w pliku CSV na ich odpowiedniki atrybutów SCIM Core User i Enterprise User.

    @{
    externalId   = 'WorkerID'
    name         = @{
        familyName = 'LastName'
        givenName  = 'FirstName'
    }
    active       = { $_.'WorkerStatus' -eq 'Active' }
    userName     = 'UserID'
    displayName  = 'FullName'
    nickName     = 'UserID'
    userType     = 'WorkerType'
    title        = 'JobTitle'
    addresses    = @(
        @{
            type          = { 'work' }
            streetAddress = 'StreetAddress'
            locality      = 'City'
            postalCode    = 'ZipCode'
            country       = 'CountryCode'
        }
    )
    phoneNumbers = @(
        @{
            type  = { 'work' }
            value = 'OfficePhone'
        }
    )
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" = @{
        employeeNumber = 'WorkerID'
        costCenter     = 'CostCenter'
        organization   = 'Company'
        division       = 'Division'
        department     = 'Department'
        manager        = @{
            value = 'ManagerID'
        }
    }
}

Udostępnij za pośrednictwem

Aprowizowanie przychodzące oparte na interfejsie API za pomocą skryptu programu PowerShell

Scenariusz integracji

Wymagania biznesowe

Wymaganie implementacji

Odmiany scenariusza integracji

Jak używać tego samouczka

Pobieranie skryptu programu PowerShell

Generowanie ładunku żądania zbiorczego przy użyciu standardowego schematu

Generowanie i przekazywanie ładunku żądania zbiorczego jako użytkownik administracyjny

Konfigurowanie certyfikatu klienta na potrzeby uwierzytelniania jednostki usługi

Przekazywanie ładunku żądania zbiorczego przy użyciu uwierzytelniania certyfikatu klienta

Generowanie żądania zbiorczego przy użyciu niestandardowego schematu SCIM

Rozszerzanie schematu zadania aprowizacji

Pobieranie dzienników aprowizacji najnowszych cykli synchronizacji

Dodatek

CSV2SCIM szczegóły użycia programu PowerShell

plik AttributeMapping.psd

Następne kroki

Opinia

Opinia

Dodatkowe zasoby