Freigeben über

Ausführen von bulkUpload

  • Artikel

Namespace: microsoft.graph

Wichtig

Die APIs unter der /beta Version in Microsoft Graph können sich ändern. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt. Um festzustellen, ob eine API in v1.0 verfügbar ist, verwenden Sie die Version Selektor.

Führen Sie mithilfe des Synchronisierungsauftrags einen neuen Massenupload durch. Verwenden Sie diesen API-Endpunkt, um Daten im Microsoft Entra-Synchronisierungsdienst zu erfassen. Der Synchronisierungsdienst wendet die Zuordnungen an, die dem Synchronisierungsauftrag zugeordnet sind, und verarbeitet die eingehenden Daten. Das Ratenlimit für diese API beträgt 40 Anforderungen pro Sekunde. Jede Anforderung kann maximal 50 Benutzervorgänge im Massenanforderungs-Operations-Array enthalten.

Hinweis

Diese API befindet sich in der öffentlichen Vorschau und ist nur für die Verwendung mit API-gesteuerten Eingehenden Bereitstellungs-Apps verfügbar.

Berechtigungen

Wählen Sie für diese API die Als am wenigsten privilegierten Berechtigungen gekennzeichneten Berechtigungen aus. Verwenden Sie nur dann eine Berechtigung mit höheren Berechtigungen , wenn dies für Ihre App erforderlich ist. Ausführliche Informationen zu delegierten Berechtigungen und Anwendungsberechtigungen finden Sie unter Berechtigungstypen. Weitere Informationen zu diesen Berechtigungen finden Sie in der Berechtigungsreferenz.

Berechtigungstyp Berechtigungen mit den geringsten Berechtigungen Berechtigungen mit höheren Berechtigungen
Delegiert (Geschäfts-, Schul- oder Unikonto) SynchronizationData-User.Upload Nicht verfügbar.
Delegiert (persönliches Microsoft-Konto) Nicht unterstützt Nicht unterstützt
Anwendung SynchronizationData-User.Upload Nicht verfügbar.

Hinweis

Diese API ist in erster Linie für die Verwendung innerhalb einer Anwendung oder eines Diensts vorgesehen, die für die Verarbeitung autoritativer Identitätsdaten und das Hochladen in Microsoft Entra ID verantwortlich ist. Mandantenadministratoren können entweder einen Dienstprinzipal oder eine verwaltete Identität konfigurieren , um die Berechtigung zum Durchführen des Uploads zu erteilen. Es gibt keine separate benutzerseitig zuweisbare Microsoft Entra integrierte Verzeichnisrolle für diese API. Außerhalb von Anwendungen, die die Berechtigung mit Administratoreinwilligung erhalten SynchronizationData-User.Upload haben, können nur Administratorbenutzer mit der Rolle "Globaler Administrator " die API aufrufen.

HTTP-Anforderung

POST /servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/bulkUpload

Bezieht sich im API-Endpunkt {servicePrincipalId} auf die Dienstprinzipalobjekt-ID und {jobId} bezieht sich auf die Bereitstellungsauftrags-ID.

Anforderungsheader

Name Beschreibung
Authorization Bearer {token}. Erforderlich. Erfahren Sie mehr über die Authentifizierung und Autorisierung.
Content-Type application/scim+json. Erforderlich.

Anforderungstext

Geben Sie im Anforderungstext den Ressourcentyp bulkUpload an. Beispielnutzlasten finden Sie im Abschnitt beispiele .

Antwort

Bei erfolgreicher Ausführung wird eine 202 Accepted Antwort und nichts im Antworttext zurückgegeben. Außerdem wird ein Location-Header zum Überprüfen der status der Massenanforderungsbereitstellung zurückgegeben.

