Freigeben über

Massenaktualisierung von Benutzerprofileigenschaften für SharePoint Online

  • Artikel

Im Rahmen der Client Side Object Model (CSOM)-Version (4622.1208 oder neuer) bietet SharePoint die Funktion für den Massenimport benutzerdefinierter Benutzerprofileigenschaften. Vor dieser Version bestand Ihre einzige Option darin, die CSOM-Vorgänge für Benutzerprofile zum Aktualisieren bestimmter Eigenschaften für einzelne Benutzerprofile zu nutzen. Dieser Ansatz ist jedoch ineffizient und zu zeitaufwändig (insbesondere bei Tausenden von Profilen).

Viele Unternehmen müssen benutzerdefinierte Attribute in den SharePoint Online-Benutzerprofildienst replizieren, weshalb eine leistungsfähigere Massen-API für Benutzerprofile freigegeben wurde, die UserProfile.BatchUpdate.API.

Übersicht des Prozesses Massenaktualisierung von Benutzerprofilen

Flow für Massenaktualisierung von Benutzerprofilattributen (UPA)

In der folgenden Liste wird der Ablauf des Massenaktualisierungsprozesses von Benutzerprofilen beschrieben:

  1. Benutzerattribute werden aus dem Active Directory des Unternehmens in Azure Active Directory (Azure AD) synchronisiert. Sie können auswählen, welche Attribute zwischen lokalem Active Directory und Azure repliziert werden.
  2. Ein standardisierter Satz von Attributen wird aus Azure AD in den SharePoint Online-Benutzerprofilspeicher innerhalb von Office 365 repliziert. Im Gegensatz zum lokalen SharePoint lassen sich diese Attribute nicht anpassen.
  3. Ein benutzerdefiniertes Synchronisierungstool nutzt die Massenaktualisierungs-APIs. Dieses Tool lädt eine JSON-Datei in den Office 365-Mandanten hoch und reiht den Importvorgang in die Warteschlange ein. Dieses Tool kann mithilfe von verwaltetem Code (.NET) oder als PowerShell-Skript mithilfe der CSOM-APIs implementiert werden.
  4. Ein Branchensystem (LOB) oder ein beliebiges externes System ist die Quelle der Informationen in der JSON-Datei. Dies könnte auch eine Kombination aus Daten aus Active Directory und einem beliebigen externen System sein. Beachten Sie, dass das Branchensystem aus Sicht der API sogar eine lokale SharePoint-Farm sein könnte.
  5. Ein vorgefertigter, serverseitiger Zeitgeberauftrag, der in SharePoint Online ausgeführt wird, prüft auf Warteschlangenimportanforderungen und führt den tatsächlichen Importvorgang auf Grundlage der API-Aufrufe und Informationen in der bereitgestellten JSON-Datei durch.
  6. Erweiterte Benutzerprofilinformationen sind in Benutzerprofilen verfügbar und können für alle vorgefertigten oder benutzerdefinierten Funktionen in SharePoint Online verwendet werden.

Hinweis

Der Import funktioniert nur für Benutzerprofileigenschaften, für die vom Endbenutzern nicht festgelegt wurde, dass sie bearbeitet werden können. Dadurch soll verhindert werden, dass der Benutzerprofilimportvorgang Informationen überschreibt, die ein Endbenutzer bereits aktualisiert hat. Darüber hinaus lässt der Import nur benutzerdefinierte Eigenschaften zu, die keine Active Directory-Kerneigenschaften sind. Benutzer müssen mit Azure AD synchronisiert werden. Die Liste dieser Kernverzeichniseigenschaften finden Sie in der Tabelle, die weiter unten in diesem Artikel im Abschnitt „Häufig gestellte Fragen“ aufgeführt ist.

Im Folgenden finden Sie ein kurzes Video, das zeigt, wie Sie die CSOM-API UserProfile.BatchUpdate.API sowohl aus verwaltetem Code (.NET) als auch aus PowerShell heraus verwenden.

Verwenden des Importvorgangs für Benutzerprofileigenschaften

