driveItem: copy

名前空間: microsoft.graph

子項目を含め、 driveItem のコピーを非同期的に作成します。新しい親フォルダーを指定することも、新しい名前を指定することもできます。要求が受け入れられると、操作はキューに入れられ、非同期的に処理されます。操作が完了するまで進行状況を追跡するには、モニター URL を使用します。

コピー操作は 30,000 driveItems に制限されています。詳細については、「 SharePoint の制限」を参照してください。

重要

システムメタデータやカスタムメタデータなど、 driveItem のコピー時にメタデータは保持されません。代わりに、完全に新しい driveItem がターゲットの場所に作成されます。
ファイルバージョンは、 includeAllVersionHistory パラメーターが明示的に true に設定されている場合にのみ保持されます。それ以外の場合は、最新バージョンのみがコピーされます。
アプリのみの認証を使用する場合、クロス geo コピーはサポートされていません。
名前要求パラメーターも渡された場合、includeAllVersionHistory 要求パラメーターが無視されると、既知の問題が発生します。この問題を回避するには、まず name パラメーターを指定せずにコピー操作を実行し、コピーの完了時にターゲット項目の名前を変更します。

この API は、次の国内クラウド展開で使用できます。

グローバルサービス	米国政府機関 L4	米国政府機関 L5 (DOD)	21Vianet が運営する中国
✅	✅	✅	✅

アクセス許可

注:

driveItem のコピー時にアクセス許可は保持されません。コピーされた driveItem は、コピー先フォルダーのアクセス許可を継承します

この API の最小特権としてマークされているアクセス許可またはアクセス許可を選択します。アプリで必要な場合にのみ、より高い特権のアクセス許可またはアクセス許可を使用します。委任されたアクセス許可とアプリケーションのアクセス許可の詳細については、「アクセス許可の種類」を参照してください。これらのアクセス許可の詳細については、「アクセス許可のリファレンス」を参照してください。

アクセス許可の種類	最小特権アクセス許可	より高い特権のアクセス許可
委任 (職場または学校のアカウント)	Files.ReadWrite	Files.ReadWrite.All、Sites.ReadWrite.All
委任 (個人用 Microsoft アカウント)	Files.ReadWrite	Files.ReadWrite.All
アプリケーション	Files.ReadWrite.All	Sites.ReadWrite.All

注:

SharePoint Embedded には、コンテナーのコンテンツにアクセスするための FileStorageContainer.Selected アクセス許可が必要です。このアクセス許可は、前に説明した権限とは異なります。 Microsoft Graph のアクセス許可に加えて、アプリには、この API を呼び出すために必要なコンテナーの種類のアクセス許可が必要です。詳細については、「 SharePoint Embedded の認証と承認」を参照してください。

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

オプションのクエリパラメーター

このメソッドは、競合が発生した場合の動作をカスタマイズするために、 @microsoft.graph.conflictBehavior クエリパラメーターをサポートします。

値	説明
fail	競合が発生すると、操作全体が失敗します。この動作は、オプションが指定されていない場合の既定値です。
replace	競合が発生すると、既存のファイル項目が削除され、新しい項目に置き換えられます。このオプションは、ファイル項目に対してのみサポートされます。新しい項目の名前は、古いものと同じです。古いアイテムの履歴が削除されます。
rename	新しいファイルまたはフォルダーの名前に一意性を保証する最も低い整数を追加し、操作を完了します。

注:

conflictBehavior パラメーターは、OneDrive コンシューマーではサポートされていません。

@microsoft.graph.conflictBehavior パラメーターは、操作中にコピーされたすべての項目に適用されます。 replace値はファイルでのみサポートされます。競合しているフォルダーでは、代わりにfail動作が使用されます。

要求本文

要求本文で、次のパラメーターを含む JSON オブジェクトを指定します。

名前	値	説明
childrenOnly	ブール値	省略可能。 `true`に設定すると、driveItem の子はコピーされますが、driveItem 自体はコピーされません。既定値は `false` です。フォルダー項目でのみ有効です。
includeAllVersionHistory	ブール値	省略可能。 `true`に設定されている場合、ソースファイルのバージョン履歴 (メジャーバージョンとマイナーバージョンがある場合) は、ターゲットバージョン設定の制限内でコピー先にコピーする必要があります。 `false`場合、最新のメジャーバージョンのみがコピー先にコピーされます。既定値は `false` です。
name	String	省略可能。コピーの新しい名前。この情報が指定されていない場合は、元の名前と同じ名前が使用されます。
parentReference	itemReference	省略可能。コピーが作成される親アイテムへの参照。

