Partager via

driveItem : copy

Espace de noms: microsoft.graph

Créez une copie d’un objet driveItem de façon asynchrone, y compris les éléments enfants. Vous pouvez 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.

Importante

Les métadonnées ne sont pas conservées lorsqu’un objet driveItem est copié, y compris les métadonnées système et les métadonnées personnalisées. Un élément driveItem entièrement nouveau est créé à l’emplacement cible à la place.

Les autorisations ne sont pas conservées lorsqu’un objet driveItem est copié. L’élément driveItem copié hérite des autorisations du dossier de destination.

Les versions de fichier sont conservées uniquement lorsque le includeAllVersionHistory paramètre est explicitement défini sur true. Sinon, seule la dernière version est copiée.

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

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. En plus des autorisations Microsoft Graph, votre application doit disposer des autorisations de type de 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 @microsoft.graph.conflictBehavior paramètre de requête pour personnaliser le comportement en cas de conflit.

Valeur Description
fail L’opération entière échoue lorsqu’un conflit se produit. Ce comportement est la valeur 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 lorsqu’un conflit se produit. Cette option est uniquement prise en charge 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 l’entier le plus bas qui garantit 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 le consommateur OneDrive.

Le @microsoft.graph.conflictBehavior paramètre est appliqué à tous les éléments copiés pendant l’opération. La replace valeur est prise en charge uniquement pour les fichiers ; les dossiers avec des conflits utilisent le 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
parentReference ItemReference Facultatif. 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.

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

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/v1.0/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 autre destination. Le dossier source est identifié par {item-id}, et la destination est identifiée par ses driveId valeurs et id .

La requête définit le paramètre sur childrenOnly true, ce qui est valide uniquement lorsque l’élément source est un dossier.

Demande

POST https://graph.microsoft.com/v1.0/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 case activée la progression de l’opération de copie. Étant donné que les opérations de copie se produisent de manière asynchrone et peuvent se terminer après un laps de temps non spécifié, vous pouvez utiliser cette URL à plusieurs reprises pour suivre son status.

Pour recevoir un rapport status similaire à celui de l’exemple suivant, obtenez l’URL dans le Location champ de la réponse.

{
  "@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 d’échec de copie d’un fichier dans un dossier de destination qui contient déjà un fichier portant le même nom. La requête 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 retourne une nameAlreadyExists erreur.

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

Demande

POST https://graph.microsoft.com/v1.0/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 status rapport obtenu en visitant l’URL dans la Location valeur du champ dans la réponse à la demande 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 portant le même nom

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

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

Les valeurs possibles pour @microsoft.graph.conflictBehavior sont les suivantes :

  • replace: remplacez le fichier existant.
  • rename: renommez la nouvelle copie.
  • fail: Échec de la requête s’il existe un conflit d’affectation de noms.

Demande

POST https://graph.microsoft.com/v1.0/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 : requête non valide lors de la copie d’éléments enfants avec des conflits de dossiers à l’aide de conflictBehavior=replace

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

Un ou plusieurs éléments enfants dans le dossier source sont des dossiers. Étant donné que le replace comportement n’est 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 retournée, mais l’opération signale finalement une erreur.

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

Demande

POST https://graph.microsoft.com/v1.0/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 la 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 des versions dans l’élément copié. Le includeAllVersionHistory paramètre est défini sur true dans le corps de la demande pour indiquer que l’historique des versions doit être conservé.

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

Demande

POST https://graph.microsoft.com/v1.0/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 : requête non valide lors de la copie du dossier racine sans childrenOnly

Cet exemple montre une demande ayant échoué qui tente de copier le dossier racine en spécifiant root comme {item-id}. La requête 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 paramètre sur childrenOnlytrue.

Demande

POST https://graph.microsoft.com/v1.0/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 paramètre sur childrenOnly true.

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

Cet exemple montre une demande ayant échoué qui définit le childrenOnly paramètre sur true pour 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/v1.0/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 : requête non valide lors de la spécification de childrenOnly et name

Cet exemple montre une demande ayant échoué qui définit le childrenOnly paramètre sur true pour 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/v1.0/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 d’enfants 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 et driveIdidde . La requête définit la propriété truesur childrenOnly , ce qui est valide uniquement pour les éléments de dossier.

Demande

POST https://graph.microsoft.com/v1.0/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 d’emplacement pour suivre la 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

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

{
  "@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 l’erreur, consultez Réponses aux erreurs.