Compartilhar via

driveItem: copiar

  • Artigo

Namespace: microsoft.graph

Importante

As APIs na versão /beta no Microsoft Graph estão sujeitas a alterações. Não há suporte para o uso dessas APIs em aplicativos de produção. Para determinar se uma API está disponível na v1.0, use o seletor Versão.

Crie de forma assíncrona uma cópia de um driveItem (incluindo crianças) num novo item principal ou com um novo nome. Depois de o pedido ser reconhecido, entra numa fila. A cópia real, incluindo quaisquer subsistemas, ocorre num momento indeterminado. O progresso é comunicado até que a operação seja concluída através da monitorização do progresso.

Esta API está disponível nas seguintes implementações de cloud nacionais.

Serviço global US Government L4 US Government L5 (DOD) China operada pela 21Vianet
✅ ✅ ✅ ✅

Permissões

Escolha a permissão ou permissões marcadas como menos privilegiadas para esta API. Utilize uma permissão ou permissões com privilégios mais elevados apenas se a sua aplicação o exigir. Para obter detalhes sobre as permissões delegadas e de aplicação, veja Tipos de permissão. Para saber mais sobre estas permissões, veja a referência de permissões.

Tipo de permissão Permissões com menos privilégios Permissões com privilégios superiores
Delegado (conta corporativa ou de estudante) Files.ReadWrite Files.ReadWrite.All, Sites.ReadWrite.All
Delegado (conta pessoal da Microsoft) Files.ReadWrite Files.ReadWrite.All
Aplicativo Files.ReadWrite.All Sites.ReadWrite.All

Observação

O SharePoint Embedded requer a FileStorageContainer.Selected permissão para aceder ao conteúdo do contentor. Esta permissão é diferente das mencionadas anteriormente. Para obter mais informações, veja Autorização e autenticação do SharePoint Embedded. Além das permissões do Microsoft Graph, a sua aplicação tem de ter as permissões ou permissões necessárias ao nível do tipo de contentor para chamar esta API. Para obter mais informações, veja Tipos de contentor. Para saber mais sobre as permissões ao nível do tipo de contentor, veja Autorização do SharePoint Embedded.

Solicitação 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 opcionais

Este método suporta o @microsoft.graph.conflictBehavior parâmetro de consulta para personalizar o comportamento quando ocorre um conflito.

Valor Descrição
fail Toda a operação falha quando ocorre um conflito. Este comportamento é a predefinição se não for especificada nenhuma opção.
replace O item de ficheiro pré-existente é eliminado e substituído pelo novo item quando ocorre um conflito. Esta opção só é suportada para itens de ficheiro. O novo item tem o mesmo nome que o antigo. O histórico do item antigo é eliminado.
rename Acrescenta o número inteiro mais baixo que garante a exclusividade ao nome do novo ficheiro ou pasta e conclui a operação.

Se especificar @microsoft.graph.conflictBehavior=replace para um item de pasta de origem, esta API devolve uma 202 Accepted resposta. Neste caso, consultar o URL de monitorização comunica um nameAlreadyExists erro. Se especificar este parâmetro com o childrenOnly parâmetro , ocorrerá um erro nameAlreadyExists se existirem itens de pasta nos subordinados do item de origem.

Observação

O conflictBehavior parâmetro não é suportado para o Consumidor do OneDrive.

Corpo da solicitação

Forneça um objeto JSON com os seguintes parâmetros no corpo da solicitação.

Nome Valor Descrição
parentReference ItemReference Opcional. Referência ao item principal no qual a cópia é criada.
nome string Opcional. O novo nome para a cópia. Se estas informações não forem fornecidas, é utilizado o mesmo nome que o original.
childrenOnly Booleano Opcional. Se definido como true, os subordinados do driveItem são copiados, mas não o driveItem em si. O valor padrão é false. Válido apenas em itens de pasta.
includeAllVersionHistory Booleano Opcional. Se estiver definido como true, o histórico de versões dos ficheiros de origem (versões principais e versões secundárias, se existirem) deve ser copiado para o destino, dentro do limite de definição da versão de destino. Se false, apenas a versão principal mais recente é copiada para o destino. O valor padrão é false.

Observação

O parentReference parâmetro deve incluir os driveId parâmetros e id para a pasta de destino.

Num único pedido, a opção childrenOnly copia 150 itens subordinados e, para os itens dos netos, aplica-se o limite do SharePoint. Para obter mais informações, veja Limitação do SharePoint

Se utilizar o @microsoft.graph.conflictBehavior parâmetro de consulta com o childrenOnly parâmetro , todos os subordinados na operação estarão sujeitos ao @microsoft.graph.conflictBehavior especificado.

Resposta

A resposta devolve detalhes sobre como monitorizar o progresso da cópia, ao aceitar o pedido. A resposta indica se a operação de cópia foi aceite ou rejeitada, por exemplo, se o nome do ficheiro de destino já está a ser utilizado.

Exemplos

Exemplo 1: Copiar um ficheiro para uma pasta

O exemplo seguinte copia um ficheiro identificado por {item-id} para uma pasta identificada pelos driveId valores e id . A nova cópia do ficheiro tem o nome contoso plan (copy).txt.

Solicitação

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

Resposta

O exemplo a seguir mostra a resposta.

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

Exemplo 2: copiar os itens subordinados numa pasta

O exemplo seguinte copia os subordinados numa pasta identificada por {item-id} numa pasta identificada pelos driveId valores e id . O childrenOnly parâmetro está definido como verdadeiro.

Solicitação

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
}

Resposta

O exemplo a seguir mostra a resposta.

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

