driveItem : copy

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 de façon asynchrone une copie d’un objet driveItem (y compris les enfants) sous un nouvel élément parent ou avec un nouveau nom. Une fois la demande confirmée, elle entre dans une file d’attente. La copie réelle, y compris les sous-éléments, se produit à un moment indéterminé. La progression est signalée jusqu’à ce que l’opération soit terminée en surveillant la progression.

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

Remarque

SharePoint Embedded nécessite l’autorisation FileStorageContainer.Selected d’accéder au contenu du conteneur. Cette autorisation est différente de celles mentionnées précédemment. Pour plus d’informations, consultez Authentification et autorisation SharePoint Embedded. En plus des autorisations Microsoft Graph, votre application doit disposer de l’autorisation ou des autorisations nécessaires au niveau du type de conteneur pour appeler cette API. Pour plus d’informations, consultez Types de conteneurs. Pour en savoir plus sur les autorisations au niveau du type de conteneur, voir Autorisation SharePoint Embedded.

Requête HTTP

POST /drives/{driveId}/items/{itemId}/copy
POST /groups/{groupId}/drive/items/{itemId}/copy
POST /me/drive/items/{item-id}/copy
POST /sites/{siteId}/drive/items/{itemId}/copy
POST /users/{userId}/drive/items/{itemId}/copy

Paramètres facultatifs de la requête

Cette méthode prend en charge le @microsoft.graph.conflictBehavior paramètre de requête pour personnaliser le comportement en cas de conflit.

Valeur Description
fail Le comportement par défaut consiste à signaler l’échec.
replace Remplacer l’élément existant sur le site cible.
rename Renommez l’élément.

Remarque

Le conflictBehavior paramètre n’est pas pris en charge pour le consommateur OneDrive.

Corps de la demande

Dans le corps de la demande, fournissez un objet JSON avec les paramètres suivants.

Nom Valeur Description
parentReference ItemReference Optional. Référence à l’élément parent dans lequel la copie est créée.
nom string Facultatif. Nouveau nom de la copie. Si ces informations ne sont pas fournies, le même nom est utilisé que l’original.
childrenOnly Boolean Facultatif. Si la valeur trueest , les enfants de l’objet driveItem sont copiés, mais pas l’élément driveItem lui-même. La valeur par défaut est false. Valide uniquement sur les éléments de dossier.
includeAllVersionHistory Boolean Facultatif. Si la truevaleur est , l’historique des versions des fichiers sources (versions principales et versions mineures, le cas échéant) doit être copié vers la destination, dans la limite du paramètre de version cible. Si falsela valeur est , seule la dernière version principale est copiée vers la destination. La valeur par défaut est false.

Remarque

Le parentReference paramètre doit inclure les driveId paramètres et id pour le dossier cible.

Dans une seule demande, l’option childrenOnly copie 150 éléments enfants, et pour les petits-enfants, la limite SharePoint s’applique. Pour plus d’informations, voir Limitation de SharePoint

Réponse

La réponse retourne des détails sur la façon de surveiller la progression de la copie, lors de l’acceptation de la demande. La réponse indique si l’opération de copie a été acceptée ou rejetée, par exemple si le nom de fichier de destination est déjà utilisé.

Exemples

Exemple 1 : Copier un fichier dans un dossier

L’exemple suivant copie un fichier identifié par {item-id} dans un dossier identifié par une driveId valeur et id . La nouvelle copie du fichier est nommée contoso plan (copy).txt.

Demande

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

{
  "parentReference": {
    "driveId": "b!s8RqPCGh0ESQS2EYnKM0IKS3lM7GxjdAviiob7oc5pXv_0LiL-62Qq3IXyrXnEop",
    "id": "DCD0D3AD-8989-4F23-A5A2-2C086050513F"
  },
  "name": "contoso plan (copy).txt"
}

Réponse

L’exemple suivant illustre la réponse.

HTTP/1.1 202 Accepted
Location: https://contoso.sharepoint.com/_api/v2.0/monitor/4A3407B5-88FC-4504-8B21-0AABD3412717

Exemple 2 : Copier les enfants dans un dossier

L’exemple suivant copie les enfants d’un dossier identifié par {item-id} dans un dossier identifié par une driveId valeur et id . Le childrenOnly paramètre est défini sur true.

Demande

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

{
  "parentReference": {
    "driveId": "b!s8RqPCGh0ESQS2EYnKM0IKS3lM7GxjdAviiob7oc5pXv_0LiL-62Qq3IXyrXnEop",
    "id": "DCD0D3AD-8989-4F23-A5A2-2C086050513F"
  },
  "childrenOnly": true
}

