Freigeben über


Einladung erstellen

Namespace: microsoft.graph

Verwenden Sie diese API, um eine neue Einladung zu erstellen oder die einlösende status für einen Gastbenutzer zurückzusetzen, der seine Einladung bereits eingelöst hat. Die Einladung fügt den externen Benutzer im Rahmen der B2B-Zusammenarbeit dem organization hinzu. Die B2B-Zusammenarbeit wird sowohl in Microsoft Entra External ID als auch in externen Mandanten unterstützt.

Beim Erstellen einer neuen Einladung stehen Ihnen mehrere Optionen zur Verfügung:

  1. Bei der Erstellung von Einladungen kann Microsoft Graph automatisch eine Einladungs-E-Mail direkt an den eingeladenen Benutzer senden, oder Ihre App kann die in der Antwort zurückgegebene inviteRedeemUrl verwenden, um Ihre eigene Einladung (über den Kommunikationsmechanismus Ihrer Wahl) an den eingeladenen Benutzer zu erstellen. Wenn Sie sich dafür entscheiden, dass Microsoft Graph eine Einladungs-E-Mail automatisch sendet, können Sie den Inhalt und die Sprache der E-Mail mithilfe von invitedUserMessageInfo angeben.
  2. Wenn der Benutzer eingeladen wird, wird eine Benutzerentität ( userTypeGuest) erstellt, die zum Steuern des Zugriffs auf Ressourcen verwendet werden kann. Der eingeladene Benutzer muss den Einlösevorgang durchlaufen, um auf Ressourcen zuzugreifen, zu denen er eingeladen wurde.

Diese API ist in den folgenden nationalen Cloudbereitstellungen verfügbar.

Weltweiter Service US Government L4 US Government L5 (DOD) China, betrieben von 21Vianet

Berechtigungen

Wählen Sie die Berechtigungen aus, die für diese API als am wenigsten privilegiert markiert sind. Verwenden Sie eine höhere Berechtigung oder Berechtigungen nur, wenn Ihre App dies erfordert. 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) User.Invite.All Directory.ReadWrite.All, User.ReadWrite.All
Delegiert (persönliches Microsoft-Konto) Nicht unterstützt Nicht unterstützt
Anwendung User.Invite.All Directory.ReadWrite.All, User.ReadWrite.All

Wichtig

In delegierten Szenarien mit Geschäfts-, Schul- oder Unikonten muss dem angemeldeten Benutzer eine unterstützte Microsoft Entra Rolle oder eine benutzerdefinierte Rolle mit einer unterstützten Rollenberechtigung zugewiesen werden. Für diesen Vorgang werden die folgenden Rollen mit den geringsten Berechtigungen unterstützt:

  • So laden Sie Gäste ein:
    • Sowohl Benutzer ohne Administratormitglied als auch Gastbenutzer können Gäste einladen, wenn der Mandantenadministrator die Standardbenutzerberechtigungen nicht eingeschränkt hat.
    • Gastladende, Verzeichnisautoren oder Benutzeradministrator.
  • So setzen Sie die einlöse status zurück: Helpdeskadministrator oder Benutzeradministrator.
  • Anwendungsberechtigungen (nur App) funktionieren nicht, wenn B2B-Einladungen auf dem Mandanten deaktiviert sind oder B2B-Einladungen auf Administratoren beschränkt sind.
  • Beim Zurücksetzen des Einlösungs-status für einen Gastbenutzer ist die Berechtigung User.ReadWrite.All die Berechtigung mit den geringsten Berechtigungen für den Vorgang.

HTTP-Anforderung

POST /invitations

Anforderungsheader

Kopfzeile Wert
Authorization Bearer {token}. Erforderlich. Erfahren Sie mehr über Authentifizierung und Autorisierung.
Content-Type application/json

Anforderungstext

Geben Sie im Anforderungstext eine JSON-Darstellung eines invitation-Objekts an.

