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 une copie d’un driveItem de manière asynchrone. Vous pouvez éventuellement copier exclusivement les éléments enfants, spécifier un nouveau dossier parent ou fournir un nouveau nom. Une fois la demande acceptée, l’opération est mise en file d’attente et traitée de manière asynchrone. Utilisez l’URL du moniteur pour suivre la progression jusqu’à la fin de l’opération.

L’opération de copie est limitée à 30 000 éléments de lecteur. Pour plus d’informations, voir Limites de SharePoint.

Importante

  • Les métadonnées ne sont pas conservées lors de la copie d’un élément de lecteur , y compris les métadonnées système et les métadonnées personnalisées. Un tout nouvel élément de lecteur est créé à l’emplacement cible à la place.
  • Les versions de fichier ne sont conservées que lorsque le paramètre includeAllVersionHistory est explicitement défini sur true. Dans le cas contraire, seule la dernière version est copiée.
  • La copie intergéographique n’est pas prise en charge lorsque vous utilisez l’authentification d’application uniquement.
  • Un problème connu se produit lorsque le paramètre de demande includeAllVersionHistory est ignoré si le paramètre de demande de nom est également passé. Pour éviter ce problème, effectuez d’abord l’opération de copie sans le paramètre name , puis renommez l’élément cible une fois la copie terminée.

Cette API est disponible dans les déploiements cloud nationaux suivants.

Service global Gouvernement américain L4 Gouvernement américain L5 (DOD) Chine exploitée par 21Vianet
✅ ✅ ✅ ✅

Autorisations

Remarque

Les autorisations ne sont pas conservées lors de la copie d’un élément de lecteur. Le driveItem copié hérite des autorisations du dossier de destination.

Choisissez l’autorisation ou les autorisations marquées comme étant les moins privilégiées pour cette API. Utilisez une ou plusieurs autorisations privilégiées uniquement si votre application en a besoin. Pour plus d’informations sur les autorisations déléguées et d’application, voir Types d’autorisations. Pour en savoir plus sur ces autorisations, consultez la référence des autorisations.

Type d’autorisation Autorisations les moins privilégiées Autorisations à privilèges plus élevés
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 pour accéder au contenu du conteneur. Cette autorisation est différente de celles mentionnées précédemment. Outre les autorisations Microsoft Graph, votre application doit disposer des autorisations de type conteneur nécessaires pour appeler cette API. Pour plus d’informations, consultez Authentification et 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 paramètre de @microsoft.graph.conflictBehavior requête pour personnaliser le comportement en cas de conflit.

Valeur Description
fail L’ensemble de l’opération échoue en cas de conflit. Ce comportement est le comportement par défaut si aucune option n’est spécifiée.
replace L’élément de fichier préexistant est supprimé et remplacé par le nouvel élément en cas de conflit. Cette option n’est prise en charge que pour les éléments de fichier. Le nouvel élément porte le même nom que l’ancien. L’historique de l’ancien élément est supprimé.
rename Ajoute le plus petit entier garantissant l’unicité au nom du nouveau fichier ou dossier et termine l’opération.

Remarque

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

Le @microsoft.graph.conflictBehavior paramètre est appliqué à tous les éléments copiés au cours de l’opération. La replace valeur n’est prise en charge que pour les fichiers ; les dossiers en conflit utilisent ce comportement à la fail place.

Corps de la demande

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

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

Remarque

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

Réponse

La réponse renvoie des détails sur la façon de surveiller la progression de la copie, après 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

Cet exemple montre comment copier un fichier identifié par {item-id} dans un dossier de destination identifié par ses driveId valeurs et id . Le fichier copié reçoit un nouveau nom 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

Utilisez l’URL dans l’en-tête Location pour surveiller la progression de l’opération de copie asynchrone.

Exemple 2 : copier les éléments enfants dans un dossier

L’exemple copie uniquement le contenu d’un dossier, et non le dossier lui-même, vers une destination différente. Le dossier source est identifié par {item-id}, et la destination est identifiée par ses driveId valeurs et id .

La demande définit le childrenOnly paramètre sur true, ce qui est valide uniquement lorsque l’élément source est un 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 202 Accepted
Location: https://contoso.sharepoint.com/_api/v2.0/monitor/4A3407B5-88FC-4504-8B21-0AABD3412717

