Compartir a través de

driveItem: copiar

Espacio de nombres: microsoft.graph

Cree una copia de un driveItem de forma asincrónica, incluidos los elementos secundarios. Puede especificar una nueva carpeta primaria o proporcionar un nuevo nombre. Una vez aceptada la solicitud, la operación se pone en cola y se procesa de forma asincrónica. Use la dirección URL del monitor para realizar un seguimiento del progreso hasta que se complete la operación.

La operación de copia está restringida a 30 000 driveItems. Para obtener más información, vea Límites de SharePoint.

Importante

  • Los metadatos no se conservan cuando se copia un driveItem , incluidos los metadatos del sistema y los metadatos personalizados. En su lugar, se crea un driveItem completamente nuevo en la ubicación de destino.
  • Las versiones de archivo solo se conservan cuando el parámetro includeAllVersionHistory se establece explícitamente en true. De lo contrario, solo se copia la versión más reciente.
  • No se admite la copia entre zonas geográficas cuando se usa la autenticación de solo aplicación.
  • Un problema conocido se produce cuando se omite el parámetro de solicitud includeAllVersionHistory si también se pasa el parámetro de solicitud de nombre . Para evitar este problema, realice primero la operación de copia sin el parámetro name y cambie el nombre del elemento de destino cuando se complete la copia.

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

Nota:

Los permisos no se conservan cuando se copia un driveItem. El driveItem copiado hereda los permisos de la carpeta de destino.

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. Además de los permisos de Microsoft Graph, la aplicación debe tener los permisos de tipo de contenedor necesarios para llamar a esta API. Para obtener más información, vea Autenticación y 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.

Nota:

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

El @microsoft.graph.conflictBehavior parámetro se aplica a todos los elementos copiados durante la operación. El replace valor solo se admite para archivos; las carpetas con conflictos usan el fail comportamiento en su lugar.

Cuerpo de la solicitud

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

Nombre Valor Descripción
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 del archivo 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.
name Cadena Opcional. El nuevo nombre de la copia. Si no se proporciona esta información, se usa el mismo nombre que el original.
parentReference itemReference Opcional. Referencia al elemento primario en el que se crea la copia.

Nota:

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

Respuesta

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

Ejemplos

Ejemplo 1: Copia de un archivo en una carpeta

En este ejemplo se muestra cómo copiar un archivo identificado por {item-id} en una carpeta de destino identificada por sus driveId valores y id . Al archivo copiado se le asigna un nuevo nombre contoso plan (copy).txt.

Solicitud

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

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

Use la dirección URL del Location encabezado para supervisar el progreso de la operación de copia asincrónica.

Ejemplo 2: Copia de los elementos secundarios en una carpeta

En el ejemplo solo se copia el contenido de una carpeta, no la propia carpeta, en un destino diferente. La carpeta de origen se identifica mediante {item-id}y el destino se identifica por sus driveId valores y id .

La solicitud establece el childrenOnly parámetro en true, que solo es válido cuando el elemento de origen es una carpeta.

Solicitud

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
}

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

Ejemplo 3: Se produce un error en la copia debido a un conflicto de nombres en la carpeta de destino

En este ejemplo se muestra un error al intentar copiar un archivo en una carpeta de destino que ya contiene un archivo con el mismo nombre. La solicitud no especifica un parámetro de @microsoft.graph.conflictBehavior consulta para resolver el conflicto.

Dado que no se proporciona ningún comportamiento de conflicto, la API acepta la solicitud, pero produce un error durante el procesamiento. La operación devuelve un nameAlreadyExists error.

Para evitar este error, use el parámetro @microsoft.graph.conflictBehavior, con un valor de replace o rename.

Solicitud

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

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

Ejemplo 4: Copia de un archivo en una carpeta que contiene un archivo con el mismo nombre

En este ejemplo se muestra cómo copiar un archivo en una carpeta que ya contiene un archivo con el mismo nombre. La solicitud usa el parámetro de consulta @microsoft.graph.conflictBehavior para controlar el conflicto de nomenclatura.

El parámetro se establece en replace, que indica a la API que sobrescriba el elemento existente en la carpeta de destino.

