通过

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 追加保证新文件或文件夹名称唯一性的最低整数，并完成操作。

如果为源文件夹项指定 @microsoft.graph.conflictBehavior=replace ，则此 API 将 202 Accepted 返回响应。 在这种情况下，查询监视 URL 会报告错误 nameAlreadyExists 。 如果使用 参数 childrenOnly 指定此参数，则如果源项的子级中有任何文件夹项，则会发生 nameAlreadyExists 错误。

注意

conflictBehavior OneDrive 使用者不支持 参数。

请求正文

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

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

注意

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

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

如果将查询参数与 参数一起使用@microsoft.graph.conflictBehaviorchildrenOnly，则操作中的每个子级都将受指定 的约束@microsoft.graph.conflictBehavior。

响应

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

示例

示例 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

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

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

{
  "@odata.context": "https://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://https://contoso.sharepoint.com/sites/site2/_api/v2.0/drives/b!1YwGyNd6RUuVB42eCVw7ULlXybr_-09Br67iDGnYY-neBqwZd6jJRJbgCTx0On5n/items/016OGUCSF6Y2GOVW7725BZO354PWSELRRZ",
  "status": "completed"
}

示例 3：无法将文件项复制到具有同名的预先存在的项的文件夹

以下示例尝试将 标识 {item-id} 的文件项复制到 由 driveId 和 id 属性值标识的文件夹中。 在此示例中，目标已有一个具有相同名称的文件。 但是，由于请求未指定 @microsoft.graph.conflictBehavior 或 rename的replace查询参数值，因此操作被接受，但在处理过程中失败。

请求

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

以下示例演示通过访问对初始请求的 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"
  }
}

若要解决此错误，请使用可选查询参数 @microsoft.graph.conflictBehavior ，如下 一个示例所示。

示例 4：通过指定 @microsoft.graph.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：无法通过指定 为 replace 来复制包含文件夹项的 @microsoft.graph.conflictBehavior 子项

以下示例尝试将 标识 {item-id} 的文件夹中的子项复制到 由 driveId 和 id 值标识的文件夹中。 子项之一是文件夹项。 目标可能具有与源文件夹中的子级名称相冲突的项目。 请求尝试通过设置要替换的可选查询参数 @microsoft.graph.conflictBehavior 来解决潜在的名称冲突。 请求已接受，但监视 URL 报告失败。 如果至少有一个子项是文件夹项，则改用 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"
  },
  "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：将项目复制到目标文件夹并保留其版本历史记录

以下示例将 标识 {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"
  },
  "includeAllVersionHistory": true
}

响应

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

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

示例 7：未将 childreOnly 参数指定为 true，无法复制根文件夹中的子项

以下示例尝试将 标识的文件夹中 {item-id}的子项（也称为“root”）复制到 由 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"
  }
}

响应

访问监视 URL 会生成类似于以下示例的状态报告。

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：无法复制超过 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"
  },
  "childrenOnly": true
}

响应

访问监视 URL 会生成类似于以下示例的状态报告。

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 个子级的源文件夹结构。

示例 9：无法复制文件项的子项

以下示例尝试将 标识 {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
}

响应

访问监视 URL 会生成类似于以下示例的状态报告。

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

示例 10：无法通过指定 childOnly 和 name 请求正文参数来复制子项

以下示例尝试将 标识 {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""
    }
  }
}

相关内容

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