Compartir a través de

driveItem: copiar

  • Artículo

Espacio de nombres: microsoft.graph

Importante

Las API de la versión /beta de Microsoft Graph están sujetas a cambios. No se admite el uso de estas API en aplicaciones de producción. Para determinar si una API está disponible en la versión 1.0, use el selector de Versión.

Cree de forma asincrónica una copia de un driveItem (incluidos los elementos secundarios) en un nuevo elemento primario o con un nuevo nombre. Una vez que se confirma la solicitud, entra en una cola. La copia real, incluidos los subelementos, se produce en un momento no determinado. El progreso se notifica hasta que la operación se completa mediante la supervisión del progreso.

Esta API está disponible en las siguientes implementaciones nacionales de nube.

Servicio global Gobierno de EE. UU. L4 Us Government L5 (DOD) China operada por 21Vianet
✅ ✅ ✅ ✅

Permissions

Elija el permiso o los permisos marcados como con privilegios mínimos para esta API. Use un permiso o permisos con privilegios superiores solo si la aplicación lo requiere. Para obtener más información sobre los permisos delegados y de aplicación, consulte Tipos de permisos. Para obtener más información sobre estos permisos, consulte la referencia de permisos.

Tipo de permiso Permisos con privilegios mínimos Permisos con privilegios más altos
Delegado (cuenta profesional o educativa) Files.ReadWrite Files.ReadWrite.All, Sites.ReadWrite.All
Delegado (cuenta personal de Microsoft) Files.ReadWrite Files.ReadWrite.All
Aplicación Files.ReadWrite.All Sites.ReadWrite.All

Nota:

SharePoint Embedded requiere el FileStorageContainer.Selected permiso para acceder al contenido del contenedor. Este permiso es diferente de los mencionados anteriormente. Para obtener más información, vea Autenticación y autorización de SharePoint Embedded. Además de los permisos de Microsoft Graph, la aplicación debe tener los permisos o permisos de nivel de tipo de contenedor necesarios para llamar a esta API. Para obtener más información, vea Tipos de contenedor. Para obtener más información sobre los permisos de nivel de tipo de contenedor, vea Autorización de SharePoint Embedded.

Solicitud 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

Parámetros de consulta opcionales

Este método admite el parámetro de @microsoft.graph.conflictBehavior consulta para personalizar el comportamiento cuando se produce un conflicto.

Valor Descripción
fail Se produce un error en toda la operación cuando se produce un conflicto. Este comportamiento es el predeterminado si no se especifica ninguna opción.
replace El elemento de archivo existente se elimina y se reemplaza por el nuevo elemento cuando se produce un conflicto. Esta opción solo se admite para los elementos de archivo. El nuevo elemento tiene el mismo nombre que el anterior. Se elimina el historial del elemento anterior.
rename Anexa el entero más bajo que garantiza la unicidad al nombre del nuevo archivo o carpeta y completa la operación.

Si especifica @microsoft.graph.conflictBehavior=replace para un elemento de carpeta de origen, esta API devuelve una 202 Accepted respuesta. En este caso, al consultar la dirección URL de supervisión se notifica un nameAlreadyExists error. Si especifica este parámetro con el childrenOnly parámetro , se produce un error nameAlreadyExists si hay elementos de carpeta en los elementos secundarios del elemento de origen.

Nota:

El conflictBehavior parámetro no se admite para el consumidor de OneDrive.

Cuerpo de la solicitud

En el cuerpo de la solicitud, proporcione un objeto JSON con los siguientes parámetros.

Nombre Valor Descripción
parentReference ItemReference Opcional. Referencia al elemento primario en el que se crea la copia.
name string Opcional. El nuevo nombre de la copia. Si no se proporciona esta información, se usa el mismo nombre que el original.
childrenOnly Booleano Opcional. Si se establece en true, los elementos secundarios del driveItem se copian, pero no el propio driveItem . El valor predeterminado es false. Válido solo en elementos de carpeta.
includeAllVersionHistory Booleano Opcional. Si se establece en true, el historial de versiones de los archivos de origen (versiones principales y versiones secundarias, si existe) debe copiarse en el destino, dentro del límite de configuración de la versión de destino. Si falsees , solo se copia la versión principal más reciente en el destino. El valor predeterminado es false.