Im Folgenden sehen Sie den vollständigen Prozess:

  1. Erstellen oder synchronisieren Sie Benutzer in einen Office 365-Mandanten oder in das ihm zugeordnete Azure AD.
    • Wenn Benutzer in Azure AD synchronisiert werden, wird ebenfalls ein standardisierter Satz von Attributen in den SharePoint Online-Benutzerprofilspeicher synchronisiert.
  2. Erstellen Sie alle benötigten benutzerdefinierten Eigenschaften innerhalb des Benutzerprofildiensts.
    • Da es keine Remote-APIs zum Erstellen benutzerdefinierter Eigenschaften im Benutzerprofildienst gibt, muss dieser Schritt für jeden Mandanten manuell ausgeführt werden, für den benutzerdefinierte Benutzerprofileigenschaften erforderlich sind (dies muss nur einmal pro Mandant erfolgen).
    • Nur Benutzerprofileigenschaften, die „von Endbenutzern nicht bearbeitet werden dürfen“, können importiert werden. Der Versuch, eine JSON-Objekteigenschaft in eine Benutzerprofileigenschaft zu importieren, die als „von Endbenutzern bearbeitbar“ markiert ist, führt zu einer Ausnahme, wenn die CSOM-API aufgerufen wird.
  3. Erstellen Sie die JSON-Datei, und laden Sie sie in den Office 365-Mandanten hoch.
    • Sie müssen die JSON-Datendatei mit den Informationen hochladen, die auf den Office 365-Mandanten aktualisiert werden sollen.
    • Im Falle einer Ausnahme während des Importvorgangs stellt SharePoint zusätzliche Protokollierungsinformationen bereit, die in einem Unterordner in derselben Dokumentbibliothek gespeichert werden, in der sich die Datei befunden hat.
    • Die Bereinigung der Protokoll- und JSON-Dateien erfolgt nicht automatisch und liegt in der Verantwortung der benutzerdefinierten Lösung, die die API verwendet. Sie sollten den Lebenszyklus dieser Dateien innerhalb Ihrer Implementierung berücksichtigen. Diese Dateien werden in Dokumentbibliotheken gespeichert, sodass sie einen Teil des zugewiesenen Speichers für die Websitesammlung verbrauchen.
  4. Rufen Sie die API für den Massenimport von Benutzerprofilattributen auf, um den Importauftrag in die Warteschlange zu stellen.
    • Verwenden Sie die CSOM-API, um den Importvorgang in die Warteschlange zu stellen. Dies kann durch Ausführen von CSOM-Code mithilfe von verwaltetem Code (.NET) oder der PowerShell erreicht werden.
    • Die Methode zum Einreihen des Auftrags in die Warteschlange erfordert Eigenschaftenzuordnungsinformationen und den Speicherort der Datendatei. Diese Methode wird schnell ausgeführt, da sie den eigentlichen Importvorgang in die Warteschlange stellt, der später als Teil eines Back-End-Prozesses in SharePoint Online ausgeführt wird.
  5. Überprüfen Sie den Status des Importauftrags.
    • Sie können auch Remote-APIs verwenden, um den Status eines bestimmten Importauftrags oder den aller zuletzt verwendeten Importaufträge zu überprüfen. Um den Status eines bestimmten Aufrufs überprüfen zu können, sollten Sie den eindeutigen Auftragsbezeichner speichern, den Sie als Rückgabewert empfangen, wenn der Auftrag in die Warteschlange eingereiht wird.

Erstellen und Hochladen der JSON-Datei

Der Importvorgang verwendet eine JSON-Datei, die die Eigenschaften und deren Werte enthält. Im Folgenden sehen Sie die erwartete Struktur dieser Datei:

{
   "value": [
     {
       "<IdName>": "<UserIdValue_1>",
       "<AttributeName_1>": "<User1_AttributeValue_1>",
       "<AttributeName_2>": "<User1_AttributeValue_2>",
     },
     {
       "<IdName>": "<UserIdValue_2>",
       "<AttributeName_1>": "<User2_AttributeValue_1>",
       "<AttributeName_2>": "<User2_AttributeValue_2>",
     },
     {
       "<IdName>": "<UserIdValue_n>",
       "<AttributeName_1>": "<Usern_AttributeValue_1>",
       "<AttributeName_2>": "<Usern_AttributeValue_2>",
     }
   ]
}

Beispiel

Es folgt eine einfache Beispieldatei, die das Format aus dem vorherigen Beispiel verwendet. In diesem Beispiel basiert die Identitätsauflösung auf der IdName-Eigenschaft, und es gibt zwei Eigenschaften, die aktualisiert werden, namens City und Office. Die Datei enthält Informationen für vier verschiedene Konten innerhalb des Mandanten. Eigenschaftennamen, die in dieser Quelldatei verwendet werden, sind nicht notwendigerweise identisch mit den Namen, die im SharePoint Online-Benutzerprofildienst verwendet werden, da wir die richtige Eigenschaftenzuordnung in unserem Code bereitstellen. 

