driveItem: copiar

Namespace: microsoft.graph

Crie uma cópia de um driveItem de forma assíncrona, incluindo itens filho. Você pode especificar uma nova pasta pai ou fornecer um novo nome. Depois que a solicitação é aceita, a operação é enfileirada e processada de forma assíncrona. Use a URL do monitor para acompanhar o progresso até que a operação seja concluída.

A operação de cópia é restrita a 30.000 driveItems. Para obter mais informações, consulte 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, um driveItem totalmente novo é criado no local de destino.
  • As versões de arquivo só são mantidas quando o parâmetro includeAllVersionHistory é definido explicitamente como true. Caso contrário, somente a versão mais recente será copiada.
  • A cópia entre áreas geográficas não é compatível ao usar a autenticação somente aplicativo.
  • Um problema conhecido ocorre quando o parâmetro de solicitação includeAllVersionHistory é ignorado se o parâmetro de solicitação de nome também é passado. Para evitar esse problema, execute a operação de cópia sem o parâmetro name primeiro e, em seguida, renomeie o item de destino quando a cópia for concluída.

Essa API está disponível nas seguintes implantações de nuvem nacional.

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

Permissões

Observação

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

Escolha a(s) permissão(s) marcada(s) como menos privilegiada(s) para essa API. Use uma permissão ou permissões com privilégios mais altos somente se o aplicativo exigir. Para obter detalhes sobre permissões delegadas e de aplicativo, consulte Tipos de permissão. Para saber mais sobre essas permissões, consulte a referência de permissões.

Tipo de permissão Permissões menos privilegiadas Permissões com privilégios mais elevados
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 acessar o conteúdo do contêiner. Essa permissão é diferente das mencionadas anteriormente. Além das permissões do Microsoft Graph, seu aplicativo deve ter as permissões de tipo de contêiner necessárias para chamar essa API. Para obter mais informações, consulte Autenticação e 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

Esse método dá suporte ao @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. Esse comportamento será o padrão se nenhuma opção for especificada.
replace O item de arquivo existente é excluído e substituído pelo novo item quando ocorre um conflito. Essa opção só tem suporte para itens de arquivo. O novo item tem o mesmo nome que o antigo. O histórico do item antigo é excluído.
rename Acrescenta o número inteiro mais baixo que garante exclusividade ao nome do novo arquivo ou pasta e conclui a operação.

Observação

Não há suporte para o conflictBehavior parâmetro 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 arquivos; pastas com conflitos usam 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 filhos do driveItem serão copiados, mas não o próprio driveItem . O valor padrão é false. Válido somente em itens de pasta.
includeAllVersionHistory Booleano Opcional. Se definido como true, o histórico de versão do arquivo de origem (versões principais e secundárias, se houver) deve ser copiado para o destino, dentro do limite de configuração de versão de destino. Em caso falsede, somente a versão principal mais recente será copiada para o destino. O valor padrão é false.
nome String Opcional. O novo nome para a cópia. Se essas informações não forem fornecidas, o mesmo nome será usado que o original.
parentReference itemReference Opcional. Referência ao item pai no qual a cópia é criada.

Observação

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

Resposta

A resposta retorna detalhes sobre como monitorar o progresso da cópia, ao aceitar a solicitação. A resposta indica se a operação de cópia foi aceita ou rejeitada; Por exemplo, se o nome do arquivo de destino já estiver em uso.

Exemplos

Exemplo 1: Copiar um arquivo para uma pasta

Este exemplo mostra como copiar um arquivo identificado por {item-id} em uma pasta de destino identificada por seus driveId valores and id . O arquivo copiado recebe um novo nome contoso plan (copy).txt.

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

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

Exemplo 2: Copiar os itens filho em uma pasta

O exemplo copia apenas o conteúdo de uma pasta, e não a pasta em si, para um destino diferente. A pasta de origem é identificada por {item-id}, e o destino é identificado por seus driveId valores and id .

A solicitação define o childrenOnly parâmetro como true, que é válido somente 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 uma URL de monitoramento que você pode usar para marcar o progresso da operação de cópia. Como 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, você pode usar essa URL repetidamente para acompanhar seu status.

Para receber um relatório de status semelhante ao do exemplo a seguir, OBTENHA a 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 nome na pasta de destino