Réponse

L’exemple suivant illustre la réponse.

HTTP/1.1 202 Accepted
Location: https://contoso.sharepoint.com/_api/v2.0/monitor/4A3407B5-88FC-4504-8B21-0AABD3412717

La surveillance est importante, car l’opération de copie avec childrenOnly se produit sur plusieurs opérations.

Exemple 3 : Copier les enfants dans un dossier avec un conflit de noms

L’exemple suivant tente de copier les enfants d’un dossier identifié par {item-id} dans un dossier identifié par une driveId valeur et id . La destination porte déjà le même nom que celui de la source. L’opération est acceptée, mais elle rencontre un échec pendant le traitement.

Demande

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

{
  "parentReference": {
    "driveId": "b!s8RqPCGh0ESQS2EYnKM0IKS3lM7GxjdAviiob7oc5pXv_0LiL-62Qq3IXyrXnEop",
    "id": "DCD0D3AD-8989-4F23-A5A2-2C086050513F"
  }
}

Réponse

L’exemple suivant illustre la réponse.

HTTP/1.1 202 Accepted
Location: https://contoso.sharepoint.com/_api/v2.0/monitor/4A3407B5-88FC-4504-8B21-0AABD3412717

Suivez l’URL du moniteur.

{
  "id": "46cf980a-28e1-4623-b8d0-11fc5278efe6",
  "createdDateTime": "0001-01-01T00:00:00Z",
  "lastActionDateTime": "0001-01-01T00:00:00Z",
  "status": "failed",
  "error": {
    "code": "nameAlreadyExists",
    "message": "Name already exists"
  }
}

Pour résoudre cette erreur, utilisez le paramètre de requête facultatif @microsoft.graph.conflictBehavior.

Exemple 4 : Copier les enfants d’un dossier avec le paramètre conflit de noms conflictBehavior

L’exemple suivant copie les enfants d’un dossier identifié par {item-id} dans un dossier identifié par une driveId valeur et id . Le paramètre @microsoft.graph.conflictBehavior de requête facultatif est défini sur remplacer. Les valeurs possibles sont replace, rename ou fail. La destination porte déjà le même nom que celui de la source.

Demande

POST https://graph.microsoft.com/beta/me/drive/items/{item-id}/copy?@microsoft.graph.conflictBehavior=replace
Content-Type: application/json

{
  "parentReference": {
    "driveId": "b!s8RqPCGh0ESQS2EYnKM0IKS3lM7GxjdAviiob7oc5pXv_0LiL-62Qq3IXyrXnEop",
    "id": "DCD0D3AD-8989-4F23-A5A2-2C086050513F"
  }
}

Réponse

L’exemple suivant illustre la réponse.

HTTP/1.1 202 Accepted
Location: https://contoso.sharepoint.com/_api/v2.0/monitor/4A3407B5-88FC-4504-8B21-0AABD3412717

Exemple 5 : l’opération de copie conserve l’historique des versions

L’exemple suivant copie l’élément identifié par {item-id} dans un dossier identifié par une driveId valeur et id . Il copie également l’historique des versions dans le dossier cible. Si le fichier source contient 20 versions et que le paramètre de limite de version de destination est 10, la copie transfère uniquement le nombre maximal de versions autorisées par le site de destination, à partir de la plus récente.

Demande

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

{
  "parentReference": {
    "driveId": "b!s8RqPCGh0ESQS2EYnKM0IKS3lM7GxjdAviiob7oc5pXv_0LiL-62Qq3IXyrXnEop",
    "id": "DCD0D3AD-8989-4F23-A5A2-2C086050513F"
  },
  "includeAllVersionHistory": true
}

Réponse

L’exemple suivant illustre la réponse.

HTTP/1.1 202 Accepted
Location: https://contoso.sharepoint.com/_api/v2.0/monitor/4A3407B5-88FC-4504-8B21-0AABD3412717

Exemple 6 : Copier les enfants d’un dossier à partir de la racine

L’exemple suivant tente de copier les enfants d’un dossier identifié par {item-id} (également appelé racine) dans un dossier identifié par une driveId valeur et id . Le childrenOnly paramètre n’est pas défini sur true. La demande échoue, car l’opération de copie ne peut pas être effectuée dans le dossier racine.

Demande

POST https://graph.microsoft.com/beta/me/drive/items/root/copy
Content-Type: application/json

{
  "parentReference": {
    "driveId": "b!s8RqPCGh0ESQS2EYnKM0IKS3lM7GxjdAviiob7oc5pXv_0LiL-62Qq3IXyrXnEop",
    "id": "DCD0D3AD-8989-4F23-A5A2-2C086050513F"
  }
}

