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 O comportamento predefinido é comunicar a falha.
replace Substituir item existente no site de destino.
rename Mude o nome do item.

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

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 com um driveId valor 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 as crianças numa pasta

O exemplo seguinte copia as crianças numa pasta identificada por {item-id} numa pasta identificada com um driveId valor 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

A monitorização é importante porque a operação de cópia com childrenOnly ocorre em várias operações.

Exemplo 3: Copiar as crianças numa pasta com conflito de nomes

O exemplo seguinte tenta copiar as crianças numa pasta identificada por {item-id} para uma pasta identificada com um driveId valor e id . O destino já tem o mesmo nome encontrado na origem. A operação é aceite, mas encontra uma 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

Siga o URL do monitor.

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

Exemplo 4: Copie as crianças numa pasta com a definição de conflito de nome ConflictBehavior

O exemplo seguinte copia as crianças numa pasta identificada por {item-id} numa pasta identificada com um driveId valor e id . O parâmetro @microsoft.graph.conflictBehavior de consulta opcional está definido para substituir. Os valores possíveis são replace, rename ou fail. O destino já tem o mesmo nome encontrado na origem.

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: Copiar operação preservar histórico de versões

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

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 6: Copiar as crianças numa pasta a partir da raiz

O exemplo seguinte tenta copiar as crianças numa pasta identificada por {item-id} (também conhecida como raiz) para uma pasta identificada com um driveId valor 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

O exemplo a seguir mostra a resposta.

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 7: Copie as crianças numa pasta onde a origem tenha mais de 150 subordinados diretos

O exemplo seguinte tenta copiar as crianças numa pasta identificada por {item-id} para uma pasta identificada com um driveId valor e id . O childrenOnly parâmetro está definido como verdadeiro. O item de unidade 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"
  }
}

Resposta

O exemplo a seguir mostra a resposta.

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 8: copiar os subordinados onde o item de origem é um ficheiro

O exemplo seguinte tenta copiar as crianças numa pasta identificada por {item-id} para uma pasta identificada com um driveId valor 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

O exemplo a seguir mostra a resposta.

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 9: Copiar os subordinados numa pasta com childrenOnly e nome

O exemplo seguinte tenta copiar as crianças numa pasta identificada por {item-id} para uma pasta identificada com um driveId valor e id . O childrenOnly parâmetro está definido como verdadeiro e especifica um name valor. O pedido falha porque childrenOnlyname e não pode ser utilizado em conjunto.

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.