Este exemplo mostra uma tentativa fracassada de copiar um arquivo para uma pasta de destino que já contém um arquivo com o mesmo nome. A solicitação não especifica um @microsoft.graph.conflictBehavior parâmetro de consulta para resolver o conflito.

Como nenhum comportamento de conflito é fornecido, a API aceita a solicitação, mas falha durante o processamento. A operação retorna um nameAlreadyExists erro.

Para evitar esse erro, use o parâmetro @microsoft.graph.conflictBehavior, 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 a seguir mostra um exemplo de relatório de status obtido visitando a URL no valor do Location campo na resposta à solicitação 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 arquivo para uma pasta que contém um arquivo com o mesmo nome

Este exemplo mostra como copiar um arquivo para uma pasta que já contém um arquivo com o mesmo nome. A solicitação usa o parâmetro de consulta @microsoft.graph.conflictBehavior para lidar com o conflito de nomenclatura.

O parâmetro é definido como replace, o que instrui a API a substituir o item existente na pasta de destino.

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

  • replace: substitua o arquivo existente.
  • rename: Renomeie a nova cópia.
  • fail: falhe na solicitação se houver 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: solicitação inválida ao copiar itens filho com conflitos de pasta usando conflictBehavior=replace

Este exemplo mostra uma solicitação com falha que tenta copiar apenas os itens filho de uma pasta. A solicitação define o parâmetro e true usa o childrenOnly@microsoft.graph.conflictBehavior parâmetro de consulta com um valor de replace.

Um ou mais itens filho na pasta de origem são pastas. Como não há suporte para o replace comportamento quando um item conflitante é uma pasta, a operação de cópia falha. A solicitação é aceita e uma URL de monitoramento é retornada, mas a operação acaba relatando um erro.

Para evitar esse erro, use rename ou fail em vez de replace ao copiar itens filho que incluem 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 a URL do monitor no cabeçalho do local para monitorar o status da operação. Uma operação com falha pode retornar uma resposta semelhante ao exemplo a seguir.

{
  "@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ão

Este exemplo mostra como copiar um item de arquivo para um novo local e incluir seu histórico de versão no item copiado. O includeAllVersionHistory parâmetro é definido como true no corpo da solicitação para indicar que o histórico de versão deve ser preservado.

Se o arquivo de origem tiver mais versões do que o permitido pelo site de destino, todas as versões serão copiadas inicialmente e, em seguida, o comportamento de armazenamento de versão quando as versões excederem as configurações aplicadas será 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

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

Exemplo 7: solicitação inválida ao copiar a pasta raiz sem childrenOnly

Este exemplo mostra uma solicitação com falha que tenta copiar a pasta raiz especificando root como .{item-id} A solicitação não inclui o childrenOnly parâmetro. Como a pasta raiz em si não pode ser copiada e childrenOnly não está definida como true, a solicitação é rejeitada 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 resolver esse erro, defina o childrenOnly parâmetro como true.

Exemplo 8: Solicitação inválida ao copiar os itens filho de um arquivo

Este exemplo mostra uma solicitação com falha que define o childrenOnly parâmetro para true um item de origem que é um arquivo. O childrenOnly parâmetro é válido somente para itens de pasta. Como os arquivos não contêm itens filho, a solicitação é rejeitada 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: solicitação inválida ao especificar ambos childrenOnly e name

Este exemplo mostra uma solicitação com falha que define o childrenOnly parâmetro para true copiar apenas os itens filho de uma pasta, ao mesmo tempo em que especifica um novo name valor. Esses dois parâmetros não podem ser usados juntos porque a pasta em si não está sendo copiada. A solicitação é rejeitada 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 somente para filhos bem-sucedida

Este exemplo demonstra como copiar os itens filho de uma pasta (sem copiar a pasta em si) para um novo destino. A pasta de origem é identificada por {item-id}, e a pasta de destino é especificada usando seu driveId e id. A solicitação define a childrenOnly propriedade como true, que é válida somente 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

Use a URL de Local para rastrear o status da operação de cópia assíncrona. Uma resposta bem-sucedida pode ser assim:

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

Use a URL de Local para rastrear o status da operação de cópia assíncrona. Uma resposta bem-sucedida pode ser assim:

{
  "@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, consulte Respostas de erro.

  • Last updated on