In der folgenden Tabelle sind die Parameter aufgeführt, die beim Erstellen einer Einladung erforderlich sind.

Parameter Typ Beschreibung
invitedUserEmailAddress string Die E-Mail-Adresse des Benutzers, den Sie einladen.
inviteRedirectUrl string Die URL, zu der der Benutzer nach der Einlösung umgeleitet wird.

Antwort

Bei erfolgreicher Ausführung gibt die Methode den Antwortcode und ein Einladungsobjekt im Antworttext zurück201 Created.

Beispiel

Beispiel 1: Einladen eines Gastbenutzers

Anforderung

Das folgende Beispiel zeigt eine Anforderung zum Hinzufügen und Einladen eines Gastbenutzers.

POST https://graph.microsoft.com/v1.0/invitations
Content-type: application/json

{
  "invitedUserEmailAddress": "admin@fabrikam.com",
  "inviteRedirectUrl": "https://myapp.contoso.com"
}

Antwort

Das folgende Beispiel zeigt die Antwort.

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

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#invitations/$entity",
    "id": "9071bfde-35e0-47d2-a582-d244ab1b4af6",
    "inviteRedeemUrl": "https://login.microsoftonline.com/redeem?rd=https%3a%2f%2finvitations.microsoft.com%2fredeem%...d%26ver%3d2.0",
    "invitedUserDisplayName": null,
    "invitedUserType": "Guest",
    "invitedUserEmailAddress": "admin@fabrikam.com",
    "sendInvitationMessage": false,
    "resetRedemption": false,
    "inviteRedirectUrl": "https://myapp.contoso.com",
    "status": "PendingAcceptance",
    "invitedUserMessageInfo": {
        "messageLanguage": null,
        "customizedMessageBody": null,
        "ccRecipients": [
            {
                "emailAddress": {
                    "name": null,
                    "address": null
                }
            }
        ]
    },
    "invitedUser": {
        "id": "cbb896f9-8306-49d0-b56b-b8e39cd28825"
    }
}

Beispiel 2: Zurücksetzen der einlöse status eines Gastbenutzers

Anforderung

Das folgende Beispiel zeigt eine Anforderung zum Zurücksetzen der Einlösung status eines Gastbenutzers. Die Anforderung ändert die E-Mail-Adresse des Benutzers, behält jedoch seine aktuelle Benutzer-ID bei. Vor dem Ausführen der Anforderung müssen Sie die neue E-Mail-Adresse der eigenschaft otherMails des vorhandenen Gastbenutzerobjekts hinzufügen.

POST https://graph.microsoft.com/v1.0/invitations
Content-type: application/json

{
    "invitedUserEmailAddress": "AdeleV@fabrikam.com",
    "inviteRedirectUrl": "https://myapp.contoso.com",
    "invitedUser": {
        "id": "264e6d50-eaec-461e-b187-873b1bcf855f"
    },
    "resetRedemption": true
}

Antwort

Das folgende Beispiel zeigt die Antwort.

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

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#invitations/$entity",
    "id": "46d72876-dba6-4a05-b9ec-118faf16c4b7",
    "inviteRedeemUrl": "https://login.microsoftonline.com/redeem?rd=https%3a%2f%2finvitations.microsoft.com%2fredeem%2f%3fte...3d2.0",
    "invitedUserDisplayName": null,
    "invitedUserType": "Guest",
    "invitedUserEmailAddress": "AdeleV@fabrikam.com",
    "sendInvitationMessage": false,
    "resetRedemption": true,
    "inviteRedirectUrl": "https://myapp.contoso.com",
    "status": "PendingAcceptance",
    "invitedUserMessageInfo": {
        "messageLanguage": null,
        "customizedMessageBody": null,
        "ccRecipients": [
            {
                "emailAddress": {
                    "name": null,
                    "address": null
                }
            }
        ]
    },
    "invitedUser": {
        "id": "264e6d50-eaec-461e-b187-873b1bcf855f"
    }
}