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:
- 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.
- Wenn der Benutzer eingeladen wird, wird eine Benutzerentität ( userType
Guest
) 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"
}
}