注:

parentReference パラメーターには、ターゲットフォルダーの driveId パラメーターと id パラメーターを含める必要があります。

応答

応答は、要求を受け入れると、コピーの進行状況を監視する方法に関する詳細を返します。応答は、コピー操作が受け入れられたか拒否されたかを示します。たとえば、コピー先のファイル名が既に使用されている場合です。

例

例 1: ファイルをフォルダーにコピーする

この例では、 {item-id} で識別されたファイルを、その driveId と id 値によって識別されるコピー先フォルダーにコピーする方法を示します。コピーされたファイルには、新しい名前 contoso plan (copy).txtが付けられます。

要求

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

応答

次の例は応答を示しています。

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

Location ヘッダーの URL を使用して、非同期コピー操作の進行状況を監視します。

例 2: フォルダー内の子項目をコピーする

この例では、フォルダー自体ではなくフォルダーの内容のみを別のコピー先にコピーします。ソースフォルダーは {item-id}によって識別され、宛先は driveId と id 値によって識別されます。

要求により、 childrenOnly パラメーターが true に設定されます。これは、ソース項目がフォルダーの場合にのみ有効です。

要求

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
}

応答

次の例は応答を示しています。

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

応答の Location フィールドには、コピー操作の進行状況をチェックするために使用できる監視 URL が含まれています。コピー操作は非同期的に実行され、不特定の時間が経過すると完了する可能性があるため、この URL を繰り返し使用してその状態を追跡できます。

次の例のような状態レポートを受信するには、応答の [ Location ] フィールドの URL を取得します。

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

例 3: コピー先フォルダーの名前の競合が原因でコピーが失敗する

この例では、同じ名前のファイルが既に含まれているコピー先フォルダーにファイルをコピーしようとして失敗したことを示します。要求では、競合を解決するための @microsoft.graph.conflictBehavior クエリパラメーターは指定されません。

競合動作は提供されないため、API は要求を受け入れますが、処理中に失敗します。操作は、 nameAlreadyExists エラーを返します。

このエラーを回避するには、 @microsoft.graph.conflictBehavior パラメーターを使用し、値 replace または renameします。

要求

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

応答

次の例は応答を示しています。

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

次の例は、最初の要求に対する応答の Location フィールドの値の URL にアクセスして取得した状態レポートの例を示しています。

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

例 4: 同じ名前のファイルを含むフォルダーにファイルをコピーする

この例では、同じ名前のファイルが既に含まれているフォルダーにファイルをコピーする方法を示します。要求では、@microsoft.graph.conflictBehavior クエリパラメーターを使用して、名前付けの競合を処理します。

パラメーターは replace に設定され、ターゲットフォルダー内の既存の項目を上書きするように API に指示します。

@microsoft.graph.conflictBehaviorに使用できる値は次のとおりです。

replace: 既存のファイルを置き換えます。
rename: 新しいコピーの名前を変更します。
fail: 名前付けの競合が存在する場合は、要求を失敗します。

要求

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

応答

次の例は応答を示しています。

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

例 5: を使用してフォルダーの競合が発生した子項目をコピーするときに要求が無効です `conflictBehavior=replace`

この例では、フォルダーの子項目のみをコピーしようとする失敗した要求を示します。要求は、childrenOnly パラメーターをtrueに設定し、値が replace の @microsoft.graph.conflictBehavior クエリパラメーターを使用します。

ソースフォルダー内の 1 つ以上の子項目はフォルダーです。競合するアイテムがフォルダーの場合、 replace 動作はサポートされていないため、コピー操作は失敗します。要求は受け入れられ、監視 URL が返されますが、最終的にはエラーが報告されます。

このエラーを回避するには、フォルダーを含む子アイテムをコピーするときにreplaceの代わりに、renameまたはfailを使用します。

要求

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
}

応答

次の例は応答を示しています。

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