O Location campo da resposta contém um URL de monitorização que pode utilizar para marcar o progresso da operação de cópia. Uma vez que as operações de cópia ocorrem de forma assíncrona e podem ser concluídas após um período de tempo não especificado, pode utilizar este URL repetidamente para controlar o respetivo status.

Para receber um relatório de status semelhante ao do exemplo seguinte, obtenha o URL no Location campo da resposta.

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

Exemplo 3: Falha ao copiar um item de ficheiro para uma pasta com um item pré-existente com o mesmo nome

O exemplo seguinte tenta copiar um item de ficheiro identificado por {item-id} para uma pasta identificada pelos valores de driveId propriedade e id . Neste exemplo, o destino já tem um ficheiro com o mesmo nome. No entanto, como o pedido não especifica um @microsoft.graph.conflictBehavior valor de parâmetro de consulta de ou renamereplace , a operação é aceite, mas falha durante o processamento.

Solicitação

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

Resposta

O exemplo a seguir mostra a resposta.

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

O exemplo seguinte mostra um exemplo status relatório obtido ao visitar o URL no valor do Location campo na resposta ao pedido 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 resolve este erro, utilize o parâmetro de consulta opcional @microsoft.graph.conflictBehavior, conforme visto no exemplo seguinte.

Exemplo 4: Copie um item de ficheiro para uma pasta com um item pré-existente com o mesmo nome ao especificar o @microsoft.graph.conflictBehavior parâmetro de consulta

O exemplo seguinte copia um item de ficheiro identificado por {item-id} para uma pasta identificada pelos driveId valores e id . Neste exemplo, o destino já tem um ficheiro com o mesmo nome. O parâmetro @microsoft.graph.conflictBehavior de consulta está definido para substituir. Os valores possíveis são replace, rename ou fail.

Solicitação

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

Resposta

O exemplo a seguir mostra a resposta.

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

Exemplo 5: Falha ao copiar itens subordinados que contêm um item de pasta ao especificar @microsoft.graph.conflictBehavior como substituir

O exemplo seguinte tenta copiar os itens subordinados numa pasta identificada por {item-id} para uma pasta identificada pelos driveId valores e id . Um dos itens subordinados é um item de pasta. O destino pode ter itens com nomes em colisão com as crianças na pasta de origem. O pedido tenta resolve potenciais conflitos de nomes ao definir o parâmetro @microsoft.graph.conflictBehavior de consulta opcional a substituir. O pedido é aceite, mas o URL de monitorização comunica falhas. Em vez disso, utilize rename ou fail se, pelo menos, uma das crianças for um item de pasta.

Solicitação

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
}

Resposta

O exemplo a seguir mostra a resposta.

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

Visitar o URL de monitorização gera um relatório de status semelhante ao seguinte exemplo.

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

Exemplo 6: copiar o item para uma pasta de destino e preservar o histórico de versões

O exemplo seguinte copia o item identificado por {item-id} para uma pasta identificada pelos driveId valores e id . Também copia o histórico de versões para a pasta de destino. Se o ficheiro de origem contiver mais versões do que a definição de limite de versão de destino, a cópia só transfere o número máximo de versões mais recentes que o site de destino permite.

Solicitação

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
}

Resposta

O exemplo a seguir mostra a resposta.

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

Exemplo 7: Falha ao copiar itens subordinados numa pasta raiz sem especificar o parâmetro childreOnly como verdadeiro

O exemplo seguinte tenta copiar os itens subordinados na pasta identificada por {item-id}, também conhecida como "raiz", para uma pasta identificada pelos driveId valores e id . O childrenOnly parâmetro não está definido como verdadeiro. O pedido falha porque a operação de cópia não pode ser feita na pasta raiz.

Solicitação

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

Resposta

Visitar o URL de monitorização gera um relatório de status semelhante ao seguinte exemplo.

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 resolve este erro, defina o childrenOnly parâmetro como verdadeiro.

Exemplo 8: Falha ao copiar mais de 150 itens subordinados diretos

O exemplo seguinte tenta copiar as crianças numa pasta identificada por {item-id} para uma pasta identificada pelos driveId valores e id . O childrenOnly parâmetro está definido como verdadeiro. O item da pasta de origem identificado por {item-id} contém mais de 150 subordinados diretos. O pedido falha porque o limite é de 150 subordinados diretos.

Solicitação

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
}

Resposta

Visitar o URL de monitorização gera um relatório de status semelhante ao seguinte exemplo.

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 resolve este erro, reorganize a estrutura da pasta de origem apenas para ter 150 subordinados.

Exemplo 9: Falha ao copiar os itens subordinados de um item de ficheiro

O exemplo seguinte tenta copiar os subordinados de um item de origem identificado por {item-id} para uma pasta identificada pelos driveId valores e id . Refere-se {item-id} a um ficheiro, não a uma pasta. O childrenOnly parâmetro está definido como verdadeiro. O pedido falha, uma vez {item-id} que é um driveItem que não é uma pasta.

Solicitação

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
}

Resposta

Visitar o URL de monitorização gera um relatório de status semelhante ao seguinte exemplo.

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

Exemplo 10: Falha ao copiar itens subordinados ao especificar os parâmetros childrenOnly e name request body

O exemplo seguinte tenta copiar os itens subordinados numa pasta identificada por {item-id} para uma pasta identificada pelos driveId valores e id . O corpo do pedido define o childrenOnly parâmetro como verdadeiro e também especifica um name valor. O pedido falha porque os childrenOnly parâmetros e name são mutuamente exclusivos.

Solicitação

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
}

Resposta

O exemplo a seguir mostra a resposta.

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

Conteúdo relacionado

Para obter informações sobre erros, veja Respostas de erros.