driveItem：copy

2025-06-01

命名空间：microsoft.graph

异步创建 driveItem 的副本，包括子项。可以指定新的父文件夹，或提供新名称。接受请求后，作将排队并异步处理。使用监视器 URL 跟踪进度，直到作完成。

重要

复制 driveItem 时不会保留元数据，包括系统元数据和自定义元数据。而是在目标位置创建全新的 driveItem。

复制 driveItem 时，不会保留权限。复制的 driveItem 继承目标文件夹的权限。

仅当参数显式设置为 true时，includeAllVersionHistory才会保留文件版本。否则，仅复制最新版本。

复制作限制为 30,000 个 driveItems。有关详细信息，请参阅 SharePoint 限制。

此 API 可用于以下国家级云部署。

全局服务	美国政府 L4	美国政府 L5 (DOD)	由世纪互联运营的中国
✅	✅	✅	✅

权限

为此 API 选择标记为最低特权的权限。只有在应用需要它时，才使用更高的特权权限。有关委派权限和应用程序权限的详细信息，请参阅权限类型。要了解有关这些权限的详细信息，请参阅权限参考。

权限类型	最低特权权限	更高特权权限
委派（工作或学校帐户）	Files.ReadWrite	Files.ReadWrite.All、Sites.ReadWrite.All
委派（个人 Microsoft 帐户）	Files.ReadWrite	Files.ReadWrite.All
应用程序	Files.ReadWrite.All	Sites.ReadWrite.All

注意

SharePoint Embedded 需要 FileStorageContainer.Selected 权限才能访问容器的内容。此权限不同于表中提到的权限。有关详细信息，请参阅 SharePoint Embedded 身份验证和授权。除了Microsoft Graph 权限外，应用还必须具有调用此 API 所需的容器类型级权限。有关详细信息，请参阅容器类型。若要详细了解容器类型级权限，请参阅 SharePoint Embedded 授权。

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

可选的查询参数

此方法支持 @microsoft.graph.conflictBehavior 查询参数，以在发生冲突时自定义行为。

值	说明
失败	发生冲突时，整个作将失败。如果未指定选项，则此行为是默认行为。
replace	发生冲突时，将删除预先存在的文件项并将其替换为新项。仅文件项支持此选项。新项的名称与旧项的名称相同。删除旧项的历史记录。
rename	追加保证新文件或文件夹名称唯一性的最低整数，并完成作。

注意

conflictBehavior OneDrive 使用者不支持参数。

参数 @microsoft.graph.conflictBehavior 应用于作期间复制的所有项。值 replace 仅支持文件;具有冲突的文件夹改用行为 fail 。

请求正文

在请求正文中，提供具有以下参数的 JSON 对象。

名称	值	说明
parentReference	ItemReference	可选。对创建副本的父项的引用。
name	string	可选。副本的新名称。如果未提供此信息，则使用与原始名称相同的名称。
childrenOnly	布尔值	可选。如果设置为 `true`，则复制 driveItem 的子级，但不会复制 driveItem 本身。默认值为 `false`。仅对文件夹项有效。
includeAllVersionHistory	布尔值	可选。如果设置为 `true`，则源文件版本历史记录 (主要版本和次要版本（如果有任何) 应复制到目标版本设置限制内）。如果 `false`为，则仅将最新的主版本复制到目标。默认值为 `false`。

注意

参数 parentReference 应包括 driveId 目标文件夹的和 id 参数。

响应

响应返回有关如何在接受请求时监视复制进度的详细信息。响应指示复制作是被接受还是被拒绝，例如，如果目标文件名已在使用中。

示例

示例 1：将文件复制到文件夹

此示例演示如何将标识 {item-id} 的文件复制到由和 driveIdid 值标识的目标文件夹中。为复制的文件指定了一个新名称 contoso plan (copy).txt。

请求

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

响应

以下示例显示了相应的响应。

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

使用标头中的 Location URL 监视异步复制作的进度。

示例 2：复制文件夹中的子项

该示例仅将文件夹的内容（而不是文件夹本身）复制到其他目标。源文件夹由 {item-id}标识，目标由其 driveId 和 id 值标识。

请求将 childrenOnly 参数设置为 true，仅当源项是文件夹时才有效。

请求

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
}

响应

以下示例显示了相应的响应。

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

Location响应字段包含可用于检查复制作进度的监视 URL。由于复制作以异步方式发生，并且可以在未指定的时间量后完成，因此可以重复使用此 URL 来跟踪其状态。

若要接收类似于以下示例中的状态报告，请在响应的字段中获取 URL Location 。

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

示例 3：由于目标文件夹中的名称冲突，复制失败

此示例显示尝试将文件复制到已包含同名文件的目标文件夹失败。请求未指定 @microsoft.graph.conflictBehavior 用于解决冲突的查询参数。

由于未提供冲突行为，因此 API 接受请求，但在处理过程中失败。该作返回错误 nameAlreadyExists 。

