Compartilhar via

driveItem: copiar

Namespace: microsoft.graph

Crie uma cópia de um driveItem de forma assíncrona, incluindo itens subordinados. Pode especificar uma nova pasta principal ou fornecer um novo nome. Assim que o pedido for aceite, a operação é em fila de espera e processada de forma assíncrona. Utilize o URL do monitor para controlar o progresso até que a operação seja concluída.

A operação de cópia está restrita a 30 000 driveItems. Para obter mais informações, veja Limites do SharePoint.

Importante

  • Os metadados não são retidos quando um driveItem é copiado, incluindo metadados do sistema e metadados personalizados. Em vez disso, é criado um driveItem totalmente novo na localização de destino.
  • As versões de ficheiro só são mantidas quando o parâmetro includeAllVersionHistory está explicitamente definido como true. Caso contrário, apenas a versão mais recente é copiada.
  • A cópia entre áreas geográficas não é suportada ao utilizar a autenticação apenas de aplicações.
  • Um problema conhecido ocorre quando o parâmetro de pedido includeAllVersionHistory é ignorado se o parâmetro do pedido de nome também for transmitido. Para evitar este problema, execute primeiro a operação de cópia sem o parâmetro name e, em seguida, mude o nome do item de destino quando a cópia for concluída.

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

Observação

As permissões não são mantidas quando um driveItem é copiado. O driveItem copiado herda as permissões da pasta de destino

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. Além das permissões do Microsoft Graph, a sua aplicação tem de ter as permissões de tipo de contentor necessárias para chamar esta API. Para obter mais informações, veja Autorização e autenticaçã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.

Observação

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

O @microsoft.graph.conflictBehavior parâmetro é aplicado a todos os itens copiados durante a operação. O replace valor só é suportado para ficheiros; em vez disso, as pastas com conflitos utilizam o fail comportamento.

Corpo da solicitação

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

Nome Valor Descrição
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 definido como true, o histórico de versões do ficheiro 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.
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.
parentReference itemReference Opcional. Referência ao item principal no qual a cópia é criada.

Observação

O parâmetro parentReference deve incluir os parâmetros driveId e ID da pasta de destino.

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á estiver a ser utilizado.

Exemplos

Exemplo 1: Copiar um ficheiro para uma pasta

Este exemplo mostra como copiar um ficheiro identificado por {item-id} para uma pasta de destino identificada pelos respetivos driveId valores e id . É atribuído um novo nome contoso plan (copy).txtao ficheiro copiado.

Solicitação

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

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

Utilize o URL no Location cabeçalho para monitorizar o progresso da operação de cópia assíncrona.

Exemplo 2: copiar os itens subordinados numa pasta

O exemplo copia apenas o conteúdo de uma pasta, não a própria pasta, para um destino diferente. A pasta de origem é identificada por {item-id}e o destino é identificado pelos respetivos driveId valores e id .

O pedido define o childrenOnly parâmetro como verdadeiro, que só é válido quando o item de origem é uma pasta.

Solicitação

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
}

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

Exemplo 3: a cópia falha devido a um conflito de nomes na pasta de destino

Este exemplo mostra uma tentativa falhada de copiar um ficheiro para uma pasta de destino que já contém um ficheiro com o mesmo nome. O pedido não especifica um @microsoft.graph.conflictBehavior parâmetro de consulta para resolve o conflito.

Uma vez que não é fornecido nenhum comportamento de conflito, a API aceita o pedido, mas falha durante o processamento. A operação devolve um nameAlreadyExists erro.

Para evitar este erro, utilize o parâmetro @microsoft.graph.conflictBehavior, parâmetro com um valor de replace ou rename.

Solicitação

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

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

Exemplo 4: Copiar um ficheiro para uma pasta que contenha um ficheiro com o mesmo nome

Este exemplo mostra como copiar um ficheiro para uma pasta que já contém um ficheiro com o mesmo nome. O pedido utiliza o parâmetro de consulta @microsoft.graph.conflictBehavior para processar o conflito de nomenclatura.

