REST を使用してフォルダーとファイルを操作するWorking with folders and files with REST

ヒント

SharePoint Online (およびオンプレミス SharePoint 2016 以降) REST サービスでは、OData $batch クエリ オプションを使って、サービスに対する複数の要求を 1 つの呼び出しに統合できます。The SharePoint Online (and on-premises SharePoint 2016 and later) REST service supports combining multiple requests into a single call to the service by using the OData $batch query option. 詳細とコード サンプルへのリンクについては、「REST API によりバッチ要求を発行する」を参照してください。For details and links to code samples, see Make batch requests with the REST APIs.

REST を使用してフォルダーを操作するWorking with folders by using REST

URL がわかっている場合は、ドキュメント ライブラリ内のフォルダーを取得できます。You can retrieve a folder inside a document library when you know its URL. たとえば、次の例のエンドポイントを使用すると、共有ドキュメント ライブラリのルート フォルダーを取得できます。For example, you can retrieve the root folder of your Shared Documents library by using the endpoint in the following example.

url: http://site url/_api/web/GetFolderByServerRelativeUrl('/Shared Documents')
method: GET
headers:
    Authorization: "Bearer " + accessToken
    accept: "application/json;odata=verbose" or "application/atom+xml"


次の XML は、XML コンテンツ タイプを要求したときに返されるフォルダー プロパティの例を示しています。The following XML shows an example of folder properties that are returned when you request the XML content type.

<content type="application/xml">
<m:properties>
<d:ItemCount m:type="Edm.Int32">0</d:ItemCount>
<d:Name>Shared Documents</d:Name>
<d:ServerRelativeUrl>/Shared Documents</d:ServerRelativeUrl>
<d:WelcomePage/>
</m:properties>
</content>

次の例は、フォルダーを作成する方法を示しています。The following example shows how to create a folder.

url: http://site url/_api/web/folders
method: POST
body: { '__metadata': { 'type': 'SP.Folder' }, 'ServerRelativeUrl': '/document library relative url/folder name'}
Headers: 
    Authorization: "Bearer " + accessToken
    X-RequestDigest: form digest value
    accept: "application/json;odata=verbose"
    content-type: "application/json;odata=verbose"
    content-length:length of post body

次の例は、MERGE メソッドを使用してフォルダーの名前を変更する方法を示しています。The following example shows how to rename a folder by using the MERGE method.

まず、GET 要求でフォルダーの OData の種類を取得します。First, obtain the folder's OData type with a GET request.

url: http://site url/_api/web/GetFolderByServerRelativeUrl('/Folder Name')/ListItemAllFields
method: GET
Headers: 
     Authorization: "Bearer " + accessToken
    "IF-MATCH": etag or "*"
    accept: "application/json;odata=verbose"
    content-type: "application/json;odata=verbose"

返された結果から、odata.type の値 (SP.Data.Shared_x0020_DocumentsItem など) を取得します (値は、ライブラリの構成によって異なる場合があります)。From the result, obtain the odata.type value, such as SP.Data.Shared_x0020_DocumentsItem (the value may be different depending on your library configuration). その後、MERGE を実行します。Then issue a MERGE

url: http://site url/_api/web/GetFolderByServerRelativeUrl('/Folder Name')/ListItemAllFields
method: POST
body: { '__metadata': { 'type': '(odata.type from previous call)' }, 'Title': 'New name', 'FileLeafRef': 'New name' }
Headers: 
     Authorization: "Bearer " + accessToken
    X-RequestDigest: form digest value
    "IF-MATCH": etag or "*"
    "X-HTTP-Method":"MERGE",
    accept: "application/json;odata=verbose"
    content-type: "application/json;odata=verbose"
    content-length:length of post body

次の例は、フォルダーを削除する方法を示しています。The following example shows how to delete a folder.

url: http://site url/_api/web/GetFolderByServerRelativeUrl('/Folder Name')
method: POST
Headers: 
     Authorization: "Bearer " + accessToken
     X-RequestDigest: form digest value
    "IF-MATCH": etag or "*"
    "X-HTTP-Method":"DELETE"


REST を使用してファイルを操作するWorking with files by using REST

次の例は、フォルダー内のすべてのファイルを取得する方法を示しています。The following example shows how to retrieve all of the files in a folder.

