driveItem: kopieren

Namespace: microsoft.graph

Wichtig

Die APIs unter der /beta Version in Microsoft Graph können sich ändern. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt. Um festzustellen, ob eine API in v1.0 verfügbar ist, verwenden Sie die Version Selektor.

Erstellen Sie asynchron eine Kopie eines driveItem . Wahlweise können Sie ausschließlich die untergeordneten Elemente kopieren, einen neuen übergeordneten Ordner angeben oder einen neuen Namen angeben. Nachdem die Anforderung akzeptiert wurde, wird der Vorgang in die Warteschlange eingereiht und asynchron verarbeitet. Verwenden Sie die Überwachungs-URL , um den Fortschritt bis zum Abschluss des Vorgangs nachzuverfolgen.

Der Kopiervorgang ist auf 30.000 driveItems beschränkt. Weitere Informationen finden Sie unter SharePoint-Limits.

Wichtig

  • Metadaten werden nicht beibehalten, wenn ein driveItem kopiert wird, einschließlich Systemmetadaten und benutzerdefinierter Metadaten. Stattdessen wird am Zielspeicherort ein völlig neues driveItem erstellt.
  • Dateiversionen werden nur beibehalten, wenn der includeAllVersionHistory-Parameter explizit auf truegesetzt ist. Andernfalls wird nur die neueste Version kopiert.
  • Geoübergreifende Kopien werden nicht unterstützt, wenn die Authentifizierung nur über die App verwendet wird.
  • Ein bekanntes Problem tritt auf, wenn der includeAllVersionHistory-Anforderungsparameter ignoriert wird, wenn der name-Anforderungsparameter ebenfalls übergeben wird. Um dieses Problem zu vermeiden, führen Sie zuerst den Kopiervorgang ohne den Parameter name durch und benennen Sie das Zielelement nach Abschluss des Kopiervorgangs um.

Diese API ist in den folgenden nationalen Cloudbereitstellungen verfügbar.

Weltweiter Service US Government L4 US Government L5 (DOD) China, betrieben von 21Vianet
✅ ✅ ✅ ✅

Berechtigungen

Hinweis

Berechtigungen werden nicht beibehalten, wenn ein driveItem kopiert wird. Das kopierte driveItem erbt die Berechtigungen des Zielordners.

Wählen Sie die Berechtigungen aus, die für diese API als am wenigsten privilegiert markiert sind. Verwenden Sie eine höhere Berechtigung oder Berechtigungen nur, wenn Ihre App dies erfordert. Ausführliche Informationen zu delegierten Berechtigungen und Anwendungsberechtigungen finden Sie unter Berechtigungstypen. Weitere Informationen zu diesen Berechtigungen finden Sie in der Berechtigungsreferenz.

Berechtigungstyp Berechtigungen mit den geringsten Berechtigungen Berechtigungen mit höheren Berechtigungen
Delegiert (Geschäfts-, Schul- oder Unikonto) Files.ReadWrite Files.ReadWrite.All, Sites.ReadWrite.All
Delegiert (persönliches Microsoft-Konto) Files.ReadWrite Files.ReadWrite.All
Anwendung Files.ReadWrite.All Sites.ReadWrite.All

Hinweis

SharePoint Embedded benötigt die FileStorageContainer.Selected Berechtigung für den Zugriff auf den Inhalt des Containers. Diese Berechtigung unterscheidet sich von den zuvor erwähnten. Zusätzlich zu den Microsoft Graph-Berechtigungen muss Ihre App über die erforderlichen Containertypberechtigungen verfügen, um diese API aufzurufen. Weitere Informationen finden Sie unter SharePoint Embedded-Authentifizierung und -Autorisierung.

HTTP-Anforderung

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

Optionale Abfrageparameter

Diese Methode unterstützt den @microsoft.graph.conflictBehavior Abfrageparameter, um das Verhalten anzupassen, wenn ein Konflikt auftritt.

Wert Beschreibung
fail Der gesamte Vorgang schlägt fehl, wenn ein Konflikt auftritt. Dieses Verhalten ist die Standardeinstellung, wenn keine Option angegeben ist.
replace Wenn ein Konflikt auftritt, wird das bereits vorhandene Dateielement gelöscht und durch das neue Element ersetzt. Diese Option wird nur für Dateielemente unterstützt. Das neue Element hat denselben Namen wie das alte. Der Verlauf des alten Elements wird gelöscht.
rename Hängt die niedrigste Ganzzahl an, die Eindeutigkeit an den Namen der neuen Datei oder des neuen Ordners garantiert, und schließt den Vorgang ab.

Hinweis

Der conflictBehavior Parameter wird für OneDrive Consumer nicht unterstützt.

Der @microsoft.graph.conflictBehavior Parameter wird auf alle Elemente angewendet, die während des Vorgangs kopiert werden. Der replace Wert wird nur für Dateien unterstützt; Ordner mit Konflikten verwenden stattdessen das fail Verhalten.