HTTP-Statuscode Erklärung
202 (Akzeptiert) Die Massenanforderung wird für die Ausführung bereitgestellt und vom zugeordneten Bereitstellungsauftrag verarbeitet. Der Location Schlüssel im Antwortheader verweist auf den Endpunkt der Bereitstellungsprotokolle, mit dem die status der Massenanforderungsbereitstellung überprüft werden kann.
400 (ungültige Anforderung) Die Anforderung kann nicht analysiert werden, ist syntaktisch falsch oder verstößt gegen das Schema. Die häufigste Ursache für diesen Fehler ist das Fehlen des Anforderungsheaders Content-Type. Stellen Sie sicher, dass sie vorhanden ist und auf application/scim+jsonfestgelegt ist.
401 (Nicht autorisiert) Der Autorisierungsheader ist ungültig oder fehlt. Stellen Sie sicher, dass der Autorisierungsheader über ein gültiges Zugriffstoken verfügt.
403 (Verboten) Die Oeration ist basierend auf der angegebenen Autorisierung nicht zulässig. Stellen Sie sicher, dass der API-Client über die berechtigung Graph-API verfügtSynchronizationData-User.Upload.

Beispiele

Beispiel 1: Massenupload mit SCIM Core-Benutzer- und Enterprise-Benutzerschema

Anforderung

Die folgende Massenanforderung verwendet das SCIM-Standardschema Core User and Enterprise User. Es verfügt über zwei Benutzervorgänge im Operations-Array . Sie können in jeder Massenanforderung maximal 50 Benutzervorgänge senden.

Verarbeitungsdetails: Der Bereitstellungsdienst liest die beiden Benutzerdatensätze. Es verwendet das übereinstimmende Attribut für userName und externalId , das in der Attributzuordnung des Bereitstellungsauftrags konfiguriert ist, um zu bestimmen, ob das Benutzerkonto im Verzeichnis erstellt, aktualisiert, aktiviert oder deaktiviert werden soll. Der Managerverweis wird mithilfe des manager.value -Felds aufgelöst. Geben Sie den externalId des Vorgesetzten des Benutzers in diesem Feld an. Im folgenden Beispiel weist der Bereitstellungsdienst Barbara Jensen als Managerin für Kathy Jensen zu.

POST https://graph.microsoft.com/beta/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/bulkUpload
Authorization: Bearer <token>
Content-Type: application/scim+json

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
    "Operations": [
    {
        "method": "POST",
        "bulkId": "701984",
        "path": "/Users",
        "data": {
            "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
            "externalId": "701984",
            "userName": "bjensen@example.com",
            "name": {
                "formatted": "Ms. Barbara J Jensen, III",
                "familyName": "Jensen",
                "givenName": "Barbara",
                "middleName": "Jane",
                "honorificPrefix": "Ms.",
                "honorificSuffix": "III"
            },
            "displayName": "Babs Jensen",
            "nickName": "Babs",
            "emails": [
            {
              "value": "bjensen@example.com",
              "type": "work",
              "primary": true
            }
            ],
            "addresses": [
            {
              "type": "work",
              "streetAddress": "234300 Universal City Plaza",
              "locality": "Hollywood",
              "region": "CA",
              "postalCode": "91608",
              "country": "USA",
              "formatted": "100 Universal City Plaza\nHollywood, CA 91608 USA",
              "primary": true
            }
            ],
            "phoneNumbers": [
            {
              "value": "555-555-5555",
              "type": "work"
            }
            ],
            "userType": "Employee",
            "title": "Tour Guide",
            "preferredLanguage": "en-US",
            "locale": "en-US",
            "timezone": "America/Los_Angeles",
            "active":true,
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
                "employeeNumber": "701984",
                "costCenter": "4130",
                "organization": "Universal Studios",
                "division": "Theme Park",
                "department": "Tour Operations",
                "manager": {
                  "value": "89607",
                  "displayName": "John Smith"
                 }
            }
        }
    },
    {
        "method": "POST",
        "bulkId": "701985",
        "path": "/Users",
        "data": {
            "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
            "externalId": "701985",
            "userName": "Kjensen@example.com",
            "name": {
                "formatted": "Ms. Kathy J Jensen, III",
                "familyName": "Jensen",
                "givenName": "Kathy",
                "middleName": "Jane",
                "honorificPrefix": "Ms.",
                "honorificSuffix": "III"
            },
            "displayName": "Kathy Jensen",
            "nickName": "Kathy",
            "emails": [
            {
              "value": "kjensen@example.com",
              "type": "work",
              "primary": true
            }
            ],
            "addresses": [
            {
              "type": "work",
              "streetAddress": "100 Oracle City Plaza",
              "locality": "Hollywood",
              "region": "CA",
              "postalCode": "91618",
              "country": "USA",
              "formatted": "100 Oracle City Plaza\nHollywood, CA 91618 USA",
              "primary": true
            }
            ],
            "phoneNumbers": [
            {
              "value": "555-555-5545",
              "type": "work"
            }
            ],
            "userType": "Employee",
            "title": "Tour Lead",
            "preferredLanguage": "en-US",
            "locale": "en-US",
            "timezone": "America/Los_Angeles",
            "active":true,
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
              "employeeNumber": "701984",
              "costCenter": "4130",
              "organization": "Universal Studios",
              "division": "Theme Park",
              "department": "Tour Operations",
              "manager": {
                "value": "701984",
                "displayName": "Barbara Jensen"
              }
            }
        }
    }
],
    "failOnErrors": null
}