url: http://site url/_api/web/GetFolderByServerRelativeUrl('/Folder Name')/Files
method: GET
headers:
    Authorization: "Bearer " + accessToken
    accept: "application/json;odata=verbose" or "application/atom+xml"


次の例は、特定のファイルを取得する方法を示しています。The following example shows how to retrieve a specific file.

url: http://site url/_api/web/GetFolderByServerRelativeUrl('/Folder Name')/Files('file name')/$value
method: GET
headers:
    Authorization: "Bearer " + accessToken

次の例のように、URL がわかっている場合は、ファイルを取得することもできます。You can also retrieve a file when you know its URL, as in the following example.

url: http://site url/_api/web/GetFileByServerRelativeUrl('/Folder Name/file name')/$value
method: GET
headers:
    Authorization: "Bearer " + accessToken

次の例は、ファイルを作成してフォルダーに追加する方法を示しています。The following example shows how to create a file and add it to a folder.

url: http://site url/_api/web/GetFolderByServerRelativeUrl('/Folder Name')/Files/add(url='a.txt',overwrite=true)
method: POST
body: "Contents of file"
Headers: 
    Authorization: "Bearer " + accessToken
    X-RequestDigest: form digest value
    content-length:length of post body

次の例は、PUT メソッドを使用してファイルを更新する方法を示しています。The following example shows how to update a file by using the PUT method.

注意

PUT はファイルの更新に使用できる唯一のメソッドです。MERGE メソッドは使用できません。PUT is the only method that you can use to update a file. The MERGE method is not allowed.

url: http://site url/_api/web/GetFileByServerRelativeUrl('/Folder Name/file name')/$value
method: POST
body: "Contents of file."
Headers: 
    Authorization: "Bearer " + accessToken
    X-RequestDigest: form digest value
    X-HTTP-Method:"PUT"
    content-length:length of post body

ファイルのメタデータを更新する場合は、リスト アイテムとしてファイルに到達するエンドポイントを作成する必要があります。If you want to update a file's metadata, you have to construct an endpoint that reaches the file as a list item. この操作を行うことができるのは、各フォルダーがリストでもあり、各ファイルがリスト アイテムでもあるからです。You can do this because each folder is also a list, and each file is also a list item. https://<site url>/_api/web/lists/getbytitle('Documents')/items(<item id>) のようなエンドポイントを作成します。Construct an endpoint that looks like this: https://<site url>/_api/web/lists/getbytitle('Documents')/items(<item id>). リスト アイテムのメタデータを更新する方法については、「REST を使用したリストとリスト アイテムの操作」を参照してください。For information about how to update a list item's metadata, see Working with lists and list items with REST.

更新するまでファイルが他の人によって変更されないようにするため、ファイルをチェックアウトすることもできます。You may want to check out a file to make sure that no one changes it before you update it. また、更新した後は、他のユーザーが操作できるようにファイルをチェックインして戻す必要もあります。After your update, you should check the file back in so that others can work with it.

次の例は、ファイルをチェックアウトする方法を示しています。The following example shows how to check out a file.

url: http://site url/_api/web/GetFileByServerRelativeUrl('/Folder Name/file name')/CheckOut(),
method: POST
headers:
    Authorization: "Bearer " + accessToken
    X-RequestDigest: form digest value

次の例は、ファイルをチェックインする方法を示しています。The following example shows how to check in a file.

url: http://site url/_api/web/GetFileByServerRelativeUrl('/Folder Name/file name')/CheckIn(comment='Comment',checkintype=0)
method: POST
headers:
    Authorization: "Bearer " + accessToken
    X-RequestDigest: form digest value

次の例は、ファイルを削除する方法を示しています。The following example shows how to delete a file.

url: http://site url/_api/web/GetFileByServerRelativeUrl('/Folder Name/file name')
method: POST
headers:
    Authorization: "Bearer " + accessToken
     X-RequestDigest: form digest value
    IF-MATCH: etag or "*"
    X-HTTP-Method:"DELETE"


REST を使用して大きなファイルを操作するWorking with large files by using REST

