author | description | ms.date | title | ms.localizationpriority | ms.subservice | doc_type |
---|---|---|---|---|---|---|
spgraph-docs-team |
Asynchronously create a copy of a driveItem (including any children) under a new parent item or with a new name. |
09/10/2017 |
driveItem: copy |
medium |
sharepoint |
apiPageType |
Namespace: microsoft.graph
[!INCLUDE beta-disclaimer]
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.
[!INCLUDE national-cloud-support]
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.
[!INCLUDE permissions-table]
[!INCLUDE app-permissions]
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
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.
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
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.
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
.
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"
}
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
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
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.
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
}
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
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.
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.
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"
}
}
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
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.
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.
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"
}
}
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
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
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.
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"
}
}
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.
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.
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"
}
}
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.
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.
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
}
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""
}
}
}
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.
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
}
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""
}
}
}
For error information, see Error responses.