{
  "value": [
    {
      "IdName": "vesaj@contoso.com",
      "City": "Helsinki",
      "Office": "Viper"
    },
    {
      "IdName": "bjansen@contoso.com",
      "City": "Brussels",
      "Office": "Beetle"
    },
    {
      "IdName": "unknowperson@contoso.com",
      "City": "None",
      "Office": ""
    },
    {
      "IdName": "erwin@contoso.com",
      "City": "Stockholm",
      "Office": "Elite"
    }
  ]
}

Einschränkungen für Quelldatendateien

Die folgenden Einschränkungen gelten für einzelne Quelldatendateien:

  • Maximale Dateigröße: 2 GB
  • Maximale Anzahl von Eigenschaften: 500.000
  • Umgekehrte Schrägstriche () in Eigenschaftswerten müssen escapen, indem sie mit einem anderen umgekehrten Schrägstrich vorangestellt werden
  • Die Quelldatei muss in denselben SharePoint Online-Mandanten hochgeladen werden, in dem der Prozess gestartet wird.

Hinweis

Für die Aktualisierungsdatei muss die Bytereihenfolge-Marke (Byte Order Mark, BOM) angegeben sein, wenn Zeichen nicht Teil der westeuropäischen Codierung (iso-8859-1) sind, bei der es sich um den Standardwert handelt. Internationale Zeichen werden möglicherweise nicht ordnungsgemäß mit der Standardcodierung interpretiert, weshalb es sich empfiehlt, die UTF-8-Codierung zu verwenden. Diese Codierung verfügt über eine BOM von „EF BB BF“ im Hexadezimalformat. Diese wird beim Erstellen des Dateistreams am Anfang des Bytearrays der Datei platziert. Wenn Sie einen Text-Editor verwenden, wählen Sie vor dem Speichern den Codierungstyp als UTF-8 aus.

Einreihen des Importvorgangs in die Warteschlange

Sie können die CSOM-API für den Massenimportvorgang in die Warteschlange stellen, indem Sie die QueueImportProfileProperties-Methode aufrufen, die sich im Office365Tenant-Objekt befindet. Dies ist ein asynchroner Aufruf, da er weder die Quelldaten herunterlädt, noch den Import ausführt. Er fügt der Warteschlange einfach ein Arbeitselement hinzu, um dies später auszuführen.

Im Folgenden sehen Sie die vollständige Signatur der Methode:

public ClientResult<Guid> QueueImportProfileProperties(
                          ImportProfilePropertiesUserIdType idType,
                          string sourceDataIdProperty,
                          IDictionary<string, string> propertyMap,
                          string sourceUri);

Parameter

  • idType: ImportProfilePropertiesUserIdType

    Der Typ der ID, der beim Nachschlagen des Benutzerprofils verwendet werden soll. Mögliche Werte sind Email, CloudId und PrincipalName. Beachten Sie, dass der Benutzer unabhängig vom Typ bereits im Benutzerprofildienst vorhanden sein muss, damit der Import funktioniert. Es wird empfohlen, den Wert CloudId zu verwenden, um Eindeutigkeit zu gewährleisten.

    Eigenschaftenzuordnung zwischen ID-Typ und Azure AD.-Eigenschaft:

    UPA-Massenimport-ID-Typ Azure AD-Attribut
    CloudId ObjectID
    PrincipalName userPrincipalName
    Email mail

  • sourceDataIdProperty: System.String

    Der Name der ID-Eigenschaft in den Quelldaten. Der Wert der Eigenschaft aus den Quelldaten wird verwendet, um den Benutzer nachzuschlagen. Die für die Suche verwendete Benutzerprofildiensteigenschaft hängt vom Wert von idType ab.

  • propertyMap: IDictionary<string, string>

    Eine Zuordnung vom Quelleigenschaftsnamen zum Eigenschaftennamen des Benutzerprofildiensts. Beachten Sie, dass die Eigenschaften des Benutzerprofildiensts bereits vorhanden sein müssen. Der Schlüssel ist der in der Quelldatei verwendete Eigenschaftenname. Der Wert ist der im Benutzerprofildienst verwendete Eigenschaftenname.

  • sourceUri: System.String

    Der URI der zu importierenden Quelldatendatei. Die Datei sollte nicht sofort verschoben oder gelöscht werden, da sie möglicherweise einige Zeit lang nicht heruntergeladen wird.

