Envoyer une invitation de partage

  • Article

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 .

Envoie une invitation de partage pour un driveItem. Une invitation de partage fournit des autorisations aux destinataires et envoie en option un e-mail aux destinataires afin de les informer que l’élément a été partagé.

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

Service global Gouvernement des États-Unis L4 Us Government L5 (DOD) Chine gérée par 21Vianet
✅ ✅ ✅ ✅

Autorisations

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

Type d’autorisation Autorisations avec privilèges minimum Autorisations privilégiées plus élevées
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

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 Collection(driveRecipient) 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 Spécifie si un e-mail ou une publication est généré (false) ou si l’autorisation a été créée récemment (true).
roles Collection(String) Spécifie les rôles accordés aux destinataires de l’invitation de partage.
expirationDateTime DateTimeOffset Spécifie la dateTime après laquelle l’autorisation expire. Pour OneDrive Entreprise et SharePoint, xpirationDateTime s’applique uniquement aux autorisations sharingLink. Disponible sur les comptes OneDrive personnels OneDrive Entreprise, SharePoint et Premium.
mot de passe Chaîne Mot de passe défini sur l’invitation par le créateur. Facultatif et OneDrive Personnel uniquement
retainInheritedPermissions Boolean Facultatif. Si true la valeur est (valeur 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 la valeur est false, toutes les autorisations existantes sont supprimées lors du premier partage.

Exemple

Cet exemple envoie une invitation de partage à un utilisateur avec l’adresse e-mail «ryan@contoso.org » avec un message concernant un fichier en cours de collaboration. L’invitation donne à Ryan un accès au fichier en lecture/écriture.

Requête HTTP

Si elle réussit, cette méthode renvoie un code de réponse 200 OK et un objet de collection permission dans le corps de la réponse.

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

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 de status HTTP de 207. Lorsque la réussite partielle est retournée, la réponse de chaque destinataire ayant échoué contient un objet avec des error informations sur ce qui s’est produit et sur la façon de le corriger.

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

Erreurs SendNotification

Voici d’autres erreurs que votre application peut rencontrer dans les objets imbriqués innererror en cas d’échec de l’envoi d’une 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 Vous devez résoudre les 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 qui peuvent être envoyés des notifications en même temps.

Note: Le service peut ajouter de nouveaux codes d’erreur ou arrêter de retourner les anciens à tout moment.

Remarques

  • Les lecteurs dont le type depersonal lecteur est (OneDrive personnel) ne peuvent pas créer ou modifier des autorisations sur l’élément DriveItem racine.
  • Pour obtenir la liste des rôles disponibles, consultez Valeurs des propriétés de rôles.

Réponses d’erreur

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