Einladung erstellen

Namespace: microsoft.graph

Verwenden Sie diese API zum Erstellen einer neuen Einladung. „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.

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

Anforderung

Das folgende Beispiel zeigt eine Anfrage.

HTTP

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

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

C#

// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Models;

var requestBody = new Invitation
{
	InvitedUserEmailAddress = "admin@fabrikam.com",
	InviteRedirectUrl = "https://myapp.contoso.com",
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Invitations.PostAsync(requestBody);

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc invitations create --body '{\
  "invitedUserEmailAddress": "admin@fabrikam.com",\
  "inviteRedirectUrl": "https://myapp.contoso.com"\
}\
'

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.

Go

import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestBody := graphmodels.NewInvitation()
invitedUserEmailAddress := "admin@fabrikam.com"
requestBody.SetInvitedUserEmailAddress(&invitedUserEmailAddress) 
inviteRedirectUrl := "https://myapp.contoso.com"
requestBody.SetInviteRedirectUrl(&inviteRedirectUrl) 

invitations, err := graphClient.Invitations().Post(context.Background(), requestBody, nil)

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.

Java

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

Invitation invitation = new Invitation();
invitation.setInvitedUserEmailAddress("admin@fabrikam.com");
invitation.setInviteRedirectUrl("https://myapp.contoso.com");
Invitation result = graphClient.invitations().post(invitation);

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

const invitation = {
  invitedUserEmailAddress: 'admin@fabrikam.com',
  inviteRedirectUrl: 'https://myapp.contoso.com'
};

await client.api('/invitations')
	.post(invitation);

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.

PHP

<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\Invitation;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new Invitation();
$requestBody->setInvitedUserEmailAddress('admin@fabrikam.com');
$requestBody->setInviteRedirectUrl('https://myapp.contoso.com');

$result = $graphServiceClient->invitations()->post($requestBody)->wait();

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.

PowerShell

Import-Module Microsoft.Graph.Identity.SignIns

$params = @{
	invitedUserEmailAddress = "admin@fabrikam.com"
	inviteRedirectUrl = "https://myapp.contoso.com"
}

New-MgInvitation -BodyParameter $params

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.

Python

from msgraph import GraphServiceClient
from msgraph.generated.models.invitation import Invitation

graph_client = GraphServiceClient(credentials, scopes)

request_body = Invitation(
	invited_user_email_address = "admin@fabrikam.com",
	invite_redirect_url = "https://myapp.contoso.com",
)

result = await graph_client.invitations.post(request_body)

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.

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%2f%3ftenant%3d69997834-fa40-45da-xxxx-382c3bdc66c3%26user%3d9071bfde-35e0-47d2-a582-d244ab1b4af6%26ticket%3dwCFIFW%25252frzl2A%25252fpZFZk5fCLJprpDxtcjR8s%25252fo1QZA0yQ%25253d%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"
    }
}