Rückgabewert

Eine GUID, die den Importauftrag identifiziert, der in die Warteschlange eingereiht wurde.

Beispiel

Es folgt ein Beispiel, das C# zum Starten des Prozesses mithilfe der vorherigen Beispieleingabedatei verwendet:

// Create an instance of the Office 365 Tenant object. Loading this object is not technically needed for this operation.
Office365Tenant tenant = new Office365Tenant(ctx);
ctx.Load(tenant);
ctx.ExecuteQuery();

// Type of user identifier ["PrincipalName", "Email", "CloudId"] in the
// user profile service. In this case, we use Email as the identifier at the UPA storage
ImportProfilePropertiesUserIdType userIdType =
      ImportProfilePropertiesUserIdType.Email;

// Name of the user identifier property within the JSON file
var userLookupKey = "IdName";

var propertyMap = new System.Collections.Generic.Dictionary<string, string>();

// The key is the property in the JSON file
// The value is the user profile property Name in the user profile service
// Notice that we have 2 custom properties in UPA called 'City' and 'OfficeCode'
propertyMap.Add("City", "City");
propertyMap.Add("Office", "OfficeCode");

// Returns a GUID that can be used to check the status of the execution and the end results
var workItemId = tenant.QueueImportProfileProperties(
      userIdType, userLookupKey, propertyMap, fileUrl
      );

ctx.ExecuteQuery();

Überprüfen des Status eines Importauftrags

Sie können den Status der Importaufträge des Benutzerprofildiensts mithilfe der CSOM-APIs überprüfen. Hierfür gibt es zwei Methoden im Mandantenobjekt (Tenant):

  • Um den Status eines einzelnen Importauftrags zu überprüfen, verwenden Sie die GetImportProfilePropertyJob-Methode.
  • Um den Status aller Importaufträge zu überprüfen, verwenden Sie die GetImportProfilePropertyJobs-Methode.

Einzelner Importauftrag

Sie können den Status eines einzelnen Importauftrags überprüfen, indem Sie die GetImportProfilePropertyJob-Methode verwenden, die sich im Office365Tenant-Objekt befindet. Sie müssen den eindeutigen Bezeichner eines bestimmten Importauftrags als Parameter für diese Methode angeben.

Im Folgenden sehen Sie die vollständige Signatur der Methode:

public ImportProfilePropertiesJobInfo GetImportProfilePropertyJob(Guid jobId);

Parameter

  • jobID: System.Guid

    Die ID des Auftrags, für den der allgemeine Status abgerufen werden soll.

Rückgabewert

Ein ImportProfilePropertiesJobStatus-Objekt mit allgemeinen Statusinformationen zum angegebenen Auftrag.

Beispiel

Es folgt ein Beispiel, das C# zum Abrufen des Status eines bestimmten Importauftrags mithilfe eines gespeicherten Bezeichners verwendet:

// Check the status of a specific request based on the job id received when we queued the job
Office365Tenant tenant = new Office365Tenant(ctx);
var job = tenant.GetImportProfilePropertyJob(workItemId);
ctx.Load(job);
ctx.ExecuteQuery();

Alle Importaufträge

Sie können den Status aller Importaufträge überprüfen, indem Sie die GetImportProfilePropertyJobs-Methode verwenden, die sich im Office365Tenant-Objekt befindet.

Im Folgenden sehen Sie die vollständige Signatur der Methode:

public ImportProfilePropertiesJobStatusCollection GetImportProfilePropertyJobs(); 

Parameter