Le Location champ de la réponse contient une URL de surveillance que vous pouvez utiliser pour vérifier la progression de l’opération de case activée. Étant donné que les opérations de copie se produisent de manière asynchrone et peuvent se terminer après une durée indéterminée, vous pouvez utiliser cette URL à plusieurs reprises pour suivre son status.

Pour recevoir un rapport de status similaire à celui de l’exemple suivant, GET the URL in the Location field of the response.

{
  "@odata.context": "https://contoso.sharepoint.com/sites/site1/_api/v2.1/$metadata#drives('driveId')/operations/$entity",
  "id": "049af13f-d177-4c70-aed0-eb6f04a5d88b",
  "createdDateTime": "0001-01-01T00:00:00Z",
  "lastActionDateTime": "0001-01-01T00:00:00Z",
  "percentageComplete": 100,
  "percentComplete": 100,
  "resourceId": "016OGUCSF6Y2GOVW7725BZO354PWSELRRZ",
  "resourceLocation": "https://contoso.sharepoint.com/sites/site2/_api/v2.0/drives/b!1YwGyNd6RUuVB42eCVw7ULlXybr_-09Br67iDGnYY-neBqwZd6jJRJbgCTx0On5n/items/016OGUCSF6Y2GOVW7725BZO354PWSELRRZ",
  "status": "completed"
}

Exemple 3 : Échec de la copie en raison d’un conflit de noms dans le dossier de destination

Cet exemple montre une tentative de copie infructueuse d’un fichier vers un dossier de destination qui contient déjà un fichier du même nom. La demande ne spécifie pas de @microsoft.graph.conflictBehavior paramètre de requête pour résoudre le conflit.

Étant donné qu’aucun comportement de conflit n’est fourni, l’API accepte la demande, mais échoue pendant le traitement. L’opération renvoie une nameAlreadyExists erreur.

Pour éviter cette erreur, utilisez le paramètre @microsoft.graph.conflictBehavior, avec une valeur de replace ou rename.

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

L’exemple suivant montre un exemple de rapport de status obtenu en visitant l’URL dans la valeur du Location champ en réponse à la requête initiale.

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

Exemple 4 : copier un fichier dans un dossier contenant un fichier du même nom

Cet exemple montre comment copier un fichier dans un dossier contenant déjà un fichier du même nom. La demande utilise le paramètre de requête @microsoft.graph.conflictBehavior pour gérer le conflit de nommage.

Le paramètre est défini sur replace, ce qui indique à l’API de remplacer l’élément existant dans le dossier de destination.

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 : Demande non valide lors de la copie d’éléments enfants avec des conflits de dossiers à l’aide de conflictBehavior=replace

Cet exemple montre une requête ayant échoué qui tente de copier uniquement les éléments enfants d’un dossier. La demande définit le paramètre et true utilise le childrenOnly@microsoft.graph.conflictBehavior paramètre de requête avec une valeur de replace.

Un ou plusieurs éléments enfants du dossier source sont des dossiers. Étant donné que le comportement n’est replace pas pris en charge lorsqu’un élément en conflit est un dossier, l’opération de copie échoue. La demande est acceptée et une URL de surveillance est renvoyée, mais l’opération finit par signaler une erreur.

Pour éviter cette erreur, utilisez rename ou fail à la place lors de replace la copie d’éléments enfants qui incluent des dossiers.

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

Interrogez l’URL du moniteur dans l’en-tête d’emplacement pour surveiller le status de l’opération. Une opération ayant échoué peut retourner une réponse similaire à l’exemple suivant.

{
  "@odata.context": "https://contoso.sharepoint.com/sites/site2/_api/v2.1/$metadata#drives('driveId')/operations/$entity",
  "id": "e410fb22-fc84-41df-ac9f-e95e5110a5cb",
  "createdDateTime": "0001-01-01T00:00:00Z",
  "lastActionDateTime": "0001-01-01T00:00:00Z",
  "status": "failed",
  "error": {
    "message": "Errors occurred during copy/move operation.",
    "details": [
      {
        "code": "nameAlreadyExists",
        "message": "Name already exists"
      },
      {
        "code": "nameAlreadyExists",
        "message": "Name already exists"
      },
      {
        "code": "nameAlreadyExists",
        "message": "Name already exists",
        "target": "01E4CGZM4FGUVRMKSJWBCLZQTWNFGHOTXG"
      },
      {
        "code": "nameAlreadyExists",
        "message": "Name already exists",
        "target": "01E4CGZM2XRHETBOUOYVA2OKZFMGGBQ6VU"
      }
    ]
  }
}

