次の方法で共有

driveItem: copy

  • [アーティクル]

名前空間: microsoft.graph

重要

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

新しい親項目の下または新しい名前を使用して 、driveItem (すべての子を含む) のコピーを非同期的に作成します。 要求が確認されると、キューに入ります。 サブ項目を含む実際のコピーは、未確定の時点で行われます。 進行状況は、進行状況を 監視して操作が完了するまで報告されます。

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

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

アクセス許可

この 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 アクセス許可が必要です。 このアクセス許可は、前に説明した権限とは異なります。 詳細については、「 SharePoint Embedded の認証と承認」を参照してください。 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 新しいファイルまたはフォルダーの名前に一意性を保証する最も低い整数を追加し、操作を完了します。

ソース フォルダー項目に @microsoft.graph.conflictBehavior=replace を指定すると、この API は 202 Accepted 応答を返します。 この場合、監視 URL に対してクエリを実行すると、 nameAlreadyExists エラーが報告されます。 childrenOnly パラメーターでこのパラメーターを指定すると、ソース 項目の子にフォルダー項目がある場合に nameAlreadyExists エラーが発生します。

注:

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

要求本文

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

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

注:

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

1 つの要求で、 childrenOnly オプションは 150 個の子項目をコピーし、孫アイテムの場合は SharePoint の制限が適用されます。 詳細については、「SharePoint の制限事項」を参照してください。

childrenOnly パラメーターで @microsoft.graph.conflictBehavior クエリ パラメーターを使用する場合、操作内のすべての子は、指定した@microsoft.graph.conflictBehaviorの対象になります。

応答

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

例

例 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

例 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://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://https://contoso.sharepoint.com/sites/site2/_api/v2.0/drives/b!1YwGyNd6RUuVB42eCVw7ULlXybr_-09Br67iDGnYY-neBqwZd6jJRJbgCTx0On5n/items/016OGUCSF6Y2GOVW7725BZO354PWSELRRZ",
  "status": "completed"
}

例 3: 同じ名前の既存の項目を持つフォルダーにファイル項目をコピーできない

次の例では、 {item-id} によって識別されたファイル項目を、 driveId で識別されるフォルダーにコピーし、プロパティ値を id します。 この例では、変換先に同じ名前のファイルが既に含まれています。 ただし、要求では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"
  }
}

このエラーを解決するには、次の例に示すように、省略可能なクエリ パラメーター @microsoft.graph.conflictBehavior を使用します。

例 4: @microsoft.graph.conflictBehavior クエリ パラメーターを指定して、同じ名前の既存の項目を含むフォルダーにファイル項目をコピーする

次の例では、 {item-id} によって識別されたファイル項目を、 driveId および id 値によって識別されるフォルダーにコピーします。 この例では、変換先に同じ名前のファイルが既に含まれています。 置き換えるクエリ パラメーター @microsoft.graph.conflictBehavior が設定されています。 使用可能な値: 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"
  }
}

応答

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

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

例 5: 置き換えとして @microsoft.graph.conflictBehavior を指定して、フォルダー項目を含む子項目をコピーできない

次の例では、 {item-id} によって識別されるフォルダー内の子項目を、 driveId で識別されるフォルダーにコピーし、値を id します。 子項目の 1 つはフォルダー項目です。 コピー先には、ソース フォルダーの子に名前を照合する項目が含まれている場合があります。 要求は、置き換えるオプションのクエリ パラメーター @microsoft.graph.conflictBehavior を設定することで、潜在的な名前の競合を解決しようとします。 要求は受け入れられますが、監視 URL によってエラーが報告されます。 代わりに、少なくとも 1 つの子がフォルダーアイテムの場合は、 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

監視 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: アイテムをコピー先フォルダーにコピーし、そのバージョン履歴を保持する

次の例では、 {item-id} で識別された項目を、 driveId と id 値によって識別されるフォルダーにコピーします。 また、バージョン履歴がターゲット フォルダーにコピーされます。 コピー元ファイルに、コピー先のバージョン制限設定よりも多くのバージョンが含まれている場合、コピー先サイトで許可されている最新バージョンの最大数のみが転送されます。

要求

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

例 7: childreOnly パラメーターを true として指定せずにルート フォルダー内の子項目をコピーできない

次の例では、 {item-id}によって識別されるフォルダー内の子項目 ("ルート" とも呼ばれます) を、 driveId および id 値によって識別されるフォルダーにコピーしようとしています。 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"
  }
}

応答

監視 URL にアクセスすると、次の例のような状態レポートが生成されます。

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: 150 を超える直接子項目をコピーできない

次の例では、 {item-id} によって識別されたフォルダー内の子を、 driveId と id の値によって識別されるフォルダーにコピーしようとしています。 childrenOnly パラメーターは true に設定されます。 {item-id}によって識別されるソース フォルダー項目には、150 を超える直接の子が含まれています。 制限は 150 個の直接子であるため、要求は失敗します。

要求

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 400 Bad Request
Content-Type: application/json
Content-Length: 341

{
  "error":
  {
    "code": "invalidRequest",
    "message": "Direct child count limit exceeded. Cannot copy children only when there are more than 150 direct children.",
    "innerError":
    {
      "code": "directChildrenLimitExceeded",
      "date": "2023-12-11T04:26:35",
      "request-id": "8f897345980-f6f3-49dd-83a8-a3064eeecdf8",
      "client-request-id": "50a0er33-4567-3f6c-01bf-04d144fc8bbe"
    }
  }
}

このエラーを解決するには、ソース フォルダー構造を再構成して、150 個の子のみを含めます。

例 9: ファイル項目の子項目をコピーできない

次の例では、 {item-id} によって識別されるソース項目の子を、 driveId および id 値によって識別されるフォルダーにコピーしようとしています。 {item-id}は、フォルダーではなくファイルを参照します。 childrenOnly パラメーターは true に設定されます。 {item-id}が非フォルダー driveItem であるため、要求は失敗します。

要求

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

例 10: childOnly パラメーターと name 要求本文パラメーターの両方を指定して子項目をコピーできない

次の例では、 {item-id} によって識別されるフォルダー内の子項目を、 driveId で識別されるフォルダーにコピーし、値を id します。 要求本文は、 childrenOnly パラメーターを true に設定し、 name 値も指定します。 childrenOnlyパラメーターと name パラメーターが相互に排他的な場合、要求は失敗します。

要求

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

関連コンテンツ

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