Réponse

L’exemple suivant illustre la réponse.

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 283

{
  "error":
  {
    "code": "invalidRequest",
    "message": "Cannot copy the root folder.",
    "innerError":
    {
      "date": "2023-12-11T04:26:35",
      "request-id": "8f897345980-f6f3-49dd-83a8-a3064eeecdf8",
      "client-request-id": "50a0er33-4567-3f6c-01bf-04d144fc8bbe"
    }
  }
}

Pour résoudre cette erreur, définissez le paramètre sur childrenOnly true.

Exemple 7 : Copier les enfants dans un dossier où la source a plus de 150 enfants directs

L’exemple suivant tente de copier les enfants d’un dossier identifié par {item-id} dans un dossier identifié par une driveId valeur et id . Le childrenOnly paramètre est défini sur true. L’élément de lecteur identifié par {item-id} contient plus de 150 enfants directs. La demande échoue, car la limite est de 150 enfants directs.

Demande

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

{
  "parentReference": {
    "driveId": "b!s8RqPCGh0ESQS2EYnKM0IKS3lM7GxjdAviiob7oc5pXv_0LiL-62Qq3IXyrXnEop",
    "id": "DCD0D3AD-8989-4F23-A5A2-2C086050513F"
  }
}

Réponse

L’exemple suivant illustre la réponse.

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 341

{
  "error":
  {
    "code": "invalidRequest",
    "message": "Direct child count limit exceeded. Cannot copy children only when there are more than 150 direct children.",
    "innerError":
    {
      "code": "directChildrenLimitExceeded",
      "date": "2023-12-11T04:26:35",
      "request-id": "8f897345980-f6f3-49dd-83a8-a3064eeecdf8",
      "client-request-id": "50a0er33-4567-3f6c-01bf-04d144fc8bbe"
    }
  }
}

Pour résoudre cette erreur, réorganisez la structure de dossiers source uniquement pour avoir 150 enfants.

Exemple 8 : Copier les enfants où l’élément source est un fichier

L’exemple suivant tente de copier les enfants d’un dossier identifié par {item-id} dans un dossier identifié par une driveId valeur et id . fait {item-id} référence à un fichier, et non à un dossier. Le childrenOnly paramètre est défini sur true. La requête échoue, car est {item-id} un élément driveItem non dossier.

Demande

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

{
  "parentReference": {
    "driveId": "b!s8RqPCGh0ESQS2EYnKM0IKS3lM7GxjdAviiob7oc5pXv_0LiL-62Qq3IXyrXnEop",
    "id": "DCD0D3AD-8989-4F23-A5A2-2C086050513F"
  },
  "childrenOnly": true
}

Réponse

L’exemple suivant illustre la réponse.

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 290

{
  "error":
  {
    "code": "invalidRequest",
    "message": "childrenOnly option is not valid for file items.",
    "innerError":
    {
      "date": "2023-12-11T04:26:35",
      "request-id": "8f897345980-f6f3-49dd-83a8-a3064eeecdf8",
      "client-request-id": "50a0er33-4567-3f6c-01bf-04d144fc8bbe""
    }
  }
}

Exemple 9 : Copier les enfants dans un dossier avec childrenOnly et name

L’exemple suivant tente de copier les enfants d’un dossier identifié par {item-id} dans un dossier identifié par une driveId valeur et id . Le childrenOnly paramètre a la valeur true et spécifie une name valeur. La demande échoue car childrenOnly et name ne peuvent pas être utilisés ensemble.

Demande

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

{
  "parentReference": {
    "driveId": "b!s8RqPCGh0ESQS2EYnKM0IKS3lM7GxjdAviiob7oc5pXv_0LiL-62Qq3IXyrXnEop",
    "id": "DCD0D3AD-8989-4F23-A5A2-2C086050513F"
  },
  "name": "contoso plan (copy).txt",
  "childrenOnly": true
}

Réponse

L’exemple suivant illustre la réponse.

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 285

{
  "error":
  {
    "code": "invalidRequest",
    "message": "Cannot use name parameter alongside childrenOnly.",
    "innerError":
    {
      "date": "2023-12-11T04:26:35",
      "request-id": "8f897345980-f6f3-49dd-83a8-a3064eeecdf8",
      "client-request-id": "50a0er33-4567-3f6c-01bf-04d144fc8bbe""
    }
  }
}

Pour plus d’informations sur l’erreur, consultez Réponses aux erreurs.