driveItem: copy

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.

Crear una copia de un elemento de unidad de forma asincrónica. Opcionalmente, puede copiar exclusivamente los elementos secundarios, especificar una nueva carpeta principal 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 elementos de unidad. Para obtener más información, vea Límites de SharePoint.

Importante

  • Los metadatos no se conservan cuando se copia un elemento de unidad , incluidos los metadatos del sistema y los metadatos personalizados. En su lugar, se crea un elemento de unidad 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 copiará la versión más reciente.
  • La copia entre zonas geográficas no se admite cuando se usa la autenticación de solo aplicación.
  • Un problema conocido se produce cuando se omite el parámetro de solicitud includeAllVersionHistorysi también se pasa el parámetro de solicitud name. 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 en la nube nacional.

Servicio global Administración pública de EE. UU. Gobierno de EE. UU. L5 (DOD) China operado por 21Vianet
✅ ✅ ✅ ✅

Permissions

Nota:

Los permisos no se conservan cuando se copia un elemento de unidad. El elemento de unidad 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 uno o varios permisos con privilegios más altos 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 permiso FileStorageContainer.Selected 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, consulte 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 @microsoft.graph.conflictBehavior parámetro query 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 preexistente 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 eliminará el historial del elemento antiguo.
rename Anexa el entero más bajo que garantiza la singularidad del 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
solo para niños Booleano Opcional. Si se establece en true, se copian los elementos secundarios de driveItem , pero no el elemento de unidad en sí. El valor predeterminado es false. Solo es válido en elementos de carpeta.
includeAllVersionHistory Booleano Opcional. Si se establece en true, el historial de versiones del archivo de origen (versiones principales y secundarias, si las hay) debe copiarse en el destino, dentro del límite de configuración de versiones de destino. Si false, solo se copia en el destino la versión principal más reciente. 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 principal en el que se crea la copia.

Nota:

El parámetro parentReference debe incluir los parámetros driveId e id de 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 la operación de copia se aceptó o rechazó; Por ejemplo, si el nombre de archivo de destino ya está en uso.

Ejemplos

Ejemplo 1: Copiar un archivo en una carpeta

Este ejemplo 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/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

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

Ejemplo 2: Copiar los elementos secundarios en una carpeta

En el ejemplo se copia solo el contenido de una carpeta, no la carpeta en sí, a 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/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 un período de tiempo no especificado, puede usar esta dirección URL repetidamente para realizar un seguimiento de su estado.

Para recibir un informe de estado similar al del siguiente ejemplo, GET la 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: Error en la copia debido a un conflicto de nombres en la carpeta de destino

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

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

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

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 ejemplo de informe de estado obtenido visitando la URL del 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: Copiar un archivo en una carpeta que contiene un archivo con el mismo nombre

Este ejemplo 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.

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: 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 @microsoft.graph.conflictBehavior parámetro de consulta con un valor de replace.

Uno o más elementos secundarios de la carpeta de origen son carpetas. Como este replace comportamiento no se admite cuando un elemento en conflicto es una carpeta, se produce un error en la operación de copia. La solicitud se acepta y se devuelve una URL de supervisión, pero la operación finalmente notifica un error.

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

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

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 a la del 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: Copiar un elemento y conservar el 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 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, todas se copian inicialmente y se sigue el comportamiento de almacenamiento de versiones cuando las versiones superan la configuración aplicada.

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

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 archivo {item-id}. La solicitud no incluye el childrenOnly parámetro. Dado que la 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 carpeta en sí, establezca el childrenOnly parámetro en true.

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

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 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/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

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 true para copiar solo los elementos secundarios de una carpeta, al mismo tiempo que especifica un nuevo name valor. Estos dos parámetros no se pueden usar juntos porque la carpeta en sí no se copia. La solicitud se rechaza con un invalidRequest error.

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

Ejemplo 10: Copia solo para niños correcta

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

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

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 puede verse así:

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

{
  "@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 de error, consulte Respuestas de error.

  • Last updated on