Freigeben über


Einladung erstellen

Namespace: microsoft.graph

Verwenden Sie diese API, um eine neue Einladung zu erstellen oder den Einlösungsstatus für einen Gastbenutzer zurückzusetzen, der seine Einladung bereits eingelöst hat. „Invitation“ fügt einen externen Benutzer zur Organisation hinzu.

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.

Globaler Dienst US Government L4 US Government L5 (DOD) China, betrieben von 21Vianet

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) 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

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ösungsstatus für einen Gastbenutzer ist die Berechtigung User.ReadWrite.All die Berechtigung mit den geringsten Berechtigungen für den Vorgang.

Für delegierte Szenarien muss der angemeldete Benutzer mindestens über die Microsoft Entra-Rolle"Gasteinladung", "Verzeichnisautor" oder "Benutzeradministrator" verfügen. Um den Einlösungsstatus zurückzusetzen, muss der angemeldete Benutzer mindestens über die Rolle Helpdeskadministrator oder Benutzeradministrator verfügen.

HTTP-Anforderung

POST /invitations

Anforderungsheader

Kopfzeile Wert
Authorization Bearer {token}. Erforderlich. Erfahren Sie mehr über die 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 des Einlösungsstatus eines Gastbenutzers

Anforderung

Das folgende Beispiel zeigt eine Anforderung zum Zurücksetzen des Einlösungsstatus 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"
    }
}