Ein ImportProfilePropertiesJobInfo-Objekt, das mit den Importstatusinformationen zurückgegeben wird, weist die folgenden Eigenschaften auf. 

  • JobId: System.Guid

    Die ID des Importauftrags.

  • State: ImportProfilePropertiesJobState

    Eine Aufzählung der folgenden Werte:

    • Unknown: Wir können den Zustand des Auftrags nicht ermitteln.
    • Submitted: Der Auftrag wurde an das System übermittelt.
    • Processing: Der Auftrag wird verarbeitet.
    • Queued: Der Auftrag hat die Überprüfung bestanden und wird für den Import in UPA in die Warteschlange eingereiht.
    • Succeeded: Der Auftrag wurde ohne Fehler abgeschlossen.
    • Error: Der Auftrag wurde mit Fehlern abgeschlossen.

  • SourceUri: System.String

    Der URI der Datenquelldatei.

  • Error: ImportProfilePropertiesJobError

    Eine Auflistung, die den möglichen Fehler darstellt:

    • NoError: Kein Fehler gefunden.
    • InternalError: Der Fehler wurde durch einen Fehler im Dienst verursacht.
    • DataFileNotExist: Die Datenquelldatei wurde nicht gefunden.
    • DataFileNotInTenant: Die Datenquelldatei gehört nicht zum selben Mandanten.
    • DataFileTooBig: Die Datendatei war zu groß.
    • InvalidDataFile: Die Datenquelldatei hat die Überprüfung nicht bestanden (möglicherweise sind weitere Details in der Protokolldatei enthalten).
    • ImportCompleteWithError: Die Daten wurden importiert, aber es ist ein Fehler aufgetreten.

  • ErrorMessage: System.String

    Die Fehlermeldung.

  • LogFileUri: System.String

    Der URI für den Ordner, in den die Protokolle geschrieben wurden.

Rückgabewert

Ein ImportProfilePropertiesJobStatusCollection-Objekt, bei dem es sich um eine Sammlung von ImportProfilePropertiesJobStatus-Objekten mit allgemeinen Statusinformationen zu den einzelnen Aufträgen handelt.

Beispiel

Es folgt ein Beispiel, das C# zum Abrufen des Status aller Importaufträge, die aktuell im Mandanten gespeichert sind, verwendet. Diese können bereits verarbeitete oder in die Warteschlange eingereihte Aufträge sein:

// Load all import jobs – old and queued ones
Office365Tenant tenant = new Office365Tenant(ctx);
var jobs = tenant.GetImportProfilePropertyJobs();
ctx.Load(jobs);
ctx.ExecuteQuery();
foreach (var item in jobs)
{
   // Check whatever properties needed
   var state = item.State;
}

Aufrufen der Import-API aus PowerShell

Sie können die Massenimport-API des Benutzerprofildiensts mithilfe von PowerShell nutzen. Dies bedeutet, dass Sie den CSOM-Code direkt in einem PowerShell-Skript verwenden, indem Sie die erforderlichen Parameter verwenden. Dies erfordert, dass das aktualisierte verteilbare CSOM-Paket auf dem Computer installiert wurde, auf dem das Skript ausgeführt wird.

Wenn Sie PowerShell verwenden, müssen Sie Ihren Code nicht in Visual Studio kompilieren, was für einige Kunden ein geeigneteres Modell sein kann.

Alternativ können Sie PnP PowerShell verwenden, womit Sie die Massenimport-API des Benutzerprofildiensts verwenden können, ohne zusätzliche Bibliotheken auf Ihrem System installieren zu müssen.

PowerShell-Beispielskript unter Verwendung von CSOM-Bibliotheken

Im Folgenden sehen Sie ein PowerShell-Beispielskript, das dieselben Vorgänge wie der vorherige Code ausführt:

# Get needed information from the end user
$adminUrl = Read-Host -Prompt 'Enter the admin URL of your tenant'
$userName = Read-Host -Prompt 'Enter your user name'
$pwd = Read-Host -Prompt 'Enter your password' -AsSecureString
$importFileUrl = Read-Host -Prompt 'Enter the URL to the file located in your tenant'

# Get instances to the Office 365 tenant using CSOM
$uri = New-Object System.Uri -ArgumentList $adminUrl
$context = New-Object Microsoft.SharePoint.Client.ClientContext($uri)

$context.Credentials = New-Object Microsoft.SharePoint.Client.SharePointOnlineCredentials($userName, $pwd)
$o365 = New-Object Microsoft.Online.SharePoint.TenantManagement.Office365Tenant($context)
$context.Load($o365)

# Type of user identifier ["Email", "CloudId", "PrincipalName"] in the user profile service
$userIdType=[Microsoft.Online.SharePoint.TenantManagement.ImportProfilePropertiesUserIdType]::Email

# Name of user identifier property in the JSON
$userLookupKey="idName"

# Create property mapping between the source file property name and the Office 365 property name
# Notice that we have here 2 custom properties in UPA called 'City' and 'OfficeCode'
$propertyMap = New-Object -type 'System.Collections.Generic.Dictionary[String,String]'
$propertyMap.Add("City", "City")
$propertyMap.Add("Office", "OfficeCode")

# Call to queue UPA property import
$workItemId = $o365.QueueImportProfileProperties($userIdType, $userLookupKey, $propertyMap, $importFileUrl);

