driveItem : createLink

  • 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 .

Créez un lien pour partager un driveItem 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 retourné.

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 :

Propriété Type Description
type String Facultatif. Type de lien de partage à créer.
étendue Chaîne Facultatif. Étendue du lien à créer. , anonymousorganizationouusers
expirationDateTime DateTimeOffset Optional. Une chaîne au 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 pour le lien de partage.
destinataires collection driveRecipient Optional. Collection de destinataires qui reçoivent l’accès au lien de partage.
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.
sendNotification Valeur booléenne Si la valeur est 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. Optional.

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

Valeur du type Description
view Crée un lien en lecture seule vers l’objet driveItem.
Examen Crée un lien de révision vers l’élément driveItem. Cette option est disponible uniquement pour les fichiers dans OneDrive Entreprise et SharePoint.
edit Crée un lien en lecture-écriture vers l’objet driveItem.
Incorporer Crée un lien incorporable vers l’élément driveItem.
blocksDownload Crée un lien en lecture seule qui bloque le téléchargement sur l’objet driveItem. Cette option est disponible uniquement pour les fichiers dans OneDrive Entreprise et SharePoint.
createOnly Crée un lien de chargement uniquement vers l’élément driveItem. Cette option est disponible uniquement pour les dossiers dans OneDrive Entreprise et SharePoint.
addressBar Crée le lien par défaut affiché dans les barres d’adresses du navigateur pour les fichiers nouvellement créés. Disponible uniquement dans OneDrive Entreprise et SharePoint. L’administrateur organization 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 l’objet driveItem, tel que déterminé par l’administrateur du organization. Disponible uniquement dans OneDrive Entreprise et SharePoint. L’administrateur applique la stratégie pour le organization.

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 organization. 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 l’objet driveItem ou 200 OK si un lien existant est retourné.

Exemples

L’exemple suivant demande la création d’un lien de partage pour l’objet 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 OneDrive Entreprise et 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 a la valeur 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 fonctionnent uniquement pour les membres du organization 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 incorporé 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’organization et les autorisations de l’appelant sur l’objet driveItem, omettez les paramètres d’étendue et de 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 pour le organization.
  • Les liens sont visibles dans les autorisations de partage pour l’élément driveItem et peuvent être supprimés par un propriétaire de l’élément driveItem.
  • Les liens pointent toujours vers la version actuelle d’un élément driveItem , sauf si l’élément driveItem est extrait (SharePoint uniquement).