driveItem : inviter

Espace de noms: microsoft.graph

Importante

Les API sous la version /beta dans Microsoft Graph sont susceptibles d’être modifiées. L’utilisation de ces API dans des applications de production n’est pas prise en charge. Pour déterminer si une API est disponible dans v1.0, utilisez le sélecteur Version .

Envoyez une invitation de partage pour un élément de lecteur. Une invitation de partage fournit des autorisations aux destinataires et, éventuellement, leur envoie un e-mail pour les informer que l’élément a été partagé.

Importante

  • Les autorisations ne peuvent pas être créées ou modifiées sur le driveItem racine des lecteurs dont le driveType est ( personal OneDrive pour les particuliers).
  • Les nouveaux invités ne peuvent pas être invités à l’aide de l’accès de l’application uniquement. Les invités existants peuvent être invités à l’aide de demandes d’application uniquement.

Cette API est disponible dans les déploiements cloud nationaux suivants.

Service global Gouvernement américain L4 Gouvernement américain L5 (DOD) Chine exploitée par 21Vianet
✅ ✅ ✅ ✅

Autorisations

Choisissez l’autorisation ou les autorisations marquées comme étant les moins privilégiées pour cette API. Utilisez une ou plusieurs autorisations privilégiées uniquement si votre application en a besoin. Pour plus d’informations sur les autorisations déléguées et d’application, voir Types d’autorisations. Pour en savoir plus sur ces autorisations, consultez la référence des autorisations.

Type d’autorisation Autorisations les moins privilégiées Autorisations à privilèges plus élevés
Déléguée (compte professionnel ou scolaire) Files.ReadWrite Files.ReadWrite.All, Sites.ReadWrite.All
Déléguée (compte Microsoft personnel) Files.ReadWrite Files.ReadWrite.All
Application Files.ReadWrite.All Sites.ReadWrite.All

Remarque

SharePoint Embedded nécessite l’autorisation FileStorageContainer.Selected pour accéder au contenu du conteneur. Cette autorisation est différente de celles mentionnées précédemment. Outre les autorisations Microsoft Graph, votre application doit disposer des autorisations de type conteneur nécessaires pour appeler cette API. Pour plus d’informations, consultez Authentification et autorisation SharePoint Embedded.

Requête HTTP

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

Corps de la demande

Dans le corps de la demande, indiquez un objet JSON avec les paramètres suivants.

{
  "requireSignIn": false,
  "sendInvitation": false,
  "roles": [ "read | write"],
  "recipients": [
    { "@odata.type": "microsoft.graph.driveRecipient" },
    { "@odata.type": "microsoft.graph.driveRecipient" }
  ],
  "message": "string"
}
Paramètre Type Description
destinataires collecte driveRecipient Une collection de destinataires qui reçoivent l’accès et l’invitation de partage.
message String Un message au format texte brut qui est inclus dans l’invitation de partage. Longueur maximale : 2 000 caractères.
requireSignIn Booléen Indique l’endroit où le destinataire de l’invitation doit se connecter pour afficher l’élément partagé.
sendInvitation Valeur booléenne Indique si un e-mail ou une publication est généré (false) ou si l’autorisation est récemment créée (true).
roles Collection de chaînes Spécifie les rôles qui sont accordés aux destinataires de l’invitation de partage.
expirationDateTime DateTimeOffset Spécifie la date/heure après laquelle l’autorisation expire. Pour OneDrive professionnel ou scolaire et SharePoint, ExpirationDateTime s’applique uniquement aux autorisations sharingLink . Disponible sur OneDrive professionnel ou scolaire, SharePoint et les comptes OneDrive personnels Premium.
mot de passe Chaîne Le mot de passe défini sur l’invitation par le créateur. facultatif et OneDrive pour les particuliers uniquement.
retainInheritedPermissions Boolean Facultatif. Si true (par défaut), toutes les autorisations héritées existantes sont conservées sur l’élément partagé lors du premier partage de cet élément. Si false, toutes les autorisations existantes sont supprimées lors du premier partage. Non pris en charge avec SharePoint Embedded.

Réponse

En cas de réussite, cette méthode renvoie un 200 OK code de réponse et une collection d’objets d’autorisation dans le corps de la réponse.

Pour plus d’informations sur la façon dont les erreurs sont renvoyées, consultez Réponses d’erreur.

Réponse de réussite partielle

Lorsque vous invitez plusieurs destinataires, il est possible que la notification réussisse pour certains et échoue pour d’autres. Dans ce cas, le service retourne une réponse de réussite partielle avec un code d’status 207 Multi-Status . Lorsqu’un succès partiel est renvoyé, la réponse de chaque destinataire ayant échoué contient un objet d’erreur contenant des informations sur ce qui n’a pas fonctionné et comment le résoudre. Pour plus d’informations, consultez l’exemple 2.

Erreurs d’envoi d’une notification d’invitation

Le tableau suivant présente d’autres erreurs que votre application peut rencontrer dans les objets innererror imbriqués lors de l’échec de l’envoi de la notification. Les applications ne sont pas nécessaires pour gérer ces erreurs.

Code Description
accountVerificationRequired La vérification du compte est nécessaire pour débloquer l’envoi de notifications.
hipCheckRequired Besoin de résoudre la case activée HIP (Host Intrusion Prevention) pour débloquer l’envoi de notifications.
exchangeInvalidUser La boîte aux lettres de l’utilisateur actuel est introuvable.
exchangeOutOfMailboxQuota Hors quota.
exchangeMaxRecipients Dépassement du nombre maximal de destinataires pouvant recevoir des notifications simultanément.

Remarque : Le service peut ajouter de nouveaux codes d’erreur ou cesser de renvoyer les anciens à tout moment.

Exemples

Exemple 1 : envoyer une invitation de partage

L’exemple suivant montre comment envoyer une invitation de partage à un utilisateur avec l’adresse robin@contoso.orge-mail , y compris un message concernant un fichier en collaboration. L’invitation accorde à Robin l’accès en lecture-écriture au fichier.

Demande

L’exemple suivant illustre une demande.

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

Réponse

L’exemple suivant illustre la réponse.

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

Exemple 2 : Envoyer une invitation de partage avec un succès partiel

L’exemple suivant montre une demande qui réussit partiellement.

Demande

L’exemple suivant illustre une demande.

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

Réponse

L’exemple suivant montre la réponse partielle.

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

Pour obtenir la liste des rôles disponibles, voir Valeurs des propriétés des rôles.