1.5 メガバイト (MB) を超えるバイナリ ファイルをアップロードする必要がある場合は、REST インターフェイスを使用するのが唯一の方法です。When you need to upload a binary file that is larger than 1.5 megabytes (MB), the REST interface is your only option. SharePoint JavaScript オブジェクト モデルを使用して 1.5 MB 未満のバイナリ ファイルをアップロードする方法を示すコード例については、「SharePoint の JavaScript ライブラリ コードを使用して基本的な操作を完了する」を参照してください。For a code example that shows you how to upload a binary file that is smaller than 1.5 MB by using the SharePoint JavaScript object model, see Complete basic operations using JavaScript library code in SharePoint. REST を使用して作成できるバイナリ ファイルの最大サイズは 2 ギガバイト (GB) です。The maximum size of a binary file that you can create with REST is 2 gigabytes (GB).

次の例は、大きなバイナリ ファイルを作成する方法を示しています。The following example shows how to create a large binary file.

警告

このアプローチは、Internet Explorer 10 と他の最新バージョンのブラウザーでのみ使用できます。This approach works only with Internet Explorer 10 and the latest versions of other browsers.

url: http://site url/_api/web/GetFolderByServerRelativeUrl('/Folder Name')/Files/Add(url='file name', overwrite=true)
method: POST
body: contents of binary file
headers:
    Authorization: "Bearer " + accessToken
    X-RequestDigest: form digest value
    content-type: "application/json;odata=verbose"
    content-length:length of post body

次のコード サンプルは、この REST エンドポイントとクロスドメイン ライブラリを使用してファイルを作成する方法を示しています。The following code sample shows how to create a file by using this REST endpoint and the cross-domain library.

function uploadFileBinary() {
XDomainTestHelper.clearLog();
var ro;
if (document.getElementById("TxtViaUrl").value.length > 0) {
ro = new SP.RequestExecutor(document.getElementById("TxtWebUrl").value, document.getElementById("TxtViaUrl").value);
}
else {
ro = new SP.RequestExecutor(document.getElementById("TxtWebUrl").value);
}
var body = "";
for (var i = 0; i < 1000; i++) {
var ch = i % 256;
body = body + String.fromCharCode(ch);
}
var info = {
url: "_api/web/lists/getByTitle('Shared Documents')/RootFolder/Files/Add(url='a.dat', overwrite=true)",
method: "POST",
binaryStringRequestBody: true,
body: body,
success: success,
error: fail,
state: "Update"
};
ro.executeAsync(info);
}


REST を使用してリスト アイテムに添付されたファイルを操作するWorking with files attached to list items by using REST

次の例は、リスト アイテムに添付されているすべてのファイルを取得する方法を示しています。The following example shows how to retrieve all of the files that are attached to a list item.

url: http://site url/_api/web/lists/getbytitle('list title')/items(item id)/AttachmentFiles/
method: GET
headers:
    Authorization: "Bearer " + accessToken
    accept: "application/json;odata=verbose" or "application/atom+xml"


次の例は、リスト アイテムに添付されているファイルを取得する方法を示しています。The following example shows how to retrieve a file that is attached to a list item.

url: http://site url/_api/web/lists/getbytitle('list title')/items(item id)/AttachmentFiles('file name')/$value
method: GET
headers:
    Authorization: "Bearer " + accessToken
    accept: "application/json;odata=verbose" or "application/atom+xml"


次の例は、リスト アイテムの添付ファイルを作成する方法を示しています。The following example shows how to create a file attachment to a list item.

url: http://site url/_api/web/lists/getbytitle('list title')/items(item id)/AttachmentFiles/ add(FileName='file name')
method: POST
headers:
    Authorization: "Bearer " + accessToken
    body: "Contents of file."
    X-RequestDigest: form digest value
    content-length:length of post body

次の例は、PUT メソッドを使用してリスト アイテムの添付ファイルを更新する方法を示しています。The following example shows how to update a file attachment to a list item by using the PUT method.

注意

PUT はファイルの更新に使用できる唯一のメソッドです。MERGE メソッドは使用できません。PUT is the only method that you can use to update a file. The MERGE method is not allowed.

url: http://site url/_api/web/lists/getbytitle('list title')/items(item id)/AttachmentFiles('file name')/$value
method: POST
body: "Contents of file."
headers:
    Authorization: "Bearer " + accessToken
    "X-HTTP-Method":"PUT"
    X-RequestDigest: form digest value
    content-length:length of post body

関連項目See also