Antwort

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.

HTTP/1.1 202 Accepted
Content-Type: application/scim+json
client-request-id: 92cd10f6-fcc3-5d61-098e-a6dd35e460ef
content-length: "0"
location: "https://graph.microsoft.com/beta/auditLogs/provisioning/?$filter=jobid%20eq%20'API2AAD.b16687d38faf42adb29892cdcaf01c6e.1a03de52-b9c3-4e2c-a1e3-9145aaa8e530'"
request-id: beeb9ea0-f7e4-4fe7-8507-cd834c88f18b

{}

Beispiel 2: Massenupload mit dem benutzerdefinierten SCIM-Schemanamespace

Anforderung

Die folgende Massenanforderung verwendet das SCIM-Standardschema Core User and Enterprise User. Es verfügt über einen weiteren benutzerdefinierten Schemanamespace namens urn:contoso:employee mit zwei Attributen HireDate und JobCode. Das schemas Array im Datenobjekt wird aktualisiert, um den benutzerdefinierten Schemanamespace einzuschließen.

Verarbeitungsdetails: Der Bereitstellungsdienst liest die beiden Benutzerdatensätze. Es verwendet das übereinstimmende Attribut für userName und externalId , das in der Attributzuordnung des Bereitstellungsauftrags konfiguriert ist, um zu bestimmen, ob das Benutzerkonto im Verzeichnis erstellt, aktualisiert, aktiviert oder deaktiviert werden soll. Wenn Sie die beiden benutzerdefinierten Attribute urn:contoso:employee:HireDate und urn:contoso:employee:JobCode in die Zuordnung des Bereitstellungsauftragsattributs einschließen, werden diese verarbeitet, und die entsprechenden Zielattribute werden festgelegt.

