driveItem : createLink

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 .

Créer un lien pour partager un élément de lecteur DriveItem.

L’action createLink crée un lien de partage si le type de lien spécifié n’existe pas déjà pour l’application appelante. Si un lien de partage du type spécifié existe déjà pour l’application, le lien de partage existant est renvoyé.

Les ressources DriveItem héritent des autorisations de partage de leurs ancêtres.

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/{driveId}/items/{itemId}/createLink
POST /groups/{groupId}/drive/items/{itemId}/createLink
POST /me/drive/items/{itemId}/createLink
POST /sites/{siteId}/drive/items/{itemId}/createLink
POST /users/{userId}/drive/items/{itemId}/createLink

En-têtes de demande

Nom Description
Autorisation Porteur {token}. Obligatoire. En savoir plus sur l’authentification et les autorisations.
Content-Type application/json. Obligatoire.

Corps de la demande

Le corps de la demande définit les propriétés du lien de partage demandé par votre application. La demande doit être un objet JSON qui possède les propriétés suivantes :

Propriété Type Description
type String Facultatif. Type de lien de partage à créer.
étendue Chaîne Facultatif. Étendue du lien à créer. Soit anonymous, organization, ou users
expirationDateTime DateTimeOffset Facultatif. Une chaîne avec le format aaaa-MM-jjTHH :mm :ssZ de DateTime indique l’heure d’expiration de l’autorisation.
mot de passe Chaîne Facultatif. Le créateur définit le mot de passe du lien de partage.
destinataires collecte driveRecipient Facultatif. Une collection de destinataires qui reçoivent l’accès au lien de partage.
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.
sendNotification Booléen Si true, cette méthode envoie un lien de partage dans un e-mail aux utilisateurs spécifiés dans recipients. Applicable à OneDrive Entreprise ou SharePoint. La valeur par défaut est false. Facultatif.

Vous pouvez utiliser les valeurs suivantes pour le paramètre type.

Valeur du type Description
view Crée un lien en lecture seule vers le driveItem.
la révision Crée un lien de révision vers le driveItem. Cette option est disponible uniquement pour les fichiers dans OneDrive Entreprise et SharePoint.
edit Crée une liaison en lecture-écriture vers le driveItem.
Incorporer Crée un lien intégrable vers le driveItem.
blocsTélécharger Crée un lien en lecture seule qui bloque le téléchargement vers le driveItem. Cette option est disponible uniquement pour les fichiers dans OneDrive Entreprise et SharePoint.
createOnly Crée un lien de téléchargement uniquement vers le driveItem. Cette option est disponible uniquement pour les dossiers dans OneDrive Entreprise et SharePoint.
barre d’adresse Crée le lien par défaut qui s’affiche dans les barres d’adresse du navigateur pour les fichiers nouvellement créés. Disponible uniquement dans OneDrive Entreprise et SharePoint. L’administrateur de l’organisation configure si ce type de lien prend en charge et spécifie les fonctionnalités qu’il prend en charge.
adminDefault Crée le lien par défaut vers le driveItem, tel que déterminé par l’administrateur de l’organisation. Disponible uniquement dans OneDrive Entreprise et SharePoint. L’administrateur applique la stratégie pour l’organisation.

Types d’étendue

Vous pouvez utiliser les valeurs suivantes pour le paramètre scope.

Valeur Description
Anonyme Toute personne disposant du lien peut accéder sans avoir besoin de se connecter. Il peut s’agir de personnes extérieures à votre organisation. Un administrateur peut désactiver la prise en charge des liens anonymes.
organisation Toute personne connectée à votre client (locataire) peut utiliser le lien pour bénéficier de l’accès. Disponible uniquement dans OneDrive Entreprise et SharePoint.
utilisateurs Des personnes spécifiques dans la collection du destinataire peuvent utiliser le lien pour obtenir l’accès. Disponible uniquement dans OneDrive Entreprise et SharePoint.

Réponse