若要避免此错误，请使用值为 replace 或 rename的 @microsoft.graph.conflictBehavior 参数。

请求

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

响应

以下示例显示了相应的响应。

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

以下示例演示通过访问对初始请求的 Location 响应中字段值中的 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"
  }
}

示例 4：将文件复制到包含同名文件的文件夹

此示例演示如何将文件复制到已包含同名文件的文件夹。请求使用 @microsoft.graph.conflictBehavior 查询参数来处理命名冲突。

参数设置为 replace，指示 API 覆盖目标文件夹中的现有项。

的可能值为 @microsoft.graph.conflictBehavior ：

replace：替换现有文件。
rename：重命名新副本。
fail：如果存在命名冲突，则请求失败。

请求

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

响应

以下示例显示了相应的响应。

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

示例 5：使用复制具有文件夹冲突的子项时请求无效 `conflictBehavior=replace`

此示例显示尝试仅复制文件夹的子项的失败请求。请求将 childrenOnly 参数设置为 true ，并使用 @microsoft.graph.conflictBehavior 值为的 replace查询参数。

源文件夹中的一个或多个子项是文件夹。由于当 replace 冲突项是文件夹时不支持该行为，因此复制作失败。接受请求并返回监视 URL，但作最终会报告错误。

若要避免此错误，请在复制包含文件夹的replace子项时使用 rename 或 fail 而不是。

请求

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
}

响应

以下示例显示了相应的响应。

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

查询位置标头中的监视器 URL 以监视作的状态。失败的作可能会返回与以下示例类似的响应。

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

示例 6：复制项并保留版本历史记录

此示例演示如何将文件项复制到新位置，并在复制的项中包含其版本历史记录。参数 includeAllVersionHistory 在请求正文中设置为 true ，以指示应保留版本历史记录。

如果源文件的版本超过目标站点允许的版本数，则最初复制所有版本，然后遵循版本超过应用设置时的版本存储行为。

请求

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
}

响应

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

Location使用响应标头中的 URL 监视异步复制作的进度。

示例 7：在不使用的情况下复制根文件夹时请求无效 `childrenOnly`

此示例显示了一个失败的请求，该请求尝试通过将指定 root 为 {item-id}来复制根文件夹。请求不包括 childrenOnly 参数。由于根文件夹本身无法复制，并且 childrenOnly 未设置为 true，因此请求被拒绝并出现 invalidRequest 错误。

若要在不复制文件夹本身的情况下复制根文件夹的内容，请将 childrenOnly 参数设置为 true。

请求

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

响应

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

若要解决此错误，请将 childrenOnly 参数设置为 true。

示例 8：复制文件的子项时请求无效

此示例显示了一个失败的请求，该请求将作为文件的源项的参数设置为 childrenOnlytrue 。参数 childrenOnly 仅对文件夹项有效。由于文件不包含子项，因此请求被拒绝并出现 invalidRequest 错误。

请求

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
}

响应

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

示例 9：指定 `childrenOnly` 和时请求无效 `name`

此示例显示了一个失败的请求，该请求将 childrenOnly 参数设置为 true 以仅复制文件夹的子项，同时指定一个新 name 值。由于未复制文件夹本身，这两个参数不能一起使用。请求被拒绝并显示 invalidRequest 错误。

请求

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
}

响应

以下示例显示了相应的响应。

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

示例 10：成功的仅子级复制

此示例演示如何在不将文件夹本身) 复制到新目标的情况下复制文件夹 (的子项。源文件夹由 {item-id}标识，目标文件夹使用其 driveId 和 id指定。请求将 childrenOnly 属性设置为 true，该属性仅对文件夹项有效。

请求

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
}

响应

使用位置 URL 跟踪异步复制作的状态。成功的响应可能如下所示：

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

使用位置 URL 跟踪异步复制作的状态。成功的响应可能如下所示：

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

有关错误信息，请参阅错误响应。

通过

driveItem：copy

权限

HTTP 请求

可选的查询参数

请求正文

响应

示例

示例 1：将文件复制到文件夹

请求

响应

示例 2：复制文件夹中的子项

请求

响应

示例 3：由于目标文件夹中的名称冲突，复制失败

请求

响应

示例 4：将文件复制到包含同名文件的文件夹

请求

响应

示例 5：使用 复制具有文件夹冲突的子项时请求无效 conflictBehavior=replace

请求

响应

示例 6：复制项并保留版本历史记录

请求

响应

示例 7：在不使用 的情况下复制根文件夹时请求无效 childrenOnly

请求

响应

示例 8：复制文件的子项时请求无效

请求

响应

示例 9：指定 childrenOnly 和 时请求无效 name

请求

响应

示例 10：成功的仅子级复制

请求

响应

相关内容

反馈

其他资源

示例 5：使用复制具有文件夹冲突的子项时请求无效 `conflictBehavior=replace`

示例 7：在不使用的情况下复制根文件夹时请求无效 `childrenOnly`

示例 9：指定 `childrenOnly` 和时请求无效 `name`