Envoyer une invitation de partage
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 de
personal
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.