Si l’opération réussit, cette méthode renvoie une seule ressource Permission dans le corps de la réponse qui représente les autorisations du lien de partage demandé.

La réponse est 201 Created si un nouveau lien de partage est créé pour le driveItem ou 200 OK si un lien existant est renvoyé.

Exemples

L’exemple suivant demande la création d’un lien de partage pour le driveItem spécifié par {itemId} dans le OneDrive de l’utilisateur. Le lien de partage est configuré pour être en lecture seule et utilisable par toute personne disposant du lien. Pour les utilisateurs de OneDrive Entreprise et de SharePoint, utilisez le sendNotification paramètre pour créer un lien de partage. Le lien de partage est ensuite envoyé aux destinataires par e-mail. Toutes les autorisations existantes sont supprimées lors du premier partage si retainInheritedPermissions la valeur est false.

Demande

POST https://graph.microsoft.com/beta/me/drive/items/{itemId}/createLink
Content-Type: application/json

{
  "type": "view",
  "scope": "anonymous",
  "password": "String",
  "recipients": [
    {
      "@odata.type": "microsoft.graph.driveRecipient"
    }
  ],
  "sendNotification": true,
  "retainInheritedPermissions": false
}

Réponse

Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "123ABC",
  "roles": ["write"],
  "link": {
    "type": "view",
    "scope": "anonymous",
    "webUrl": "https://1drv.ms/A6913278E564460AA616C71B28AD6EB6",
    "application": {
      "id": "1234",
      "displayName": "Sample Application"
    },
  },
  "hasPassword": true
}

OneDrive Entreprise et SharePoint prennent en charge les liens pouvant être partagés au sein de l’entreprise. Ils sont similaires aux liens anonymes, sauf qu’ils ne fonctionnent que pour les membres de l’organisation propriétaire. Pour créer un lien pouvant être partagé au sein de l’entreprise, utilisez le paramètre scope avec la valeur organization.

Demande

POST https://graph.microsoft.com/beta/me/drive/items/{item-id}/createLink
Content-Type: application/json

{
  "type": "edit",
  "scope": "organization"
}

Réponse

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "123ABC",
  "roles": ["write"],
  "link": {
    "type": "edit",
    "scope": "organization",
    "webUrl": "https://contoso-my.sharepoint.com/personal/ellen_contoso_com/...",
    "application": {
      "id": "1234",
      "displayName": "Sample Application"
    },
  }
}

Lorsque vous utilisez le type de lien embed, la webUrl renvoyée peut être incorporée dans un élément HTML <iframe>. Lorsqu’un lien d’incorporation est créé, la webHtml propriété contient le code HTML d’un <iframe> pour héberger le contenu.

Remarque : les liens incorporables sont uniquement pris en charge pour OneDrive Personnel.

Demande

L’exemple suivant illustre une demande.

POST https://graph.microsoft.com/beta/me/drive/items/{item-id}/createLink
Content-Type: application/json

{
  "type": "embed"
}

Réponse

L’exemple suivant illustre la demande.

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "123ABC",
  "roles": ["read"],
  "link": {
    "type": "embed",
    "webHtml": "<IFRAME src=\"https://onedrive.live.com/...\"></IFRAME>",
    "webUrl": "https://onedive.live.com/...",
    "application": {
      "id": "1234",
      "displayName": "Sample Application"
    },
  }
}

Remarques

  • Pour créer un lien basé sur la stratégie par défaut de l’organisation et les autorisations de l’appelant sur le driveItem, omettez les paramètres scope et type.
  • Les liens créés à l’aide de cette action n’expirent pas, sauf si une stratégie d’expiration par défaut est appliquée à l’organisation.
  • Les liens sont visibles dans les autorisations de partage pour le driveItem et peuvent être supprimés par un propriétaire du driveItem.
  • Les liens pointent toujours vers la version actuelle d’un driveItem , sauf si le driveItem est extrait (SharePoint uniquement).