Anforderungstext

Geben Sie im Anforderungstext ein JSON-Objekt mit den folgenden Parametern an.

Name Wert Beschreibung
children Only Boolescher Wert Optional. Wenn diese Einstellung festgelegt ist true, werden die untergeordneten Elemente des driveItem kopiert, nicht jedoch das driveItem selbst. Der Standardwert ist false. Nur gültig für Ordnerelemente.
includeAllVersionHistory Boolescher Wert Optional. Wenn festgelegt auf true, sollte der Versionsverlauf der Quelldatei (Haupt- und Nebenversionen, falls vorhanden) innerhalb des Zielversionseinstellungslimits auf das Ziel kopiert werden. If falsewird nur die neueste Hauptversion auf das Ziel kopiert. Der Standardwert ist false.
name Zeichenfolge Optional. Der neue Name der Kopie. Wenn diese Informationen nicht angegeben werden, wird derselbe Name wie im Original verwendet.
parentReference itemReference Optional. Verweis auf das übergeordnete Element, in dem die Kopie erstellt wird.

Hinweis

Der Parameter parentReference sollte die Parameter driveId und id für den Zielordner enthalten.

Antwort

Die Antwort gibt Details dazu zurück, wie der Fortschritt des Kopiervorgangs überwacht werden kann, wenn die Anforderung akzeptiert wird. Die Antwort gibt an, ob der Kopiervorgang akzeptiert oder abgelehnt wurde. Dies kann beispielsweise der Fall sein, wenn der Zieldateiname bereits verwendet wird.

Beispiele

Beispiel 1: Kopieren einer Datei in einen Ordner

In diesem Beispiel wird gezeigt, wie Sie eine durch identifizierte {item-id} Datei in einen Zielordner kopieren, der durch seine driveIdid und-Werte identifiziert wird. Die kopierte Datei erhält einen neuen Namen contoso plan (copy).txt.

Anforderung

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

Antwort

Das folgende Beispiel zeigt die Antwort.

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

Verwenden Sie die URL in der Location Kopfzeile, um den Fortschritt des asynchronen Kopiervorgangs zu überwachen.

Beispiel 2: Kopieren der untergeordneten Elemente in einem Ordner

In diesem Beispiel wird nur der Inhalt eines Ordners an einen anderen Bestimmungsort kopiert, nicht der Ordner selbst. Der Quellordner wird durch {item-id}identifiziert, und das Ziel wird durch seine driveId und-Werte id identifiziert.

Die Anforderung legt den childrenOnly Parameter auf "true" fest, der nur gültig ist, wenn das Quellelement ein Ordner ist.

Anforderung

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
}

Antwort

Das folgende Beispiel zeigt die Antwort.

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

Das Location Feld der Antwort enthält eine Überwachungs-URL, mit der Sie den Fortschritt des Kopiervorgangs überprüfen können. Da Kopiervorgänge asynchron erfolgen und nach einer unbestimmten Zeitspanne abgeschlossen werden können, können Sie diese URL wiederholt verwenden, um ihren Status nachzuverfolgen.

Um einen ähnlichen Status wie im folgenden Beispiel zu erhalten, ABRUFEN Sie die URL im Location Feld der Antwort.

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

Beispiel 3: Fehler beim Kopieren aufgrund eines Namenskonflikts im Zielordner

Dieses Beispiel zeigt einen fehlgeschlagenen Versuch, eine Datei in einen Zielordner zu kopieren, der bereits eine Datei mit demselben Namen enthält. In der Anforderung wird kein @microsoft.graph.conflictBehavior Abfrageparameter zur Lösung des Konflikts angegeben.

Da kein Konfliktverhalten angegeben wird, akzeptiert die API die Anforderung, schlägt aber bei der Verarbeitung fehl. Der Vorgang gibt einen nameAlreadyExists Fehler zurück.

Um diesen Fehler zu vermeiden, verwenden Sie den Parameter @microsoft.graph.conflictBehavior mit dem Wert replace oder rename.

Anforderung

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

Antwort

Das folgende Beispiel zeigt die Antwort.

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

Das folgende Beispiel zeigt einen Beispielbericht status der durch Aufrufen der URL im Wert des Felds Location in der Antwort auf die ursprüngliche Anforderung abgerufen wurde.

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

Beispiel 4: Kopieren einer Datei in einen Ordner, der eine Datei mit demselben Namen enthält

Dieses Beispiel zeigt, wie Sie eine Datei in einen Ordner kopieren, der bereits eine Datei mit demselben Namen enthält. Die Anforderung verwendet den Abfrageparameter @microsoft.graph.conflictBehavior , um den Namenskonflikt zu behandeln.

Der Parameter ist auf replacefestgelegt, wodurch die API angewiesen wird, das vorhandene Element im Zielordner zu überschreiben.

Anforderung

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

Antwort

Das folgende Beispiel zeigt die Antwort.

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