location ヘッダーのモニター URL にクエリを実行して、操作の状態を監視します。失敗した操作は、次の例と同様の応答を返す場合があります。

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

例 6: 項目をコピーし、バージョン履歴を保持する

この例では、ファイル項目を新しい場所にコピーし、コピーした項目にそのバージョン履歴を含める方法を示します。 includeAllVersionHistory パラメーターは、バージョン履歴を保持する必要があることを示すために、要求本文でtrueに設定されます。

移行元ファイルのバージョンがコピー先サイトで許可されているよりも多い場合、すべてのバージョンが最初にコピーされ、バージョンが設定を超えたときのバージョンストレージの動作が適用されます。

要求

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
}

応答

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

非同期コピー操作の進行状況を監視するには、応答ヘッダーの Location URL を使用します。

例 7: を指定せずにルートフォルダーをコピーするときに要求が無効です `childrenOnly`

この例では、{item-id}として root を指定してルートフォルダーのコピーを試行する失敗した要求を示します。要求には、 childrenOnly パラメーターは含まれません。ルートフォルダー自体をコピーできず、 childrenOnly が true に設定されていないため、要求は invalidRequest エラーで拒否されます。

フォルダー自体をコピーせずにルートフォルダーの内容をコピーするには、 childrenOnly パラメーターを true に設定します。

要求

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

応答

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

このエラーを解決するには、 childrenOnly パラメーターを true に設定します。

例 8: ファイルの子項目をコピーするときに要求が無効です

この例では、ファイルであるソース項目のtrueにchildrenOnly パラメーターを設定する失敗した要求を示します。 childrenOnly パラメーターは、フォルダー項目に対してのみ有効です。ファイルには子項目が含まれていないため、要求は invalidRequest エラーで拒否されます。

要求

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
}

応答

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

例 9: `childrenOnly` との両方を指定するときに要求が無効です `name`

この例では、 childrenOnly パラメーターをフォルダーの子項目のみをコピーするように true に設定し、新しい name 値も指定する失敗した要求を示します。フォルダー自体がコピーされていないため、これら 2 つのパラメーターを一緒に使用することはできません。要求は、 invalidRequest エラーで拒否されます。

要求

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
}

応答

次の例は応答を示しています。

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

例 10: 成功した子のコピーのみ

この例では、(フォルダー自体をコピーせずに) フォルダーの子項目を新しい宛先にコピーする方法を示します。ソースフォルダーは {item-id}によって識別され、コピー先フォルダーはその driveId と idを使用して指定されます。要求は、 childrenOnly プロパティを true に設定します。これはフォルダー項目に対してのみ有効です。

要求

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
}

応答

[場所 URL] を使用して、非同期コピー操作の状態を追跡します。成功した応答は次のようになります。

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

[場所 URL] を使用して、非同期コピー操作の状態を追跡します。成功した応答は次のようになります。

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

エラー情報については、「エラー応答」を参照してください。

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-09-23

次の方法で共有

driveItem: copy

アクセス許可

HTTP 要求

オプションのクエリ パラメーター

要求本文

応答

例

例 1: ファイルをフォルダーにコピーする

要求

応答

例 2: フォルダー内の子項目をコピーする

要求

応答

例 3: コピー先フォルダーの名前の競合が原因でコピーが失敗する

要求

応答

例 4: 同じ名前のファイルを含むフォルダーにファイルをコピーする

要求

応答

例 5: を使用してフォルダーの競合が発生した子項目をコピーするときに要求が無効です conflictBehavior=replace

要求

応答

例 6: 項目をコピーし、バージョン履歴を保持する

要求

応答

例 7: を指定せずにルート フォルダーをコピーするときに要求が無効です childrenOnly

要求

応答

例 8: ファイルの子項目をコピーするときに要求が無効です

要求

応答

例 9: childrenOnly と の両方を指定するときに要求が無効です name

要求

応答

例 10: 成功した子のコピーのみ

要求

応答

関連コンテンツ

フィードバック

その他のリソース

オプションのクエリパラメーター

例 5: を使用してフォルダーの競合が発生した子項目をコピーするときに要求が無効です `conflictBehavior=replace`

例 7: を指定せずにルートフォルダーをコピーするときに要求が無効です `childrenOnly`

例 9: `childrenOnly` との両方を指定するときに要求が無効です `name`