Créer un lien de partage vers un objet DriveItem

  • Article

Espace de noms: microsoft.graph

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.

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/{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 l’autorisation.
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 :

Nom Type Description
type string Type de lien de partage à créer. Soit view, edit ou embed.
mot de passe string Mot de passe du lien de partage défini par le créateur. Facultatif et OneDrive Personnel uniquement.
expirationDateTime string Une chaîne au format aaaa-MM-jjTHH :mm :ssZ de DateTime indique l’heure d’expiration de l’autorisation.
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.
étendue string Facultatif. Étendue du lien à créer. Soit anonymous, organization ou users.

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.
users Partagez uniquement avec les personnes que vous choisissez à l’intérieur ou à l’extérieur du organization.

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. Toutes les autorisations existantes sont supprimées lors du premier partage si retainInheritedPermissions a la valeur false.

Demande

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

{
  "type": "view",
  "password": "ThisIsMyPrivatePassword",
  "scope": "anonymous",
  "retainInheritedPermissions": false
}

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"
    },
  },
  "hasPassword": true
}

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 https://graph.microsoft.com/v1.0/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.

Demande

POST https://graph.microsoft.com/v1.0/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://onedrive.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).