driveItem: copy
Namespace: microsoft.graph
Important
APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.
Asynchronously create a copy of a driveItem (including any children) under a new parent item or with a new name. After the request is acknowledged, it enters a queue. The actual copying, including any subitems, occurs at an undetermined time. Progress is reported until the operation is completed by monitoring the progress.
This API is available in the following national cloud deployments.
| Global service | US Government L4 | US Government L5 (DOD) | China operated by 21Vianet |
|---|---|---|---|
| ✅ | ✅ | ✅ | ✅ |
Permissions
Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.
| Permission type | Least privileged permissions | Higher privileged permissions |
|---|---|---|
| Delegated (work or school account) | Files.ReadWrite | Files.ReadWrite.All, Sites.ReadWrite.All |
| Delegated (personal Microsoft account) | Files.ReadWrite | Files.ReadWrite.All |
| Application | Files.ReadWrite.All | Sites.ReadWrite.All |
Note
SharePoint Embedded requires the FileStorageContainer.Selected permission to access the content of the container. This permission is different from the ones mentioned previously. For more information, see SharePoint Embedded authentication and authorization.
In addition to Microsoft Graph permissions, your app must have the necessary container type-level permission or permissions to call this API. For more information, see container types. To learn more about container type-level permissions, see SharePoint Embedded authorization.
HTTP request
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
Optional query parameters
This method supports the @microsoft.graph.conflictBehavior query parameter to customize the behavior when a conflict occurs.
| Value | Description |
|---|---|
| fail | Default behavior is to report the failure. |
| replace | Overwrite existing item at the target site. |
| rename | Rename the item. |
Note
The conflictBehavior parameter isn't supported for OneDrive Consumer.
Request body
In the request body, provide a JSON object with the following parameters.
| Name | Value | Description |
|---|---|---|
| parentReference | ItemReference | Optional. Reference to the parent item the copy is created in. |
| name | string | Optional. The new name for the copy. If this information isn't provided, the same name is used as the original. |
| childrenOnly | Boolean | Optional. If set to true, the children of the driveItem are copied but not the driveItem itself. The default value is false. Valid only on folder items. |
Note
The parentReference parameter should include the driveId and id parameters for the target folder.
In a single request, the childrenOnly option copies 150 children items, and for the grandchildren items the SharePoint limit applies. For more information, see SharePoint limitation
Response
The response returns details about how to monitor the progress of the copy, upon accepting the request. The response indicates whether the copy operation was accepted or rejected - for example, if the destination filename is already in use.
Examples
Example 1: Copy a file to a folder
The following example copies a file identified by {item-id} into a folder identified with a driveId and id value.
The new copy of the file is named contoso plan (copy).txt.
Request
POST https://graph.microsoft.com/beta/me/drive/items/{item-id}/copy
Content-Type: application/json
{
"parentReference": {
"driveId": "6F7D00BF-FC4D-4E62-9769-6AEA81F3A21B",
"id": "DCD0D3AD-8989-4F23-A5A2-2C086050513F"
},
"name": "contoso plan (copy).txt"
}
Response
The following example shows the response.
HTTP/1.1 202 Accepted
Location: https://contoso.sharepoint.com/_api/v2.0/monitor/4A3407B5-88FC-4504-8B21-0AABD3412717
Example 2: Copy the children in a folder
The following example copies the children in a folder identified by {item-id} into a folder identified with a driveId and id value.
The childrenOnly parameter is set to true.
Request
POST https://graph.microsoft.com/beta/me/drive/items/{item-id}/copy
Content-Type: application/json
{
"parentReference": {
"driveId": "6F7D00BF-FC4D-4E62-9769-6AEA81F3A21B",
"id": "DCD0D3AD-8989-4F23-A5A2-2C086050513F"
},
"childrenOnly": true
}
Response
The following example shows the response.
HTTP/1.1 202 Accepted
Location: https://contoso.sharepoint.com/_api/v2.0/monitor/4A3407B5-88FC-4504-8B21-0AABD3412717
Monitoring is important because the copy operation with childrenOnly occurs across multiple operations.
Example 3: Copy the children in a folder with name conflict
The following example attempts to copy the children in a folder identified by {item-id} into a folder identified with a driveId and id value.
The destination already has the same name found at the source. The operation is accepted but it encounters a failure during processing.
Request
POST https://graph.microsoft.com/beta/me/drive/items/{item-id}/copy
Content-Type: application/json
{
"parentReference": {
"driveId": "6F7D00BF-FC4D-4E62-9769-6AEA81F3A21B",
"id": "DCD0D3AD-8989-4F23-A5A2-2C086050513F"
}
}
Response
The following example shows the response.
HTTP/1.1 202 Accepted
Location: https://contoso.sharepoint.com/_api/v2.0/monitor/4A3407B5-88FC-4504-8B21-0AABD3412717
Follow the monitor url.
{
"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"
}
}
To resolve this error, use the optional query parameter @microsoft.graph.conflictBehavior.
Example 4: Copy the children in a folder with name conflict setting conflictBehavior
The following example copies the children in a folder identified by {item-id} into a folder identified with a driveId and id value.
The optional query parameter @microsoft.graph.conflictBehavior is set to replace. The possible values are replace, rename, or fail.
The destination already has the same name found at the source.
Request
POST https://graph.microsoft.com/beta/me/drive/items/{item-id}/copy?@microsoft.graph.conflictBehavior=replace
Content-Type: application/json
{
"parentReference": {
"driveId": "6F7D00BF-FC4D-4E62-9769-6AEA81F3A21B",
"id": "DCD0D3AD-8989-4F23-A5A2-2C086050513F"
}
}
Response
The following example shows the response.
HTTP/1.1 202 Accepted
Location: https://contoso.sharepoint.com/_api/v2.0/monitor/4A3407B5-88FC-4504-8B21-0AABD3412717
Example 5: Copy the children in a folder from root
The following example attempts to copy the children in a folder identified by {item-id} (also known as root) into a folder identified with a driveId and id value.
The childrenOnly parameter isn't set to true.
The request fails because the copy operation can't be done in the root folder.
Request
POST https://graph.microsoft.com/beta/me/drive/items/root/copy
Content-Type: application/json
{
"parentReference": {
"driveId": "6F7D00BF-FC4D-4E62-9769-6AEA81F3A21B",
"id": "DCD0D3AD-8989-4F23-A5A2-2C086050513F"
}
}
Response
The following example shows the response.
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"
}
}
}
To resolve this error, set the childrenOnly parameter to true.
Example 6: Copy the children in a folder where source has more than 150 direct children
The following example attempts to copy the children in a folder identified by {item-id} into a folder identified with a driveId and id value.
The childrenOnly parameter is set to true. The drive item identified by {item-id} contains more than 150 direct children.
The request fails because the limit is 150 direct children.
Request
POST https://graph.microsoft.com/beta/me/drive/items/{item-id}/copy
Content-Type: application/json
{
"parentReference": {
"driveId": "6F7D00BF-FC4D-4E62-9769-6AEA81F3A21B",
"id": "DCD0D3AD-8989-4F23-A5A2-2C086050513F"
}
}
Response
The following example shows the response.
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"
}
}
}
To resolve this error, reorganize the source folder structure only to have 150 children.
Example 7: Copy the children where the source item is a file
The following example attempts to copy the children in a folder identified by {item-id} into a folder identified with a driveId and id value.
The {item-id} refers to a file, not a folder. The childrenOnly parameter is set to true.
The request fails since the {item-id} is a nonfolder driveItem.
Request
POST https://graph.microsoft.com/beta/me/drive/items/{item-id}/copy
Content-Type: application/json
{
"parentReference": {
"driveId": "6F7D00BF-FC4D-4E62-9769-6AEA81F3A21B",
"id": "DCD0D3AD-8989-4F23-A5A2-2C086050513F"
},
"childrenOnly": true
}
Response
The following example shows the response.
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""
}
}
}
Example 8: Copy the children in a folder with childrenOnly and name
The following example attempts to copy the children in a folder identified by {item-id} into a folder identified with a driveId and id value.
The childrenOnly parameter is set to true and specify a name value.
The request fails because childrenOnly and name can't be used together.
Request
POST https://graph.microsoft.com/beta/me/drive/items/{item-id}/copy
Content-Type: application/json
{
"parentReference": {
"driveId": "6F7D00BF-FC4D-4E62-9769-6AEA81F3A21B",
"id": "DCD0D3AD-8989-4F23-A5A2-2C086050513F"
},
"name": "contoso plan (copy).txt",
"childrenOnly": true
}
Response
The following example shows the response.
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""
}
}
}
Related content
For error information, see Error responses.
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per