Freigeben über


driveItem: invite

Namespace: microsoft.graph

Senden sie eine Freigabeaufladung für ein driveItem-Objekt. Eine Freigabe-Einladung gewährt den Empfängern Berechtigungen und sendet ihnen optional eine E-Mail, um sie darüber zu informieren, dass das Element freigegeben wurde.

Wichtig

  • Berechtigungen können nicht für das StammlaufwerkElement von Laufwerken mit dem driveType ( personal OneDrive home) erstellt oder geändert werden.
  • Neue Gäste können nicht mit Nur-App-Zugriff eingeladen werden. Vorhandene Gäste können mithilfe von Nur-App-Anforderungen 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 erfordert die FileStorageContainer.Selected Berechtigung für den Zugriff auf den Inhalt des Containers. Diese Berechtigung unterscheidet sich von den zuvor erwähnten Berechtigungen. 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

Anforderungsheader

Name Beschreibung
Authorization Bearer {token}. Erforderlich. Erfahren Sie mehr über Authentifizierung und Autorisierung.
Content-Type application/json. Erforderlich.

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-Sammlung Eine Sammlung von Empfängern, die Zugriff und die Freigabe-Einladung erhalten.
message String Eine formatierte Nur-Text-Nachricht, die in der Freigabeeinladung enthalten ist. Maximale Länge von 2.000 Zeichen.
requireSignIn Boolescher Wert Gibt an, ob der Empfänger der Einladung sich anmelden muss, um auf das freigegebene Element zuzugreifen.
sendInvitation Boolescher Wert Bei „wahr“ wird ein Freigabelink an den Empfänger gesendet. Andernfalls wird direkt eine Berechtigung erteilt, ohne dass eine Benachrichtigung gesendet wird.
roles Zeichenfolgenauflistung Gibt die Rollen an, die den Empfängern der Freigabeaufladung gewährt werden sollen.
expirationDateTime DateTimeOffset Gibt den dateTime-Wert an, nach dem die Berechtigung abläuft. Für OneDrive für Arbeit, Schule oder Uni und SharePoint gilt expirationDateTime nur für freigabeLink-Berechtigungen . Verfügbar auf 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 OneDrive nur für die Startseite.
retainInheritedPermissions Boolescher Wert Optional. Wenn true (Standard), werden alle vorhandenen geerbten Berechtigungen für das freigegebene Element beibehalten, wenn dieses Element zum ersten Mal freigegeben wird. Gibt falsean, dass alle vorhandenen Berechtigungen bei der erstmaligen Freigabe entfernt werden.

Antwort

Wenn die Methode erfolgreich verläuft, werden der 200 OK Antwortcode und eine Auflistung von Berechtigungsobjekten im Antworttext zurückgegeben.

Weitere Informationen zur Rückgabe von Fehlern finden Sie unter Fehlerantworten.

Teilweise erfolgreiche Antwort

Wenn Sie mehrere Empfänger einladen, ist es möglich, dass die Benachrichtigung für einige erfolgreich und für andere fehlschlägt. In diesem Fall gibt der Dienst eine partielle Erfolgsantwort mit einem 207 Multi-Status status Code zurück. Wenn ein Teilerfolg zurückgegeben wird, enthält die Antwort für jeden fehlgeschlagenen Empfänger ein Fehlerobjekt mit Informationen darüber, was schiefgelaufen ist und wie es behoben werden kann. Weitere Informationen finden Sie unter Beispiel 2.

Fehler beim Senden von Einladungsbenachrichtigungen

In der folgenden Tabelle sind einige andere Fehler aufgeführt, die ihre App innerhalb der geschachtelten innererror-Objekte auftreten kann, 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 zu entsperren.
hipCheckRequired Sie müssen die HIP-Überprüfung (Host Intrusion Prevention) lösen, um das Senden von Benachrichtigungen zu entsperren.
exchangeInvalidUser Das Postfach des aktuellen Benutzers wurde nicht gefunden.
exchangeOutOfMailboxQuota Das Kontingent ist überschritten.
exchangeMaxRecipients Die maximale Anzahl von Empfängern, die gleichzeitig Benachrichtigungen senden können, wurde überschritten.

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

Beispiele

Beispiel 1: Senden einer Freigabe-Einladung

Das folgende Beispiel zeigt, wie Sie eine Freigabe-Einladung an einen Benutzer mit der E-Mail-Adresse ryan@contoso.comsenden, einschließlich einer Nachricht zu einer Datei im Rahmen der Zusammenarbeit. Die Einladung gewährt Ryan Lese-/ Schreibzugriff auf die Datei.

Anforderung

Das folgende Beispiel zeigt eine Anfrage.

POST https://graph.microsoft.com/v1.0/me/drive/items/{item-id}/invite
Content-type: application/json

{
  "recipients": [
    {
      "email": "ryan@contoso.com"
    }
  ],
  "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"
}

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: Senden einer Freigabeeinladung mit teilweisem Erfolg

Das folgende Beispiel zeigt eine Anforderung, die teilweise erfolgreich ist.

Anforderung

Das folgende Beispiel zeigt eine Anfrage.

POST https://graph.microsoft.com/v1.0/me/drive/items/{item-id}/invite
Content-type: application/json

{
  "recipients": [
    {
      "email": "helga@contoso.com"
    },
    {
      "email": "robin@contoso.com"
    }
  ],
  "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"
}

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

Eine Liste der verfügbaren Rollen finden Sie unter Rolleneigenschaftenwerte.