Beispiel 5: Ungültige Anforderung beim Kopieren von untergeordneten Elementen mit Ordnerkonflikten unter Verwendung conflictBehavior=replace

Dieses Beispiel zeigt eine fehlerhafte Anforderung, bei der versucht wird, nur die untergeordneten Elemente eines Ordners zu kopieren. Die Anforderung legt den childrenOnly Parameter fest true und verwendet den @microsoft.graph.conflictBehavior Abfrageparameter mit dem Wert .replace

Ein oder mehrere untergeordnete Elemente im Quellordner sind Ordner. Da dieses replace Verhalten nicht unterstützt wird, wenn ein in Konflikt stehendes Element ein Ordner ist, schlägt der Kopiervorgang fehl. Die Anforderung wird akzeptiert und eine Überwachungs-URL zurückgegeben, aber der Vorgang meldet letztendlich einen Fehler.

Um diesen Fehler zu vermeiden, verwenden Sie rename beim Kopieren von untergeordneten Elementen, die Ordner enthalten, ODERfail.replace

Anforderung

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
}

Antwort

Das folgende Beispiel zeigt die Antwort.

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

Fragen Sie die Monitor-URL im Locationheader ab, um den Status des Vorgangs zu überwachen. Ein fehlgeschlagener Vorgang kann eine ähnliche Antwort wie im folgenden Beispiel zurückgeben.

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

Beispiel 6: Kopieren eines Elements und Beibehalten des Versionsverlaufs

In diesem Beispiel wird gezeigt, wie Sie ein Dateielement an einen neuen Speicherort kopieren und den zugehörigen Versionsverlauf in das kopierte Element einschließen. Der includeAllVersionHistory Parameter wird im Anforderungstext auf true festgelegt, um anzugeben, dass der Versionsverlauf beibehalten werden soll.

Wenn die Quelldatei mehr Versionen enthält, als die Zielwebsite zulässt, werden zunächst alle Versionen kopiert, und dann wird das Versionsspeicherverhalten bei Überschreitung der angewendeten Einstellungen befolgt.

Anforderung

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
}

Antwort

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

Verwenden Sie die Location URL im Antwortheader, um den Fortschritt des asynchronen Kopiervorgangs zu überwachen.

Beispiel 7: Ungültige Anforderung beim Kopieren des Stammordners ohne childrenOnly

Dieses Beispiel zeigt eine fehlerhafte Anforderung, die versucht, den Stammordner zu kopieren, indem als angegeben root wird {item-id}. Die Anforderung enthält den childrenOnly Parameter nicht. Da der Stammordner selbst nicht kopiert werden kann und childrenOnly nicht auf "True" festgelegt ist, wird die Anforderung mit einem invalidRequest Fehler abgelehnt.

Um den Inhalt des Stammordners zu kopieren, ohne den Ordner selbst zu kopieren, setzen Sie den childrenOnly Parameter auf true.

Anforderung

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

Antwort

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

Um diesen Fehler zu beheben, legen Sie den childrenOnly Parameter auf true fest.

Beispiel 8: Ungültige Anforderung beim Kopieren der untergeordneten Elemente einer Datei

Dieses Beispiel zeigt eine fehlerhafte Anforderung, die den childrenOnly Parameter true für ein Quellelement, eine Datei, auf festlegt. Der childrenOnly Parameter ist nur für Ordnerelemente gültig. Da Dateien keine untergeordneten Elemente enthalten, wird die Anforderung mit einem invalidRequest-Fehler abgelehnt.

Anforderung

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
}

Antwort

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

Beispiel 9: Ungültige Anforderung bei Angabe sowohl als auch childrenOnlyname

Dieses Beispiel zeigt eine fehlerhafte Anforderung, die den childrenOnly Parameter so festlegt, dass true nur die untergeordneten Elemente eines Ordners kopiert werden, während gleichzeitig ein neuer name Wert angegeben wird. Diese beiden Parameter können nicht zusammen verwendet werden, da der Ordner selbst nicht kopiert wird. Die Anforderung wird mit einem invalidRequest Fehler abgelehnt.

Anforderung

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
}

Antwort

Das folgende Beispiel zeigt die Antwort.

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

Beispiel 10: Erfolgreiche Kopie nur für Kinder

Dieses Beispiel zeigt, wie die untergeordneten Elemente eines Ordners (ohne den Ordner selbst zu kopieren) in ein neues Ziel kopiert werden. Der Quellordner wird durch {item-id}identifiziert, und der Zielordner wird mit seinem driveId und idangegeben. Die Anforderung legt die childrenOnly Eigenschaft auf truefest, die nur für Ordnerelemente gültig ist.

Anforderung

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
}

Antwort

Verwenden Sie die Standort-URL, um den Status des asynchronen Kopiervorgangs nachzuverfolgen. Eine erfolgreiche Antwort könnte wie folgt aussehen:

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

Verwandte Inhalte

Fehlerinformationen finden Sie unter Fehlerantworten.

  • Last updated on