Créer un lien de partage vers un objet DriveItem

  • Article

Vous pouvez utiliser l’action createLink pour partager un objet DriveItem via un lien de partage.

L’action createLink créera un nouveau lien de partage si le type de lien spécifié n’existe pas encore 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.

Autorisations

L’une des autorisations suivantes est requise pour appeler cette API. Pour plus d’informations, notamment sur la façon de choisir les autorisations, voir Autorisations.

Type d’autorisation Autorisations (de celle qui offre le plus de privilèges à celle qui en offre le moins)
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/{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

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 :

Nom Type Description
type string Type de lien de partage à créer. Soit view, edit ou embed.
étendue string Facultatif. Étendue du lien à créer. Soit anonymous ou organization.

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

Valeur du type Description
view Permet de créer un lien en lecture seule vers la ressource DriveItem.
edit Permet de créer un lien en lecture/écriture vers la ressource DriveItem.
embed Permet de créer un lien incorporable vers la ressource DriveItem. Cette option est uniquement disponible pour les fichiers situés dans OneDrive Personnel.

Types d’étendue

Vous pouvez utiliser les valeurs suivantes pour le paramètre scope. Si le paramètre scope n’est pas spécifié, le type de liaison par défaut de l’organisation est créé.

Valeur Description
anonymous Toute personne disposant du lien peut accéder sans avoir besoin de se connecter. Cela peut inclure des personnes extérieures à votre organisation. Le support des liens anonymes peut être désactivé par l’administrateur.
organization 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.

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 sera 201 Created si un nouveau lien de partage est créé pour l’élément, ou 200 OK si un lien existant est renvoyé.

Exemple

L’exemple suivant demande la création d’un lien de partage pour la ressource DriveItem spécifié par {itemId} dans l’instance OneDrive de l’utilisateur. Le lien de partage est configuré pour être en lecture seule et utilisable par toute personne disposant du lien.

Demande

POST /me/drive/items/{item-id}/createLink
Content-type: application/json

{
  "type": "view",
  "scope": "anonymous"
}

Réponse

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

OneDrive Entreprise et SharePoint prennent en charge les liens pouvant être partagés au sein de l’entreprise. Ils sont semblables aux liens anonymes, à l’exception du fait qu’ils fonctionnent uniquement 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 /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>. Lors de la création d’un lien incorporé, la propriété webHtml contient le code HTML qui permet à un élément <iframe> d’héberger le contenu.

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

Demander

POST /me/drive/items/{item-id}/createLink
Content-Type: application/json

{
  "type": "embed"
}

Réponse

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

  • 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 pour l’organisation.
  • Les liens sont visibles dans les autorisations de partage de l’élément et peuvent être supprimés par le propriétaire de l’élément.
  • Les liens renvoient toujours vers la version actuelle de l’élément, sauf si l’élément a été extrait (SharePoint uniquement).