Freigeben über


Freigabeeinladung senden

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.

Sendet eine Freigabe-Einladung für ein driveItem-Objekt. 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.

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) 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 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 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 Collection(String) Gibt die Rollen an, die den Empfängern der Freigabeaufladung gewährt werden.
expirationDateTime DateTimeOffset Gibt den dateTime-Wert an, nach dem die Berechtigung abläuft. Für OneDrive for Business und SharePoint gilt xpirationDateTime nur für sharingLink-Berechtigungen. Verfügbar für OneDrive for Business-, SharePoint- und Premium-Persönliche OneDrive-Konten.
password String Das Kennwort, das der Ersteller für die Einladung festgelegt hat. Optional und Nur OneDrive Personal
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.

Beispiel

In diesem Beispiel wird eine Freigabeeinladung an einen Benutzer mit der E-Mail-Adresse "ryan@contoso.org" mit einer Nachricht über eine Datei gesendet, an der mitgearbeitet 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 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"
}

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

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 dem HTTP-status Code 207 zurück. Wenn ein Teilerfolg zurückgegeben wird, enthält die Antwort für jeden fehlgeschlagenen Empfänger ein error -Objekt mit Informationen darüber, was schiefgelaufen ist und wie es behoben werden kann.

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

SendNotification-Fehler

Im Folgenden sind einige weitere Fehler aufgeführt, die bei der App innerhalb der geschachtelten 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 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.

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

Bemerkungen

  • Laufwerke mit dem driveType -Wert personal (OneDrive personal) können keine Berechtigungen für das DriveItem-Stammelement 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 .