# Execute the CSOM command for queuing the import job
$context.ExecuteQuery();

# Output the unique identifier of the job
Write-Host "Import job created with the following identifier:" $workItemId.Value

Aktualisieren des SharePoint Online-Benutzerprofils mithilfe von PnP PowerShell

Zum Synchronisieren von Benutzerprofileigenschaften von Azure Active Directory mit SharePoint Online-Benutzerprofilen können Sie das PnP PowerShell-Cmdlet Sync-PnPSharePointUserProfilesFromAzureActiveDirectoryverwenden.

Wenn Sie Benutzerprofileigenschaften aus einer anderen Quelle synchronisieren möchten, können Sie alternativ New-PnPUPABulkImportJob verwenden.

Um den Verarbeitungsstatus eines Massenimportauftrags zu überprüfen, können Sie Get-PnPUPABulkImportStatus verwenden.

Hinweis

PnP PowerShell ist eine Open Source-Lösung mit aktiver Community, die Support dafür bietet. Es gibt keine SLA für den Support des Open-Source-Tools durch Microsoft.

Behandeln von Ausnahmen

Es gibt zwei Überprüfungsebenen, wenn diese API verwendet wird. Wenn Sie den Importvorgang mit CSOM in die Warteschlange stellen, gibt es eine anfängliche Überprüfungsebene der angegebenen Werte. Dies schließt die Bestätigung ein, dass die bereitgestellten Zuordnungseigenschaften im Benutzerprofildienst vorhanden sind und dass diese Eigenschaften vom Endbenutzer nicht bearbeitet werden können. Wenn die Warteschlangen-API aufgerufen wird, wird nur eine anfängliche Überprüfungsebene angewendet, und die abschließende Überprüfung der bereitgestellten Informationen wird ausgeführt, wenn der Importauftrag tatsächlich ausgeführt wird.

Wenn während der eigentlichen Ausführung des Importauftrags Ausnahmen auftreten, wird eine Protokollierungsdatei mit zusätzlichen Details in derselben Dokumentbibliothek generiert, in der sich die Importdatei befand. Protokolldateien für bestimmte Importaufträge werden in Unterordnern gespeichert, die mithilfe des eindeutigen Bezeichners des jeweiligen Importauftrags benannt werden.

Im Folgenden finden Sie ein Beispiel für die Ergebnisse der Ausführung eines Importauftrags. In der folgenden Abbildung sehen Sie zwei Unterordner für zwei verschiedene Ausführungen, die in der Dokumentbibliothek erstellt wurden, in der die Importdatei gespeichert ist.

Unterordner für Auftragsausnahmen

Die eigentliche Protokolldatei wird im Unterordner gespeichert, und Sie können sie aus zur detaillierten Analyse aus Office 365 herunterladen.

Protokolldatei für Auftragsausnahmen

Gängige Ausnahmen

Die folgende Tabelle enthält typische Ausnahmen, die auftreten können, wenn Sie mit der Verwendung der Massen-API des Benutzerprofildiensts beginnen.

Beispielausnahme Details
Eigenschaftsnamen [AboutMe] können vom Benutzer bearbeitet werden. Diese würde von der CSOM-API ausgelöst, wenn Sie die ExecuteQuery-Methode aufrufen, wenn Sie den Auftrag an Ihren Mandanten übermitteln. Die API überprüft, ob alle derzeit zugeordneten Eigenschaften NICHT vom Benutzer bearbeitet werden können. Die Ausnahme verweist auf die Eigenschaft, die nicht verwendet werden kann.