Exemple 6 : Copier un élément et conserver l’historique des versions

Cet exemple montre comment copier un élément de fichier vers un nouvel emplacement et inclure son historique de version dans l’élément copié. Le includeAllVersionHistory paramètre est défini true sur dans le corps de la demande pour indiquer que l’historique des versions doit être conservé.

Si le fichier source a plus de versions que le site de destination ne l’autorise, toutes les versions sont initialement copiées, puis le comportement de stockage de version lorsque les versions dépassent les paramètres appliqués est suivi.

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

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

Utilisez l’URL Location dans l’en-tête de réponse pour surveiller la progression de l’opération de copie asynchrone.

Exemple 7 : Demande non valide lors de la copie du dossier racine sans childrenOnly

Cet exemple montre une requête ayant échoué qui tente de copier le dossier racine en spécifiant root comme .{item-id} La demande n’inclut pas le childrenOnly paramètre. Étant donné que le dossier racine lui-même ne peut pas être copié et childrenOnly n’est pas défini sur true, la demande est rejetée avec une invalidRequest erreur.

Pour copier le contenu du dossier racine sans copier le dossier lui-même, définissez le childrenOnly paramètre sur true.

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

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 childrenOnly paramètre sur true.

Exemple 8 : Demande non valide lors de la copie des éléments enfants d’un fichier

Cet exemple montre une requête ayant échoué qui définit le childrenOnly paramètre sur true un élément source qui est un fichier. Le childrenOnly paramètre est valide uniquement pour les éléments de dossier. Étant donné que les fichiers ne contiennent pas d’éléments enfants, la demande est rejetée avec une erreur invalidRequest.

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

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 : Demande non valide lors de la spécification des deux childrenOnly et name

Cet exemple montre une requête ayant échoué qui définit le childrenOnly paramètre de true copier uniquement les éléments enfants d’un dossier, tout en spécifiant une nouvelle name valeur. Ces deux paramètres ne peuvent pas être utilisés ensemble, car le dossier lui-même n’est pas copié. La demande est rejetée avec une invalidRequest erreur.

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

Exemple 10 : Copie enfant réussie uniquement

Cet exemple montre comment copier les éléments enfants d’un dossier (sans copier le dossier lui-même) dans une nouvelle destination. Le dossier source est identifié par {item-id}, et le dossier de destination est spécifié à l’aide de ses driveId et id. La requête définit la propriété sur true, qui est valide uniquement pour les childrenOnly éléments de 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

Utilisez l’URL de l’emplacement pour suivre le status de l’opération de copie asynchrone. Une réponse réussie peut ressembler à ceci :

HTTP/1.1 202 Accepted
Location: https://contoso.sharepoint.com/sites/FromSite/_api/v2.1/monitor/780293e6-07b3-4544-a126-fea909efcc84

{
  "@odata.context": "https://contoso.sharepoint.com/sites/FromSite/_api/v2.1/$metadata#drives('b!eUKtdpCU_kSVaTUFV6NpD-X6ybrlZ_5AgIz5YS9EUgU51UBlz4oFSauS0JyHnBdR')/operations/$entity",
  "id": "780293e6-07b3-4544-a126-fea909efcc84",
  "createdDateTime": "0001-01-01T00:00:00Z",
  "lastActionDateTime": "0001-01-01T00:00:00Z",
  "percentageComplete": 100,
  "percentComplete": 100,
  "resourceId": "01MXEZFVE5G2AS5Y74YZFYQF3KZAQ7CFEP",
  "resourceLocation": "https://contoso.sharepoint.com/sites/ToSite/_api/v2.0/drives/b!JiheeiHiFEymg-TwftZJ-eX6ybrlZ_5AgIz5YS9EUgU51UBlz4oFSauS0JyHnBdR/items/01MXEZFVE5G2AS5Y74YZFYQF3KZAQ7CFEP",
  "status": "completed"
}

Contenu connexe

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

  • Last updated on