listItem : 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éez un lien de partage pour un objet listItem.

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, cette action retourne le lien de partage existant.

Les ressources listItem héritent des autorisations de partage de la liste dans laquelle réside l’élément.

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 /sites/{siteId}/lists/{listId}/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

Dans le corps de la demande, fournissez une représentation JSON des paramètres.

Le tableau suivant indique les paramètres utilisables avec cette action.

Propriété Type Description
type Chaîne Type de lien de partage à créer. Optional.
étendue Chaîne Étendue du lien à créer. soit anonymous, organization soit users. Optional.
expirationDateTime DateTimeOffset Une chaîne au format aaaa-MM-ddTHH :mm :ssZ de DateTime indique l’heure d’expiration de l’autorisation. Optional.
mot de passe Chaîne Mot de passe du lien de partage défini par le créateur. Optional.
destinataires collection driveRecipient Collection de destinataires qui recevront l’accès au lien de partage. Optional.
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 et 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’élément.
Examen Crée un lien de révision vers l’élément. Cette option est disponible uniquement pour les fichiers dans OneDrive Entreprise et SharePoint.
edit Crée un lien en lecture/écriture vers l’élément.
Incorporer Crée un lien incorporable vers l’élément.
blocksDownload Crée un lien en lecture seule qui bloque le téléchargement vers l’élément. 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. 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 est pris en charge et quelles fonctionnalités sont prises en charge par ce type de lien.
adminDefault Crée le lien par défaut vers l’élément tel que déterminé par l’administrateur de l’organization. Disponible uniquement dans OneDrive Entreprise et SharePoint. La stratégie est appliquée pour le organization par l’administrateur

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. Cela peut inclure des personnes extérieures à votre organisation. Le support des liens anonymes peut être désactivé par l’administrateur.
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 de destinataires peuvent utiliser le lien pour obtenir l’accès. Disponible uniquement dans OneDrive Entreprise et SharePoint.

Réponse

Si elle réussit, cette méthode renvoie une ressource d’autorisation unique dans le corps de la réponse qui représente les autorisations de partage demandées.

La réponse est 201 Created si un nouveau lien de partage est créé pour l’objet listItem 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 listItem spécifié par {itemId} dans la liste spécifiée {listId}. 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 sharingLink 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/sites/{siteId}/lists/{listId}/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. Ces liens 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/sites/{siteId}/lists/{listId}/items/{itemId}/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 embed lien, le webUrl retourné peut être incorporé dans un <iframe> élément HTML. 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

POST https://graph.microsoft.com/beta/sites/{siteId}/lists/{listId}/items/{itemId}/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

  • 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 listItem, 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’objet listItem et peuvent être supprimés par un propriétaire de l’objet listItem.
  • Les liens pointent toujours vers la version actuelle d’un objet listItem, sauf si l’objet listItem est extrait (SharePoint uniquement).