driveItem: copy

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

Создайте копию driveItem асинхронно, включая дочерние элементы. Можно указать новую родительскую папку или указать новое имя. После принятия запроса операция помещается в очередь и обрабатывается асинхронно. Используйте URL-адрес монитора для отслеживания хода выполнения до завершения операции.

Операция копирования ограничена 30 000 driveItems. Дополнительные сведения см. в разделе Ограничения SharePoint.

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

Разрешения

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

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 параметр запроса для настройки поведения при возникновении конфликта.

Текст запроса

В тексте запроса предоставьте JSON-объект с указанными ниже параметрами.

Отклик

Ответ возвращает сведения о том, как отслеживать ход выполнения копирования после принятия запроса. Ответ указывает, была ли операция копирования принята или отклонена; например, если имя целевого файла уже используется.

Примеры

Пример 1. Копирование файла в папку

В этом примере показано, как скопировать файл, идентифицируемый , {item-id} в целевую папку, определяемую его driveId значениями и id . Скопированный файл получает новое имя 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

Используйте URL-адрес в заголовке Location , чтобы отслеживать ход выполнения асинхронной операции копирования.

Пример 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 .

Чтобы избежать этой ошибки, используйте параметр @microsoft.graph.conflictBehavior, со значением replace или rename.

Запрос

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

В следующем примере показан пример отчета о состоянии, полученного путем посещения 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"
  }
}

Пример 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-адрес мониторинга, но операция в конечном итоге сообщает об ошибке.

Чтобы избежать этой ошибки, используйте rename или fail вместо при копировании replace дочерних элементов, включающих папки.

Запрос

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 .

Чтобы скопировать содержимое корневой папки без копирования самой папки, задайте для параметра значение childrenOnlytrue.

Запрос

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. Недопустимый запрос при копировании дочерних элементов файла

В этом примере показан неудачный запрос, который задает childrenOnly параметру значение true для исходного элемента, который является файлом. Параметр 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. Недопустимый запрос при указании и childrenOnlyname

В этом примере показан неудачный запрос, который задает 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"
}

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

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