Senden einer Einladung zum Zugriff auf ein Element - Microsoft Graph beta

Artikel
12/01/2021
6 Minuten Lesedauer

Namespace: microsoft.graph

Wichtig

APIs unter der /beta Version in Microsoft Graph können geändert werden. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt. Um festzustellen, ob eine API in Version 1.0 verfügbar ist, verwenden Sie die Versionsauswahl .

Sendet eine Freigabeeinladung für ein DriveItem-Element. Eine Freigabeeinladung stellt Berechtigungen für Empfänger bereit und sendet optional eine E-Mail-Nachricht an den Empfänger, um diesen über die Freigabe in Kenntnis zu setzen.

Berechtigungen

Eine der nachfolgenden Berechtigungen ist erforderlich, um diese API aufrufen zu können. Weitere Informationen, unter anderem zur Auswahl von Berechtigungen, finden Sie im Artikel zum Thema Berechtigungen.

Berechtigungstyp	Berechtigungen (von der Berechtigung mit den wenigsten Rechten zu der mit den meisten Rechten)
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

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	Collection(DriveRecipient)	Eine Sammlung der Empfänger, die Zugriff und die Freigabeeinladung erhalten.
message	String	Eine formatierte Nur-Text-Nachricht, die in der Freigabeeinladung enthalten ist. Die maximale Länge beträgt 2000 Zeichen.
requireSignIn	Boolescher Wert	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 (falsch) oder ob nur die Berechtigung erstellt (true) wurde.
roles	Collection(String)	Gibt die Rollen an, die den Empfängern der Freigabeeinladung erteilt werden.
expirationDateTime	DateTimeOffset	Geben Sie DateTime an, nach dem die Berechtigung abläuft. Verfügbar für OneDrive for Business-, SharePoint- und Premium-konten für persönliche OneDrive.
password	String	Das Kennwort, das für die Einladung des Erstellers festgelegt wurde. Nur optional und OneDrive Persönlich

Beispiel

In diesem Beispiel wird eine Einladung zur Freigabe an einen Benutzer mit der E-Mail-Adresse "ryan@contoso.org" versandt, in der dieser über eine Datei für die Zusammenarbeit benachrichtigt wird. Die Einladung gewährt Ryan Lese-/ Schreibzugriff auf die Datei.

HTTP-Anforderung

Wenn die Methode erfolgreich verläuft, werden der Antwortcode 200 OK und das permission-Sammlungsobjekt im Antworttext zurückgegeben.

POST /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"
}


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var recipients = new List<DriveRecipient>()
{
    new DriveRecipient
    {
        Email = "robin@contoso.org"
    }
};

var message = "Here's the file that we're collaborating on.";

var requireSignIn = true;

var sendInvitation = true;

var roles = new List<String>()
{
    "write"
};

var password = "password123";

var expirationDateTime = "2018-07-15T14:00:00Z";

await graphClient.Me.Drive.Items["{driveItem-id}"]
    .Invite(recipients,requireSignIn,roles,sendInvitation,message,null,expirationDateTime,password)
    .Request()
    .PostAsync();

Wichtig

Microsoft Graph SDKs verwenden standardmäßig die Version 1.0 der API und unterstützen nicht alle Typen, Eigenschaften und APIs, die in der Betaversion verfügbar sind. Ausführliche Informationen zum Zugreifen auf die Beta-API mit dem SDK finden Sie unter Verwenden der Microsoft Graph-SDKs mit der Beta-API.

Ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider-Instanz finden Sie in der SDK-Dokumentation.


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

Wichtig

Ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider-Instanz finden Sie in der SDK-Dokumentation.


MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/beta/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/me/drive/items/{item-id}/invite"]]];
[urlRequest setHTTPMethod:@"POST"];
[urlRequest setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];

NSMutableDictionary *payloadDictionary = [[NSMutableDictionary alloc] init];

NSMutableArray *recipientsList = [[NSMutableArray alloc] init];
MSGraphDriveRecipient *recipients = [[MSGraphDriveRecipient alloc] init];
[recipients setEmail:@"robin@contoso.org"];
[recipientsList addObject: recipients];
payloadDictionary[@"recipients"] = recipientsList;

NSString *message = @"Here's the file that we're collaborating on.";
payloadDictionary[@"message"] = message;

BOOL requireSignIn = YES;
payloadDictionary[@"requireSignIn"] = requireSignIn;

BOOL sendInvitation = YES;
payloadDictionary[@"sendInvitation"] = sendInvitation;