In diesem Beispiel haben wir versucht, der AboutMe-Eigenschaft in den Eigenschaften des Benutzerprofildiensts eine JSON-Eigenschaft zuzuordnen. Dies ist jedoch nicht zulässig, da AboutMe eine vom Benutzer bearbeitbare Eigenschaft ist.
InvalidProperty: vesaj@contoso.com Die Eigenschaft "AboutMe" ist keiner Eigenschaft in der Benutzerprofilanwendung zugeordnet. Die JSON-Datendatei enthielt eine Eigenschaft, die nicht der Eigenschaft des Benutzerprofildiensts in SharePoint Online zugeordnet wurde. Dies bedeutet, dass die Quelldatendatei Eigenschaften enthält, für die Sie keine Zuordnung im propertyMap-Parameter bereitgestellt haben. Sie müssen für jede der Eigenschaften im JSON-Datenobjekt eine Zuordnungsdefinition haben.
MissingIdentity: Die Identität für das Benutzerobjekt fehlt. Die Identitätseigenschaft wurde im Benutzerobjekt nicht gefunden. Die wahrscheinlichste Ursache ist, dass das sourceDataIdProperty-Attribut für die QueueImportProfileProperties-Methode falsch festgelegt ist. Stellen Sie sicher, dass Sie über die richtige Eigenschaft in der JSON-Quelldatei verfügen und dass Ihr Code/Skript dieses Attribut entsprechend zuweist.
IdentityNotResolvable unknown@contoso.com Benutzeridentität kann nicht aufgelöst werden Die Datendatei enthält eine Identität, die nicht aufgelöst werden konnte oder im Benutzerprofildienst nicht vorhanden war. In diesem Fall konnte das Benutzerprofil mit der E-Mail-Adresse nicht unknown@contoso.com im Benutzerprofildienst gefunden werden.
DataFileNotJson: JsonToken EndObject ist für das Schließen des JsonType-Arrays ungültig. Pfad 'Wert', Zeile 8, Position 10. Das Format Ihrer Importdatei ist kein gültiges JSON-Format und entspricht nicht dem erwarteten Format. 

Häufig gestellte Fragen

Kann ich den Code mit „Nur-App“-/“Nur-Add-In“-Berechtigungen ausführen?

Ja, der tatsächliche Import der Datei erfolgt nicht synchron mit der Identität des Aufrufers, sodass dies ohne Probleme mit dem „Nur-App“-Kontext funktioniert.

Um einen „Nur-App“-Kontext mit dem SharePoint-Add-In-Modell zu verwenden, müssen Sie gemäß diesem Leitfaden eine Client-ID und ein Geheimnis registrieren, um die APIs ausführen zu können. Darüber hinaus müssen Sie beim Registrieren des SharePoint-Add-Ins die Berechtigungen mithilfe des folgenden XML-Codeausschnitts erteilen:

<AppPermissionRequests AllowAppOnlyPolicy="true">
  <AppPermissionRequest Scope="http://sharepoint/content/tenant" Right="FullControl" />
  <AppPermissionRequest Scope="http://sharepoint/social/tenant" Right="FullControl" />
</AppPermissionRequests>

Wichtig

Die Verwendung von Azure ACS (Access Control Services) für SharePoint Online wurde am 27. November 2023 eingestellt. Weitere Informationen finden Sie in der Ankündigung zur vollständigen Einstellung. Die Verwendung von Azure ACS außerhalb des SharePoint-Kontexts wurde bereits am 7. November 2018 eingestellt und endet jetzt.

Die Einstellung bedeutet, dass das Feature keine neuen Investitionen erhält, aber weiterhin unterstützt wird. Ende der Lebensdauer bedeutet, dass das Feature nicht mehr zur Verfügung steht.

Um „Nur-App“ mit einer in Azure Active Directory registrierten Anwendung zu verwenden, müssen Sie die Anwendung registrieren, ein X.509-Zertifikat für die Authentifizierung bereitstellen, was eine Voraussetzung für die SharePoint Online-„Nur-App“-Authentifizierung innerhalb von Azure Active Directory ist, und die folgenden SharePoint Online-Berechtigungsbereiche für die Anwendung gewähren: „Sites.FullControl.All“ und „User.ReadWrite.All“.

Diese API aktualisiert die Eigenschaften im Benutzerprofildienst, aber wie erstelle ich diese Eigenschaften im Mandanten?

Es gibt keine Remote-API zum programmgesteuerten Erstellen benutzerdefinierter Benutzerprofileigenschaften, sodass dies ein manueller Vorgang ist, der einmal pro Mandant durchgeführt werden muss. Anleitungen, wie Sie diese benutzerdefinierten Eigenschaften erstellen, finden Sie unter Hinzufügen und Bearbeiten von Benutzerprofileigenschaften in SharePoint Online.

Ist diese Funktion in lokalem SharePoint verfügbar?

Leider ist diese Funktion derzeit nur in SharePoint Online verfügbar. In lokalem SharePoint wäre diese Funktion nützlich, aber nicht so kritisch, weil Sie die Attributzuordnung in der lokalen Benutzerprofildienst-Anwendung ändern können. Sie können auch das Importieren von Benutzerprofilattributen nutzen, indem Sie den Business Connectivity Service (BCS) in SharePoint 2013 verwenden. Diese Option ist jedoch in SharePoint 2016 nicht verfügbar, was bedeutet, dass für SharePoint 2016 derzeit die einzige Möglichkeit darin besteht, Anpassungen zu implementieren, die die Benutzerprofil-Webdienste nutzen.