Los valores posibles para @microsoft.graph.conflictBehavior son:

  • replace: reemplace el archivo existente.
  • rename: cambie el nombre de la nueva copia.
  • fail: se produce un error en la solicitud si existe un conflicto de nomenclatura.

Solicitud

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

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: Solicitud no válida al copiar elementos secundarios con conflictos de carpeta mediante conflictBehavior=replace

En este ejemplo se muestra una solicitud con error que intenta copiar solo los elementos secundarios de una carpeta. La solicitud establece el childrenOnly parámetro en true y usa el parámetro de @microsoft.graph.conflictBehavior consulta con un valor de replace.

Uno o varios elementos secundarios de la carpeta de origen son carpetas. Dado que el replace comportamiento no se admite cuando un elemento en conflicto es una carpeta, se produce un error en la operación de copia. Se acepta la solicitud y se devuelve una dirección URL de supervisión, pero la operación notifica un error en última instancia.

Para evitar este error, use rename o fail en lugar de replace al copiar elementos secundarios que incluyan carpetas.

Solicitud

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
}

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

Consulte la dirección URL del monitor en el encabezado de ubicación para supervisar el estado de la operación. Una operación con errores puede devolver una respuesta similar al ejemplo siguiente.

{
  "@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: Copia de un elemento y conservación del historial de versiones

En este ejemplo se muestra cómo copiar un elemento de archivo en una nueva ubicación e incluir su historial de versiones en el elemento copiado. El includeAllVersionHistory parámetro se establece true en en el cuerpo de la solicitud para indicar que se debe conservar el historial de versiones.

Si el archivo de origen tiene más versiones de las que permite el sitio de destino, se copian inicialmente todas las versiones y, a continuación, se sigue el comportamiento de almacenamiento de versiones cuando las versiones superan la configuración aplicada.

Solicitud

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
}

Respuesta

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

Use la Location dirección URL del encabezado de respuesta para supervisar el progreso de la operación de copia asincrónica.

Ejemplo 7: Solicitud no válida al copiar la carpeta raíz sin childrenOnly

En este ejemplo se muestra una solicitud con error que intenta copiar la carpeta raíz especificando root como {item-id}. La solicitud no incluye el childrenOnly parámetro . Dado que la propia carpeta raíz no se puede copiar y childrenOnly no se establece en true, la solicitud se rechaza con un invalidRequest error.

Para copiar el contenido de la carpeta raíz sin copiar la propia carpeta, establezca el childrenOnly parámetro en true.

Solicitud

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

Respuesta

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: Solicitud no válida al copiar los elementos secundarios de un archivo

En este ejemplo se muestra una solicitud con error que establece el childrenOnly parámetro en true para un elemento de origen que es un archivo. El childrenOnly parámetro solo es válido para los elementos de carpeta. Dado que los archivos no contienen elementos secundarios, la solicitud se rechaza con un error invalidRequest.

Solicitud

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
}

Respuesta

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 9: Solicitud no válida al especificar y childrenOnlyname

En este ejemplo se muestra una solicitud con error que establece el childrenOnly parámetro en true para copiar solo los elementos secundarios de una carpeta, al tiempo que se especifica un nuevo name valor. Estos dos parámetros no se pueden usar juntos porque la propia carpeta no se está copiando. La solicitud se rechaza con un invalidRequest error.

Solicitud

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
}

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

Ejemplo 10: Copia correcta de elementos secundarios

En este ejemplo se muestra cómo copiar los elementos secundarios de una carpeta (sin copiar la propia carpeta) en un nuevo destino. La carpeta de origen se identifica mediante {item-id}y la carpeta de destino se especifica mediante sus driveId y id. La solicitud establece la childrenOnly propiedad en true, que solo es válida para los elementos de carpeta.

Solicitud

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
}

Respuesta

Use la dirección URL de ubicación para realizar un seguimiento del estado de la operación de copia asincrónica. Una respuesta correcta podría tener este aspecto:

HTTP/1.1 202 Accepted
Location: https://contoso.sharepoint.com/sites/FromSite/_api/v2.1/monitor/780293e6-07b3-4544-a126-fea909efcc84

Use la dirección URL de ubicación para realizar un seguimiento del estado de la operación de copia asincrónica. Una respuesta correcta podría tener este aspecto:

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

Contenido relacionado

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

  • Last updated on