POST https://graph.microsoft.com/beta/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/bulkUpload
Authorization: Bearer <token>
Content-Type: application/scim+json

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
    "Operations": [
    {
        "method": "POST",
        "bulkId": "701984",
        "path": "/Users",
        "data": {
            "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
            "urn:contoso:employee"],
            "externalId": "701984",
            "userName": "bjensen@example.com",
            "name": {
                "formatted": "Ms. Barbara J Jensen, III",
                "familyName": "Jensen",
                "givenName": "Barbara",
                "middleName": "Jane",
                "honorificPrefix": "Ms.",
                "honorificSuffix": "III"
            },
            "displayName": "Babs Jensen",
            "nickName": "Babs",
            "emails": [
            {
              "value": "bjensen@example.com",
              "type": "work",
              "primary": true
            }
            ],
            "addresses": [
            {
              "type": "work",
              "streetAddress": "234300 Universal City Plaza",
              "locality": "Hollywood",
              "region": "CA",
              "postalCode": "91608",
              "country": "USA",
              "formatted": "100 Universal City Plaza\nHollywood, CA 91608 USA",
              "primary": true
            }
            ],
            "phoneNumbers": [
            {
              "value": "555-555-5555",
              "type": "work"
            }
            ],
            "userType": "Employee",
            "title": "Tour Guide",
            "preferredLanguage": "en-US",
            "locale": "en-US",
            "timezone": "America/Los_Angeles",
            "active":true,
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
                "employeeNumber": "701984",
                "costCenter": "4130",
                "organization": "Universal Studios",
                "division": "Theme Park",
                "department": "Tour Operations",
                "manager": {
                  "value": "89607",
                  "displayName": "John Smith"
                 }
            },
            "urn:contoso:employee": {
                "HireDate": "2021-05-01T00:00:00-05:00",
                "JobCode": "AB-1002"
            }            
        }
    },
    {
        "method": "POST",
        "bulkId": "701985",
        "path": "/Users",
        "data": {
            "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
            "urn:contoso:employee"],
            "externalId": "701985",
            "userName": "Kjensen@example.com",
            "name": {
                "formatted": "Ms. Kathy J Jensen, III",
                "familyName": "Jensen",
                "givenName": "Kathy",
                "middleName": "Jane",
                "honorificPrefix": "Ms.",
                "honorificSuffix": "III"
            },
            "displayName": "Kathy Jensen",
            "nickName": "Kathy",
            "emails": [
            {
              "value": "kjensen@example.com",
              "type": "work",
              "primary": true
            }
            ],
            "addresses": [
            {
              "type": "work",
              "streetAddress": "100 Oracle City Plaza",
              "locality": "Hollywood",
              "region": "CA",
              "postalCode": "91618",
              "country": "USA",
              "formatted": "100 Oracle City Plaza\nHollywood, CA 91618 USA",
              "primary": true
            }
            ],
            "phoneNumbers": [
            {
              "value": "555-555-5545",
              "type": "work"
            }
            ],
            "userType": "Employee",
            "title": "Tour Lead",
            "preferredLanguage": "en-US",
            "locale": "en-US",
            "timezone": "America/Los_Angeles",
            "active":true,
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
              "employeeNumber": "701984",
              "costCenter": "4130",
              "organization": "Universal Studios",
              "division": "Theme Park",
              "department": "Tour Operations",
              "manager": {
                "value": "701984",
                "displayName": "Barbara Jensen"
             }
            },
            "urn:contoso:employee": {
                "HireDate": "2022-07-15T00:00:00-05:00",
                "JobCode": "AB-1003"
            }            
        }
    }
],
    "failOnErrors": null
}

Antwort

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.

HTTP/1.1 202 Accepted
Content-Type: application/scim+json
client-request-id: 92cd10f6-fcc3-5d61-098e-a6dd35e460ef
content-length: "0"
location: "https://graph.microsoft.com/beta/auditLogs/provisioning/?$filter=jobid%20eq%20'API2AAD.b16687d38faf42adb29892cdcaf01c6e.1a03de52-b9c3-4e2c-a1e3-9145aaa8e530'"
request-id: beeb9ea0-f7e4-4fe7-8507-cd834c88f18b

{}

Beispiel 3: Massenupload zum Aktualisieren eines vorhandenen Benutzers

Anforderung

Die folgende Massenanforderung veranschaulicht, wie Attribute eines vorhandenen Microsoft Entra Benutzers aktualisiert, die Abteilung des Benutzers geändert und die Anmeldung für den Benutzer deaktiviert wird. In diesem Beispiel wird davon ausgegangen, dass Sie eine Zuordnung für die Felder externalId, department und active konfiguriert haben und über einen vorhandenen Microsoft Entra Benutzer verfügen, der über ein Attribut verfügt, das der externalId entspricht.

POST https://graph.microsoft.com/beta/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/bulkUpload
Authorization: Bearer <token>
Content-Type: application/scim+json

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
    "Operations": [
        {
            "method": "POST",
            "bulkId": "7172023",
            "path": "/Users",
            "data": {
                "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",
                "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
                "externalId": "7172023",
                "active": false,
                "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
                    "department": "Tour Ops"
                }
            }
        }
    ],
    "failOnErrors": null
}

Antwort

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.

HTTP/1.1 202 Accepted
Content-Type: application/scim+json
client-request-id: 92cd20f6-fcc3-5d61-098e-a6dd35e460ef
content-length: "0"
location: "https://graph.microsoft.com/beta/auditLogs/provisioning/?$filter=jobid%20eq%20'API2AAD.b16687d38faf42adb29892cdcaf01c6e.1a03de52-b9c3-4e2c-a1e3-9145aaa8e530'"
request-id: beec9ea0-f7e4-4fe7-8507-cd834c88f18b

{}