通过

driveItem：copy

  • 项目

命名空间：microsoft.graph

重要

Microsoft Graph /beta 版本下的 API 可能会发生更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 是否在 v1.0 中可用，请使用 版本 选择器。

异步创建 driveItem (包括新父项下或具有新名称的任何子项) 的副本。 确认请求后，它将进入队列。 实际复制（包括任何子项）在不确定的时间进行。 通过 监视进度，将报告进度，直到操作完成。

此 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 使用者不支持 参数。

请求正文

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

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

注意

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

在单个请求中 childrenOnly ，选项复制 150 个子项，对于孙子项，将应用 SharePoint 限制。 有关详细信息，请参阅 SharePoint 限制

响应

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

示例

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

以下示例将标识的文件 {item-id} 复制到使用 driveId 和 id 值标识的文件夹中。 文件的新副本名为 contoso plan (copy).txt。

请求

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

响应

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

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

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

以下示例将 标识 {item-id} 的文件夹中的子级复制到使用 driveId 和 id 值标识的文件夹中。 参数 childrenOnly 设置为 true。

请求

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
}

响应

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

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

监视非常重要，因为使用 childrenOnly 的复制操作跨多个操作进行。

示例 3：复制名称有冲突的文件夹中的子级

以下示例尝试将 标识 {item-id} 的文件夹中的子级复制到使用 driveId 和 id 值标识的文件夹中。 目标已具有在源中找到的相同名称。 操作已接受，但在处理过程中遇到失败。

请求

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

响应

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

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

按照监视器 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"
  }
}

若要解决此错误，请使用可选查询参数 @microsoft.graph.conflictBehavior。

示例 4：复制具有名称冲突设置 conflictBehavior 的文件夹中的子级

以下示例将 标识 {item-id} 的文件夹中的子级复制到使用 driveId 和 id 值标识的文件夹中。 可选查询参数 @microsoft.graph.conflictBehavior 设置为替换。 可取值包括 replace、rename 或 fail。 目标已具有在源中找到的相同名称。

请求

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

响应

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

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

示例 5：复制操作保留版本历史记录

以下示例将 标识 {item-id} 的项复制到使用 driveId 和 id 值标识的文件夹中。 它还会将版本历史记录复制到目标文件夹。 如果源文件包含 20 个版本，并且目标版本限制设置为 10，则副本仅传输目标站点允许的最大版本数（从最新版本开始）。

请求

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
}

响应

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

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

示例 6：从根目录复制文件夹中的子级

以下示例尝试将 (也称为根) 标识 {item-id} 的文件夹中的子级复制到使用 driveId 和 id 值标识的文件夹中。 参数 childrenOnly 未设置为 true。 请求失败，因为无法在根文件夹中执行复制操作。

请求

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

响应

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

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。

示例 7：复制源包含 150 个以上直接子级的文件夹中的子级

以下示例尝试将 标识 {item-id} 的文件夹中的子级复制到使用 driveId 和 id 值标识的文件夹中。 参数 childrenOnly 设置为 true。 标识 {item-id} 的驱动器项包含 150 多个直接子级。 请求失败，因为限制为 150 个直接子级。

请求

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

响应

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

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

若要解决此错误，请重新组织仅包含 150 个子级的源文件夹结构。

示例 8：复制源项为文件的子级

以下示例尝试将 标识 {item-id} 的文件夹中的子级复制到使用 driveId 和 id 值标识的文件夹中。 是指 {item-id} 文件，而不是文件夹。 参数 childrenOnly 设置为 true。 请求失败， {item-id} 因为 是非旧 driveItem。

请求

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
}

响应

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

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 和名称的文件夹中的子级

以下示例尝试将 标识 {item-id} 的文件夹中的子级复制到使用 driveId 和 id 值标识的文件夹中。 参数 childrenOnly 设置为 true 并指定值 name 。 请求失败，因为 childrenOnly 和 name 不能一起使用。

请求

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
}

响应

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

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

相关内容

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