driveItem: copy

名前空間: microsoft.graph

重要

Microsoft Graph の /beta バージョンの API は変更される可能性があります。 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。

driveItem のコピーを非同期に作成します。 必要に応じて、子アイテムのみをコピーしたり、新しい親フォルダーを指定したり、新しい名前を指定したりできます。 要求が受け入れられると、操作はキューに入れられ、非同期的に処理されます。 モニター URL を使用して、操作が完了するまでの進行状況を追跡します。

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

重要

  • driveItem のコピー時に、システム メタデータやカスタム メタデータなどのメタデータは保持されません。 代わりに、まったく新しい driveItem がターゲットの場所に作成されます。
  • ファイル バージョンは、 includeAllVersionHistory パラメーターが明示的に true に設定されている場合にのみ保持されます。 それ以外の場合は、最新バージョンのみがコピーされます。
  • アプリのみの認証を使用する場合、クロス地域コピーはサポートされません。
  • name 要求パラメーターも渡された場合に 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/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"
}

応答

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

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

応答

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

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 エラーが返されます。

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

要求

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

応答

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

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 に指示します。

要求

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

応答

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

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

応答

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

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

応答

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

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

例 7: 指定されていないルート フォルダーをコピーすると要求が無効になる childrenOnly

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

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

要求

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

応答

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: ファイルの子アイテムをコピーするときに無効な要求が表示される

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

要求

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
}

応答

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

応答

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

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

応答

非同期コピー操作の状態を追跡するには、場所 URL を使用します。 正常な応答は次のようになります。

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

関連コンテンツ

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

  • Last updated on