Nota:

El parentReference parámetro debe incluir los driveId parámetros y id para la carpeta de destino.

En una sola solicitud, la childrenOnly opción copia 150 elementos secundarios y, para los elementos de los nietos, se aplica el límite de SharePoint. Para obtener más información, vea Limitación de SharePoint.

Si usa el parámetro de @microsoft.graph.conflictBehavior consulta con el childrenOnly parámetro , todos los elementos secundarios de la operación estarán sujetos al @microsoft.graph.conflictBehavior especificado.

Respuesta

La respuesta devuelve detalles sobre cómo supervisar el progreso de la copia, al aceptar la solicitud. La respuesta indica si la operación de copia se ha aceptado o rechazado, por ejemplo, si el nombre de archivo de destino ya está en uso.

Ejemplos

Ejemplo 1: Copia de un archivo en una carpeta

En el ejemplo siguiente se copia un archivo identificado por {item-id} en una carpeta identificada por los driveId valores y id . La nueva copia del archivo se denomina contoso plan (copy).txt.

Solicitud

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

Respuesta

En el ejemplo siguiente se muestra la respuesta.

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

Ejemplo 2: Copia de los elementos secundarios en una carpeta

En el ejemplo siguiente se copian los elementos secundarios de una carpeta identificada por {item-id} en una carpeta identificada por los driveId valores y id . El childrenOnly parámetro se establece en true.

Solicitud

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
}

Respuesta

En el ejemplo siguiente se muestra la respuesta.

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

El Location campo de la respuesta contiene una dirección URL de supervisión que puede usar para comprobar el progreso de la operación de copia. Dado que las operaciones de copia se producen de forma asincrónica y pueden finalizar después de una cantidad de tiempo no especificada, puede usar esta dirección URL repetidamente para realizar un seguimiento de su estado.

Para recibir un informe de estado similar al del ejemplo siguiente, obtenga la dirección URL en el Location campo de la respuesta.

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

Ejemplo 3: Error al copiar un elemento de archivo en una carpeta con un elemento preexistente con el mismo nombre

En el ejemplo siguiente se intenta copiar un elemento de archivo identificado por {item-id} en una carpeta identificada por los valores de propiedad driveId y id . En este ejemplo, el destino ya tiene un archivo con el mismo nombre. Sin embargo, dado que la solicitud no especifica un valor de parámetro de consulta de o replacerename, se acepta la operación, pero se produce un @microsoft.graph.conflictBehavior error durante el procesamiento.

Solicitud

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

Respuesta

En el ejemplo siguiente se muestra la respuesta.

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

En el ejemplo siguiente se muestra un informe de estado de ejemplo obtenido visitando la dirección URL en el valor del Location campo en la respuesta a la solicitud inicial.

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

Para resolver este error, use el parámetro de consulta opcional @microsoft.graph.conflictBehavior , como se muestra en el ejemplo siguiente.

Ejemplo 4: Copiar un elemento de archivo en una carpeta con un elemento existente con el mismo nombre especificando el parámetro de @microsoft.graph.conflictBehavior consulta

En el ejemplo siguiente se copia un elemento de archivo identificado por {item-id} en una carpeta identificada por los driveId valores y id . En este ejemplo, el destino ya tiene un archivo con el mismo nombre. El parámetro @microsoft.graph.conflictBehavior de consulta se establece para reemplazar. Los valores posibles sonreplace, rename o fail.

Solicitud

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

Respuesta

En el ejemplo siguiente se muestra la respuesta.

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

Ejemplo 5: Error al copiar elementos secundarios que contienen un elemento de carpeta especificando @microsoft.graph.conflictBehavior como reemplazar

