Поделиться через

driveItem: copy

  • Статья

Пространство имен: microsoft.graph

Важно!

API версии /beta в Microsoft Graph могут быть изменены. Использование этих API в производственных приложениях не поддерживается. Чтобы определить, доступен ли API в версии 1.0, используйте селектор версий.

Асинхронно создайте копию элемента driveItem (включая все дочерние элементы) под новым родительским элементом или с новым именем. После подтверждения запроса он входит в очередь. Фактическое копирование, включая все подэлементы, происходит в неопределенное время. Ход выполнения сообщается до завершения операции путем отслеживания хода выполнения.

Этот API доступен в следующих национальных облачных развертываниях.

Глобальная служба Правительство США L4 Правительство США L5 (DOD) Китай управляется 21Vianet
✅ ✅ ✅ ✅

Разрешения

Выберите разрешение или разрешения, помеченные как наименее привилегированные для этого API. Используйте более привилегированное разрешение или разрешения только в том случае, если это требуется приложению. Дополнительные сведения о делегированных разрешениях и разрешениях приложений см. в разделе Типы разрешений. Дополнительные сведения об этих разрешениях см. в справочнике по разрешениям.

Тип разрешения Разрешения с наименьшими привилегиями Более высокие привилегированные разрешения
Делегированные (рабочая или учебная учетная запись) Files.ReadWrite Files.ReadWrite.All, Sites.ReadWrite.All
Делегированные (личная учетная запись Майкрософт) 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 Boolean Необязательное свойство. Если задано значение true, то копируются дочерние элементы элемента driveItem , но не сам объект driveItem . Значение по умолчанию — false. Допустимо только для элементов папки.
includeAllVersionHistory Boolean Необязательное свойство. Если задано значение true, журнал версий исходных файлов (основных и дополнительных версий, если таковые есть) следует скопировать в место назначения в пределах предельного значения целевой версии. Если falseзадано значение , в место назначения копируется только последняя основная версия. Значение по умолчанию — false.

Примечание.

Параметр parentReference должен включать driveId параметры и id для целевой папки.

В одном запросе childrenOnly параметр копирует 150 дочерних элементов, а для элементов внуков применяется ограничение SharePoint. Дополнительные сведения см. в разделе Ограничение SharePoint.

Если вы используете @microsoft.graph.conflictBehavior параметр запроса с параметром childrenOnly , то каждый дочерний элемент в операции будет подчиняться указанному @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 значение replace параметра запроса или rename, операция принимается, но завершается сбоем во время обработки.

Запрос

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-адреса в значении Location поля в ответе на первоначальный запрос.

{
  "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. Сбой копирования @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. Сбой копирования дочерних элементов путем указания параметров текста запроса childrenOnly и 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""
    }
  }
}

Связанные материалы

Сведения об ошибках см. в разделе Ответы на ошибки.