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.
Senden einer Freigabeeinladung für ein driveItem. Eine Freigabeeinladung gewährt den Empfängern Berechtigungen und sendet ihnen optional eine E-Mail, um sie darüber zu informieren, dass das Element geteilt wurde.
Wichtig
- Berechtigungen können auf dem StammlaufwerkElement der Laufwerke mit dem Laufwerktyp (
personal OneDrive für Privat) nicht erstellt oder geändert werden.
-
Neue Gäste können nicht mit dem reinen App-Zugriff eingeladen werden. Vorhandene Gäste können über Nur-App-Anfragen eingeladen werden.
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) |
Files.ReadWrite |
Files.ReadWrite.All, Sites.ReadWrite.All |
| Delegiert (persönliches Microsoft-Konto) |
Files.ReadWrite |
Files.ReadWrite.All |
| Anwendung |
Files.ReadWrite.All |
Sites.ReadWrite.All |
Hinweis
SharePoint Embedded benötigt die FileStorageContainer.Selected Berechtigung für den Zugriff auf den Inhalt des Containers. Diese Berechtigung unterscheidet sich von den zuvor erwähnten. Zusätzlich zu den Microsoft Graph-Berechtigungen muss Ihre App über die erforderlichen Containertypberechtigungen verfügen, um diese API aufzurufen. Weitere Informationen finden Sie unter SharePoint Embedded-Authentifizierung und -Autorisierung.
HTTP-Anforderung
POST /drives/{drive-id}/items/{item-id}/invite
POST /groups/{group-id}/drive/items/{item-id}/invite
POST /me/drive/items/{item-id}/invite
POST /sites/{siteId}/drive/items/{itemId}/invite
POST /users/{userId}/drive/items/{itemId}/invite
Anforderungstext
Geben Sie im Anforderungstext ein JSON-Objekt mit den folgenden Parametern an.
{
"requireSignIn": false,
"sendInvitation": false,
"roles": [ "read | write"],
"recipients": [
{ "@odata.type": "microsoft.graph.driveRecipient" },
{ "@odata.type": "microsoft.graph.driveRecipient" }
],
"message": "string"
}
| Parameter |
Typ |
Beschreibung |
| recipients |
driveRecipient collection |
Eine Sammlung von Empfängern, die Zugriff und die Freigabeeinladung erhalten. |
| message |
String |
Eine formatierte Nur-Text-Nachricht, die in der Freigabeeinladung enthalten ist. Maximale Länge: 2.000 Zeichen. |
| requireSignIn |
Boolean |
Gibt an, ob der Empfänger der Einladung sich anmelden muss, um auf das freigegebene Element zuzugreifen. |
| sendInvitation |
Boolescher Wert |
Gibt an, ob eine E-Mail oder ein Beitrag generiert wird (false) oder ob die Berechtigung kürzlich erstellt wurde (true). |
| roles |
Zeichenfolgenauflistung |
Gibt die Rollen an, die den Empfängern der Freigabeeinladung zugewiesen sind. |
| expirationDateTime |
DateTimeOffset |
Gibt die dateTime-Zeit an, nach der die Berechtigung abläuft. Für OneDrive für den Arbeitsplatz oder die Schule/Universität und SharePoint gilt expirationDateTime nur für sharingLink-Berechtigungen . Verfügbar für OneDrive für Geschäfts-, Schul- oder Unikonten, SharePoint und persönliche Premium-OneDrive-Konten. |
| password |
String |
Das Kennwort, das der Ersteller für die Einladung festgelegt hat. Optional und nur OneDrive für zuhause. |
| retainInheritedPermissions |
Boolescher Wert |
Optional. Wenn true (Standard), bleiben alle vorhandenen geerbten Berechtigungen für das freigegebene Element erhalten, wenn dieses Element zum ersten Mal freigegeben wird. If false, werden bei der ersten Freigabe alle vorhandenen Berechtigungen entfernt. Nicht unterstützt mit SharePoint Embedded. |
Antwort
Bei erfolgreicher Ausführung gibt diese Methode einen 200 OK Antwortcode und eine Auflistung von Berechtigungsobjekten im Antworttext zurück.
Weitere Informationen zur Rückgabe von Fehlern finden Sie unter Fehlerantworten.
Teilweise Erfolgsantwort
Beim Einladen mehrerer Empfänger kann die Benachrichtigung für einige erfolgreich sein und für andere fehlschlagen. In diesem Fall gibt der Dienst eine Teilerfolgsmeldung mit einem 207 Multi-Status Status zurück. Wenn ein teilweiser Erfolg zurückgegeben wird, enthält die Antwort für jeden fehlgeschlagenen Empfänger ein Fehlerobjekt mit Informationen darüber, was schief gelaufen ist und wie es behoben werden kann. Weitere Informationen finden Sie unter Beispiel 2.
Fehler beim Senden von Einladungsbenachrichtigungen
Die folgende Tabelle zeigt einige andere Fehler, die in Ihrer App innerhalb der verschachtelten innererror-Objekte auftreten können, wenn das Senden einer Benachrichtigung fehlschlägt. Apps sind nicht erforderlich, um diese Fehler zu behandeln.
| Code |
Beschreibung |
| accountVerificationRequired |
Die Kontoüberprüfung ist erforderlich, um das Senden von Benachrichtigungen freizugeben. |
| hipCheckRequired |
Need to solve HIP (Host Intrusion Prevention) check to unlock block sending notifications. |
| exchangeInvalidUser |
Das Postfach des aktuellen Benutzers wurde nicht gefunden. |
| exchangeOutOfMailboxQuota |
Außerhalb des Kontingents. |
| exchangeMaxRecipients |
Die maximale Anzahl von Empfängern, die gleichzeitig benachrichtigt werden können, wurde überschritten. |
Hinweis: Der Dienst kann jederzeit neue Fehlercodes hinzufügen oder die Rückgabe alter Fehlercodes beenden.
Beispiele
Beispiel 1: Senden einer Freigabeeinladung
Im folgenden Beispiel wird gezeigt, wie Sie eine Freigabeeinladung an einen Benutzer mit der E-Mail-Adresse robin@contoso.orgsenden, einschließlich einer Nachricht zu einer Datei, die zur Zusammenarbeit verwendet wird. Die Einladung gewährt Robin Lese-/Schreibzugriff auf die Datei.
Anforderung
Das folgende Beispiel zeigt eine Anfrage.
POST https://graph.microsoft.com/beta/me/drive/items/{item-id}/invite
Content-type: application/json
{
"recipients": [
{
"email": "robin@contoso.org"
}
],
"message": "Here's the file that we're collaborating on.",
"requireSignIn": true,
"sendInvitation": true,
"roles": [ "write" ],
"password": "password123",
"expirationDateTime": "2018-07-15T14:00:00.000Z"
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Beta.Drives.Item.Items.Item.Invite;
using Microsoft.Graph.Beta.Models;
var requestBody = new InvitePostRequestBody
{
Recipients = new List<DriveRecipient>
{
new DriveRecipient
{
Email = "robin@contoso.org",
},
},
Message = "Here's the file that we're collaborating on.",
RequireSignIn = true,
SendInvitation = true,
Roles = new List<string>
{
"write",
},
Password = "password123",
ExpirationDateTime = "2018-07-15T14:00:00.000Z",
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Items["{driveItem-id}"].Invite.PostAsInvitePostResponseAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphdrives "github.com/microsoftgraph/msgraph-beta-sdk-go/drives"
graphmodels "github.com/microsoftgraph/msgraph-beta-sdk-go/models"
//other-imports
)
requestBody := graphdrives.NewInvitePostRequestBody()
driveRecipient := graphmodels.NewDriveRecipient()
email := "robin@contoso.org"
driveRecipient.SetEmail(&email)
recipients := []graphmodels.DriveRecipientable {
driveRecipient,
}
requestBody.SetRecipients(recipients)
message := "Here's the file that we're collaborating on."
requestBody.SetMessage(&message)
requireSignIn := true
requestBody.SetRequireSignIn(&requireSignIn)
sendInvitation := true
requestBody.SetSendInvitation(&sendInvitation)
roles := []string {
"write",
}
requestBody.SetRoles(roles)
password := "password123"
requestBody.SetPassword(&password)
expirationDateTime := "2018-07-15T14:00:00.000Z"
requestBody.SetExpirationDateTime(&expirationDateTime)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
invite, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").Invite().PostAsInvitePostResponse(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
com.microsoft.graph.beta.drives.item.items.item.invite.InvitePostRequestBody invitePostRequestBody = new com.microsoft.graph.beta.drives.item.items.item.invite.InvitePostRequestBody();
LinkedList<DriveRecipient> recipients = new LinkedList<DriveRecipient>();
DriveRecipient driveRecipient = new DriveRecipient();
driveRecipient.setEmail("robin@contoso.org");
recipients.add(driveRecipient);
invitePostRequestBody.setRecipients(recipients);
invitePostRequestBody.setMessage("Here's the file that we're collaborating on.");
invitePostRequestBody.setRequireSignIn(true);
invitePostRequestBody.setSendInvitation(true);
LinkedList<String> roles = new LinkedList<String>();
roles.add("write");
invitePostRequestBody.setRoles(roles);
invitePostRequestBody.setPassword("password123");
invitePostRequestBody.setExpirationDateTime("2018-07-15T14:00:00.000Z");
var result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").invite().post(invitePostRequestBody);
const options = {
authProvider,
};
const client = Client.init(options);
const permission = {
recipients: [
{
email: 'robin@contoso.org'
}
],
message: 'Here\'s the file that we\'re collaborating on.',
requireSignIn: true,
sendInvitation: true,
roles: [ 'write' ],
password: 'password123',
expirationDateTime: '2018-07-15T14:00:00.000Z'
};
await client.api('/me/drive/items/{item-id}/invite')
.version('beta')
.post(permission);
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Drives\Item\Items\Item\Invite\InvitePostRequestBody;
use Microsoft\Graph\Beta\Generated\Models\DriveRecipient;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new InvitePostRequestBody();
$recipientsDriveRecipient1 = new DriveRecipient();
$recipientsDriveRecipient1->setEmail('robin@contoso.org');
$recipientsArray []= $recipientsDriveRecipient1;
$requestBody->setRecipients($recipientsArray);
$requestBody->setMessage('Here\'s the file that we\'re collaborating on.');
$requestBody->setRequireSignIn(true);
$requestBody->setSendInvitation(true);
$requestBody->setRoles(['write', ]);
$requestBody->setPassword('password123');
$requestBody->setExpirationDateTime('2018-07-15T14:00:00.000Z');
$result = $graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->invite()->post($requestBody)->wait();
Import-Module Microsoft.Graph.Beta.Files
$params = @{
recipients = @(
@{
email = "robin@contoso.org"
}
)
message = "Here's the file that we're collaborating on."
requireSignIn = $true
sendInvitation = $true
roles = @(
"write"
)
password = "password123"
expirationDateTime = "2018-07-15T14:00:00.000Z"
}
Invoke-MgBetaInviteDriveItem -DriveId $driveId -DriveItemId $driveItemId -BodyParameter $params
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.drives.item.items.item.invite.invite_post_request_body import InvitePostRequestBody
from msgraph_beta.generated.models.drive_recipient import DriveRecipient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = InvitePostRequestBody(
recipients = [
DriveRecipient(
email = "robin@contoso.org",
),
],
message = "Here's the file that we're collaborating on.",
require_sign_in = True,
send_invitation = True,
roles = [
"write",
],
password = "password123",
expiration_date_time = "2018-07-15T14:00:00.000Z",
)
result = await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').invite.post(request_body)
Antwort
Das folgende Beispiel zeigt die Antwort.
HTTP/1.1 200 OK
Content-type: application/json
{
"value": [
{
"@deprecated.GrantedTo": "GrantedTo has been deprecated. Refer to GrantedToV2",
"grantedTo": {
"user": {
"displayName": "Robin Danielsen",
"id": "42F177F1-22C0-4BE3-900D-4507125C5C20"
}
},
"grantedToV2": {
"user": {
"id": "42F177F1-22C0-4BE3-900D-4507125C5C20",
"displayName": "Robin Danielsen"
},
"siteUser": {
"id": "1",
"displayName": "Robin Danielsen",
"loginName": "Robin Danielsen"
}
},
"hasPassword": true,
"id": "CCFC7CA3-7A19-4D57-8CEF-149DB9DDFA62",
"invitation": {
"email": "robin@contoso.com",
"signInRequired": true
},
"roles": [ "write" ],
"expirationDateTime": "2018-07-15T14:00:00.000Z"
}
]
}
Beispiel 2: Freigabeeinladung mit Teilerfolg senden
Das folgende Beispiel zeigt eine Anforderung, die teilweise erfolgreich ist.
Anforderung
Das folgende Beispiel zeigt eine Anfrage.
POST https://graph.microsoft.com/beta/me/drive/items/{item-id}/invite
Content-type: application/json
{
"recipients": [
{
"email": "helga@contoso.com"
},
{
"email": "robin@contoso.org"
}
],
"message": "Here's the file that we're collaborating on.",
"requireSignIn": true,
"sendInvitation": true,
"roles": [ "write" ],
"password": "password123",
"expirationDateTime": "2018-07-15T14:00:00.000Z"
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Beta.Drives.Item.Items.Item.Invite;
using Microsoft.Graph.Beta.Models;
var requestBody = new InvitePostRequestBody
{
Recipients = new List<DriveRecipient>
{
new DriveRecipient
{
Email = "helga@contoso.com",
},
new DriveRecipient
{
Email = "robin@contoso.org",
},
},
Message = "Here's the file that we're collaborating on.",
RequireSignIn = true,
SendInvitation = true,
Roles = new List<string>
{
"write",
},
Password = "password123",
ExpirationDateTime = "2018-07-15T14:00:00.000Z",
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Items["{driveItem-id}"].Invite.PostAsInvitePostResponseAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphdrives "github.com/microsoftgraph/msgraph-beta-sdk-go/drives"
graphmodels "github.com/microsoftgraph/msgraph-beta-sdk-go/models"
//other-imports
)
requestBody := graphdrives.NewInvitePostRequestBody()
driveRecipient := graphmodels.NewDriveRecipient()
email := "helga@contoso.com"
driveRecipient.SetEmail(&email)
driveRecipient1 := graphmodels.NewDriveRecipient()
email := "robin@contoso.org"
driveRecipient1.SetEmail(&email)
recipients := []graphmodels.DriveRecipientable {
driveRecipient,
driveRecipient1,
}
requestBody.SetRecipients(recipients)
message := "Here's the file that we're collaborating on."
requestBody.SetMessage(&message)
requireSignIn := true
requestBody.SetRequireSignIn(&requireSignIn)
sendInvitation := true
requestBody.SetSendInvitation(&sendInvitation)
roles := []string {
"write",
}
requestBody.SetRoles(roles)
password := "password123"
requestBody.SetPassword(&password)
expirationDateTime := "2018-07-15T14:00:00.000Z"
requestBody.SetExpirationDateTime(&expirationDateTime)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
invite, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").Invite().PostAsInvitePostResponse(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
com.microsoft.graph.beta.drives.item.items.item.invite.InvitePostRequestBody invitePostRequestBody = new com.microsoft.graph.beta.drives.item.items.item.invite.InvitePostRequestBody();
LinkedList<DriveRecipient> recipients = new LinkedList<DriveRecipient>();
DriveRecipient driveRecipient = new DriveRecipient();
driveRecipient.setEmail("helga@contoso.com");
recipients.add(driveRecipient);
DriveRecipient driveRecipient1 = new DriveRecipient();
driveRecipient1.setEmail("robin@contoso.org");
recipients.add(driveRecipient1);
invitePostRequestBody.setRecipients(recipients);
invitePostRequestBody.setMessage("Here's the file that we're collaborating on.");
invitePostRequestBody.setRequireSignIn(true);
invitePostRequestBody.setSendInvitation(true);
LinkedList<String> roles = new LinkedList<String>();
roles.add("write");
invitePostRequestBody.setRoles(roles);
invitePostRequestBody.setPassword("password123");
invitePostRequestBody.setExpirationDateTime("2018-07-15T14:00:00.000Z");
var result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").invite().post(invitePostRequestBody);
const options = {
authProvider,
};
const client = Client.init(options);
const permission = {
recipients: [
{
email: 'helga@contoso.com'
},
{
email: 'robin@contoso.org'
}
],
message: 'Here\'s the file that we\'re collaborating on.',
requireSignIn: true,
sendInvitation: true,
roles: [ 'write' ],
password: 'password123',
expirationDateTime: '2018-07-15T14:00:00.000Z'
};
await client.api('/me/drive/items/{item-id}/invite')
.version('beta')
.post(permission);
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Drives\Item\Items\Item\Invite\InvitePostRequestBody;
use Microsoft\Graph\Beta\Generated\Models\DriveRecipient;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new InvitePostRequestBody();
$recipientsDriveRecipient1 = new DriveRecipient();
$recipientsDriveRecipient1->setEmail('helga@contoso.com');
$recipientsArray []= $recipientsDriveRecipient1;
$recipientsDriveRecipient2 = new DriveRecipient();
$recipientsDriveRecipient2->setEmail('robin@contoso.org');
$recipientsArray []= $recipientsDriveRecipient2;
$requestBody->setRecipients($recipientsArray);
$requestBody->setMessage('Here\'s the file that we\'re collaborating on.');
$requestBody->setRequireSignIn(true);
$requestBody->setSendInvitation(true);
$requestBody->setRoles(['write', ]);
$requestBody->setPassword('password123');
$requestBody->setExpirationDateTime('2018-07-15T14:00:00.000Z');
$result = $graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->invite()->post($requestBody)->wait();
Import-Module Microsoft.Graph.Beta.Files
$params = @{
recipients = @(
@{
email = "helga@contoso.com"
}
@{
email = "robin@contoso.org"
}
)
message = "Here's the file that we're collaborating on."
requireSignIn = $true
sendInvitation = $true
roles = @(
"write"
)
password = "password123"
expirationDateTime = "2018-07-15T14:00:00.000Z"
}
Invoke-MgBetaInviteDriveItem -DriveId $driveId -DriveItemId $driveItemId -BodyParameter $params
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.drives.item.items.item.invite.invite_post_request_body import InvitePostRequestBody
from msgraph_beta.generated.models.drive_recipient import DriveRecipient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = InvitePostRequestBody(
recipients = [
DriveRecipient(
email = "helga@contoso.com",
),
DriveRecipient(
email = "robin@contoso.org",
),
],
message = "Here's the file that we're collaborating on.",
require_sign_in = True,
send_invitation = True,
roles = [
"write",
],
password = "password123",
expiration_date_time = "2018-07-15T14:00:00.000Z",
)
result = await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').invite.post(request_body)
Antwort
Das folgende Beispiel zeigt die Teilantwort.
HTTP/1.1 207 Multi-Status
Content-type: application/json
{
"value": [
{
"grantedTo": {
"user": {
"displayName": "Helga Hammeren",
"id": "5D8CA5D0-FFF8-4A97-B0A6-8F5AEA339681"
}
},
"id": "1EFG7CA3-7A19-4D57-8CEF-149DB9DDFA62",
"invitation": {
"email": "helga@contoso.com",
"signInRequired": true
},
"roles": [ "write" ],
"error": {
"code":"notAllowed",
"message":"Account verification needed to unblock sending emails.",
"localizedMessage": "Kontobestätigung erforderlich, um das Senden von E-Mails zu entsperren.",
"fixItUrl":"http://g.live.com/8SESkydrive/VerifyAccount",
"innererror":{
"code":"accountVerificationRequired"
}
}
},
{
"grantedTo": {
"user": {
"displayName": "Robin Danielsen",
"id": "42F177F1-22C0-4BE3-900D-4507125C5C20"
}
},
"id": "CCFC7CA3-7A19-4D57-8CEF-149DB9DDFA62",
"invitation": {
"email": "robin@contoso.com",
"signInRequired": true
},
"roles": [ "write" ],
"expirationDateTime": "2018-07-15T14:00:00.000Z"
}
]
}
Verwandte Inhalte
Eine Liste der verfügbaren Rollen finden Sie unter Rollen-Eigenschaftswerte.