NSMutableArray *rolesList = [[NSMutableArray alloc] init];
[rolesList addObject: @"write"];
payloadDictionary[@"roles"] = rolesList;

NSString *password = @"password123";
payloadDictionary[@"password"] = password;

NSString *expirationDateTimeDateTimeString = @"07/15/2018 14:00:00";
NSDate *expirationDateTime = [NSDate ms_dateFromString: expirationDateTimeDateTimeString];
payloadDictionary[@"expirationDateTime"] = expirationDateTime;

NSData *data = [NSJSONSerialization dataWithJSONObject:payloadDictionary options:kNilOptions error:&error];
[urlRequest setHTTPBody:data];

MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest 
    completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

        //Request Completed

}];

[meDataTask execute];

Wichtig

Ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider-Instanz finden Sie in der SDK-Dokumentation.


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

LinkedList<DriveRecipient> recipientsList = new LinkedList<DriveRecipient>();
DriveRecipient recipients = new DriveRecipient();
recipients.email = "robin@contoso.org";

recipientsList.add(recipients);

String message = "Here's the file that we're collaborating on.";

Boolean requireSignIn = true;

Boolean sendInvitation = true;

LinkedList<String> rolesList = new LinkedList<String>();
rolesList.add("write");

String password = "password123";

String expirationDateTime = "07/15/2018 14:00:00";

graphClient.me().drive().items("{item-id}")
    .invite(DriveItemInviteParameterSet
        .newBuilder()
        .withRequireSignIn(requireSignIn)
        .withRoles(rolesList)
        .withSendInvitation(sendInvitation)
        .withMessage(message)
        .withRecipients(recipientsList)
        .withRetainInheritedPermissions(null)
        .withExpirationDateTime(expirationDateTime)
        .withPassword(password)
        .build())
    .buildRequest()
    .post();

Wichtig

Ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider-Instanz finden Sie in der SDK-Dokumentation.

Antwort

Nachfolgend sehen Sie ein Beispiel der 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"
    }
  ]
}

Partielle Erfolgsantwort

Beim Einladen mehrerer Empfänger ist es möglich, dass die Benachrichtigung für einige erfolgreich ist und für andere fehlschlägt. In diesem Fall gibt der Dienst eine Teilweise-Erfolgsantwort mit dem HTTP-Statuscode 207 zurück. Wenn ein Teilerfolg zurückgegeben wird, enthält die Antwort für jeden fehlgeschlagenen Empfänger ein error Objekt mit Informationen dazu, was schief gelaufen ist und wie es behoben werden kann.

Nachfolgend sehen Sie ein Beispiel für die partielle Antwort.

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"
    }
  ]
}

SendNotification-Fehler

Im Folgenden finden Sie einige zusätzliche Fehler, auf die Ihre App innerhalb der geschachtelten Objekte stoßen innererror kann, wenn das Senden von Benachrichtigungen fehlschlägt. Apps müssen diese nicht verarbeiten.

Code	Beschreibung
accountVerificationRequired	Die Kontoüberprüfung ist erforderlich, um das Senden von Benachrichtigungen aufzuheben.
hipCheckRequired	Sie müssen die HIP-Prüfung (Host Intrusion Prevention) lösen, um das Senden von Benachrichtigungen zu entsperren.
exchangeInvalidUser	Das Postfach des aktuellen Benutzers wurde nicht gefunden.
exchangeOutOfMailboxQuota	Außerhalb des Kontingents.
exchangeMaxRecipients	Die maximale Anzahl von Empfängern, die gleichzeitig Benachrichtigungen gesendet werden können, wurde überschritten.

Hinweis: Der Dienst kann jederzeit neue Fehlercodes hinzufügen oder die Rückgabe alter Fehlercodes beenden.

Hinweise

Laufwerke mit dem driveTypepersonal (OneDrive Personal) können keine Berechtigungen am Stamm-DriveItem erstellen oder ändern.
Eine Liste der verfügbaren Rollen finden Sie unter Rolleneigenschaftenwerte.

Fehlerantworten

Weitere Informationen dazu, wie Fehler zurückgegeben werden, finden Sie im Thema Fehlerantworten.

Freigabeeinladung senden

Berechtigungen

HTTP-Anforderung

Anforderungstext

Beispiel

HTTP-Anforderung

Antwort

Partielle Erfolgsantwort

SendNotification-Fehler

Hinweise

Fehlerantworten

Feedback