Könnte ich diese API zum Synchronisieren der Werte von Benutzerprofileigenschaften aus meinen lokalen SharePoint-Farmen in SharePoint Online verwenden?

Ja, lokales SharePoint kann genau wie jedes andere Quellsystem verwendet werden. Sie müssen die Benutzerprofilwerte aus Ihrem lokalen SharePoint in das JSON-Dateiformat exportieren, wonach der Prozess exakt dem Vorgang wie beim Importieren von Werten aus jedem anderen System entspricht.

Kann ich zeichenfolgenbasierte Mehrwerteigenschaften importieren?

Nein, dies wird von dieser API derzeit nicht unterstützt.

Welche Berechtigungen sind für die Ausführung dieser API erforderlich?

Aktuell müssen Sie über globale Administratorberechtigungen verfügen, es sei denn, Sie verwenden einen „Nur-App“-Authentifizierungskontext. SharePoint-Administrator ist nicht ausreichend.

Kann ich taxonomiebasierte Eigenschaften importieren?

Nein, dies wird von dieser API derzeit nicht unterstützt.

Was geschieht, wenn ich eine Zuordnung im Code definiere, die nicht verwendet wird, oder wenn die JSON-Datei Eigenschaften enthält, die nicht zugeordnet sind?

Wenn Ihr Code/Skript eine Zuordnung definiert, die nicht verwendet wird, oder die Datendatei keine Eigenschaften für diese Zuordnung enthält, wird die Ausführung ohne Ausnahmen fortgesetzt, und der Import wird auf Grundlage der zugeordneten Eigenschaften angewendet. Wenn sie jedoch eine Eigenschaft in der JSON-Datei haben, die nicht zugeordnet ist, wird der Importvorgang abgebrochen, und Ausnahmedetails werden in der Protokolldatei für die jeweilige Auftragsausführung bereitgestellt.

Was geschieht, wenn ich benutzerdefinierte Eigenschaften aktualisieren muss, die die Größenbeschränkungen dieser Massen-API überschreiten (d. h. größer als eine 2 GB-Datei oder mehr als 500.000 Eigenschaften)?

Sie müssen Ihre Aufträge entsprechend als Batches zusammenfassen, indem Sie mehrere Aufträge nacheinander auslösen (d. h. einen Auftrag nach dem anderen mit dem maximalen Grenzwert für diese API abschließen). Sie sollten davon ausgehen, dass solche Importe mit hoher Bandbreite sehr lange dauern werden. Außerdem sollten Sie die Importaufträge so optimieren, dass nur Deltaänderungen an benutzerdefinierten Profileigenschaften berücksichtig werden, anstatt einen vollständigen Satz von Werten in alle Aufträge zu importieren.

Welche Azure AD-Attribute werden standardmäßig in SharePoint Online-Benutzerprofile synchronisiert?

In der folgenden Tabelle finden Sie die offizielle Liste der synchronisierten Attribute und deren Zuordnung zwischen Azure AD und dem SharePoint Online-Benutzerprofildienst.

Azure Directory-Attribut SharePoint Online-Profileigenschaft
ObjectSid SPS-SavedSID
msonline-UserPrincipalName UserName
msonline-UserPrincipalName AccountName
msonline-UserPrincipalName SPS-ClaimID
msonline-UserPrincipalName SPS-UserPrincipalName
GivenName FirstName
sn LastName
Manager Manager
DisplayName PreferredName
telephoneNumber WorkPhone
proxyAddresses WorkEmail
proxyAddresses SPS-SIPAddress
PhysicalDeliveryOfficeName Büro
Position Titel
Titel SPS-JobTitle
Department Department
Department SPS-Department
ObjectGuid ADGuid
WWWHomePage PublicSiteRedirect
DistinguishedName SPS-DistinguishedName
msOnline-ObjectId msOnline-ObjectId
PreferredLanguage SPS-MUILanguages
msExchHideFromAddressList SPS-HideFromAddressLists
msExchRecipientTypeDetails SPS-RecipientTypeDetails
msonline-groupType IsUnifiedGroup
msOnline-IsPublic IsPublic
msOnline-ObjectId msOnline-ObjectId
msOnline-UserType SPS-UserType
GroupType GroupType
SPO-IsSharePointOnlineObject SPO-IsSPO

Siehe auch