O parâmetro está definido como replace, o que indica à API para substituir o item existente na pasta de destino.

Os valores possíveis para @microsoft.graph.conflictBehavior são:

  • replace: substitua o ficheiro existente.
  • rename: mudar o nome da nova cópia.
  • fail: falhe o pedido se existir um conflito de nomenclatura.

Solicitação

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

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: Pedido inválido ao copiar itens subordinados com conflitos de pastas com conflictBehavior=replace

Este exemplo mostra um pedido falhado que tenta copiar apenas os itens subordinados de uma pasta. O pedido define o childrenOnly parâmetro como true e utiliza o @microsoft.graph.conflictBehavior parâmetro de consulta com um valor de replace.

Um ou mais itens subordinados na pasta de origem são pastas. Uma vez que o replace comportamento não é suportado quando um item em conflito é uma pasta, a operação de cópia falha. O pedido é aceite e é devolvido um URL de monitorização, mas a operação, em última análise, comunica um erro.

Para evitar este erro, utilize rename ou fail em vez de replace quando copiar itens subordinados que incluam pastas.

Solicitação

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
}

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

Consulte o URL do monitor no cabeçalho da localização para monitorizar a status da operação. Uma operação falhada pode devolver uma resposta 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 um item e preservar o histórico de versões

Este exemplo mostra como copiar um item de ficheiro para uma nova localização e incluir o histórico de versões no item copiado. O includeAllVersionHistory parâmetro está definido como true no corpo do pedido para indicar que o histórico de versões deve ser preservado.

Se o ficheiro de origem tiver mais versões do que o site de destino permite, todas as versões são inicialmente copiadas e, em seguida, o comportamento de armazenamento da versão quando as versões excedem as definições aplicadas é seguido.

Solicitação

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
}

Resposta

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

Utilize o Location URL no cabeçalho da resposta para monitorizar o progresso da operação de cópia assíncrona.

Exemplo 7: Pedido inválido ao copiar a pasta raiz sem childrenOnly

Este exemplo mostra um pedido falhado que tenta copiar a pasta raiz ao especificar root como .{item-id} O pedido não inclui o childrenOnly parâmetro . Uma vez que a própria pasta raiz não pode ser copiada e childrenOnly não está definida como verdadeira, o pedido é rejeitado com um invalidRequest erro.

Para copiar o conteúdo da pasta raiz sem copiar a própria pasta, defina o childrenOnly parâmetro como true.

Solicitação

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

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 8: Pedido inválido ao copiar os itens subordinados de um ficheiro

Este exemplo mostra um pedido falhado que define o parâmetro true como para um item de origem childrenOnly que é um ficheiro. O childrenOnly parâmetro é válido apenas para itens de pasta. Uma vez que os ficheiros não contêm itens subordinados, o pedido é rejeitado com um erro invalidRequest.

Solicitação

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
}

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: Pedido inválido ao especificar e childrenOnlyname

Este exemplo mostra um pedido falhado que define o childrenOnly parâmetro como true para copiar apenas os itens subordinados de uma pasta, ao mesmo tempo que especifica um novo name valor. Estes dois parâmetros não podem ser utilizados em conjunto porque a própria pasta não está a ser copiada. O pedido é rejeitado com um invalidRequest erro.

Solicitação

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
}

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

Exemplo 10: cópia apenas para crianças com êxito

Este exemplo demonstra como copiar os itens subordinados de uma pasta (sem copiar a própria pasta) para um novo destino. A pasta de origem é identificada por {item-id}e a pasta de destino é especificada com o respetivo driveId e id. O pedido define a childrenOnly propriedade como true, que é válida apenas para itens de pasta.

Solicitação

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
}

Resposta

Utilize o URL de Localização para controlar a status da operação de cópia assíncrona. Uma resposta bem-sucedida pode ter o seguinte aspeto:

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

Utilize o URL de Localização para controlar a status da operação de cópia assíncrona. Uma resposta bem-sucedida pode ter o seguinte aspeto:

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

Conteúdo relacionado

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

  • Last updated on