En el ejemplo siguiente se intenta copiar los elementos secundarios de una carpeta identificada por {item-id} en una carpeta identificada por los driveId valores y id . Uno de los elementos secundarios es un elemento de carpeta. El destino puede tener elementos con nombres que colisionan con los elementos secundarios en la carpeta de origen. La solicitud intenta resolver posibles conflictos de nombres estableciendo el parámetro @microsoft.graph.conflictBehavior de consulta opcional que se va a reemplazar. Se acepta la solicitud, pero la dirección URL de supervisión notifica errores. En su lugar, use rename o fail si al menos uno de los elementos secundarios es un elemento de carpeta.

Solicitud

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
}

Respuesta

En el ejemplo siguiente se muestra la respuesta.

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

Al visitar la dirección URL de supervisión, se genera un informe de estado similar al siguiente ejemplo.

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

Ejemplo 6: Copiar elemento en una carpeta de destino y conservar su historial de versiones

En el ejemplo siguiente se copia el elemento identificado por {item-id} en una carpeta identificada por los driveId valores y id . También copia el historial de versiones en la carpeta de destino. Si el archivo de origen contiene más versiones que la configuración de límite de versión de destino, la copia solo transfiere el número máximo de versiones más recientes que permite el sitio de destino.

Solicitud

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
}

Respuesta

En el ejemplo siguiente se muestra la respuesta.

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

Ejemplo 7: Error al copiar elementos secundarios en una carpeta raíz sin especificar el parámetro childreOnly como true

En el ejemplo siguiente se intenta copiar los elementos secundarios de la carpeta identificada por {item-id}, también conocida como "raíz", en una carpeta identificada por los driveId valores y id . El childrenOnly parámetro no se establece en true. Se produce un error en la solicitud porque la operación de copia no se puede realizar en la carpeta raíz.

Solicitud

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

Respuesta

Al visitar la dirección URL de supervisión, se genera un informe de estado similar al siguiente ejemplo.

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

Para resolver este error, establezca el childrenOnly parámetro en true.

Ejemplo 8: Error al copiar más de 150 elementos secundarios directos

En el ejemplo siguiente se intenta copiar los elementos secundarios de una carpeta identificada por {item-id} en una carpeta identificada por los driveId valores y id . El childrenOnly parámetro se establece en true. El elemento de carpeta de origen identificado por {item-id} contiene más de 150 elementos secundarios directos. Se produce un error en la solicitud porque el límite es de 150 elementos secundarios directos.

Solicitud

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
}

Respuesta

Al visitar la dirección URL de supervisión, se genera un informe de estado similar al siguiente ejemplo.

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

Para resolver este error, reorganice la estructura de carpetas de origen solo para tener 150 elementos secundarios.

Ejemplo 9: Error al copiar los elementos secundarios de un elemento de archivo

En el ejemplo siguiente se intenta copiar los elementos secundarios de un elemento de origen identificado por {item-id} en una carpeta identificada por los driveId valores y id . {item-id} hace referencia a un archivo, no a una carpeta. El childrenOnly parámetro se establece en true. Se produce un error en la {item-id} solicitud, ya que es un objeto driveItem nofolder.

Solicitud

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
}

Respuesta

Al visitar la dirección URL de supervisión, se genera un informe de estado similar al siguiente ejemplo.

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

Ejemplo 10: Error al copiar elementos secundarios especificando los parámetros de cuerpo de solicitud childrenOnly y name

En el ejemplo siguiente se intenta copiar los elementos secundarios de una carpeta identificada por {item-id} en una carpeta identificada por los driveId valores y id . El cuerpo de la solicitud establece el childrenOnly parámetro en true y también especifica un name valor. Se produce un error en la solicitud, ya que los childrenOnly parámetros y name son mutuamente excluyentes.

Solicitud

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
}

Respuesta

En el ejemplo siguiente se muestra la respuesta.

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

Contenido relacionado

Para obtener información sobre errores, consulte Respuestas de error.