REST を使用してフォルダーとファイルを操作する
注:
このページの例では、% と # の文字はサポートされていません。 ResourcePath API を使用してファイルとフォルダーの % と # をサポートする
ヒント
SharePoint Online (およびオンプレミス SharePoint 2016 以降) REST サービスでは、OData $batch クエリ オプションを使って、サービスに対する複数の要求を 1 つの呼び出しに統合できます。 詳細とコード サンプルへのリンクについては、「REST API によりバッチ要求を発行する」を参照してください。
REST を使用してフォルダーを操作する
URL がわかっている場合は、ドキュメント ライブラリ内のフォルダーを取得できます。 たとえば、次の例のエンドポイントを使用すると、共有ドキュメント ライブラリのルート フォルダーを取得できます。
GET https://{site_url}/_api/web/GetFolderByServerRelativeUrl('/Shared Documents')
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
次の XML は、XML コンテンツ タイプを要求したときに返されるフォルダー プロパティの例を示しています。
<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>
次の例は、フォルダーを作成する方法を示しています。
POST https://{site_url}/_api/web/folders
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Content-Type: "application/json"
Content-Length: {length of request body as integer}
X-RequestDigest: "{form_digest_value}"
{
"__metadata": {
"type": "SP.Folder"
},
"ServerRelativeUrl": "/document library relative url/folder name"
}
次の例は、MERGE メソッドを使用してフォルダーの名前を変更する方法を示しています。
まず、GET 要求でフォルダーの OData の種類を取得します。
GET https://{site_url}/_api/web/GetFolderByServerRelativeUrl('/Folder Name')/ListItemAllFields
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
結果から、SP.Data.Shared_x0020_DocumentsItem などの odata.type 値を取得します (値は、ライブラリ構成によって異なる場合があります)。 差し込み印刷要求を送信します。
POST https://{site_url}/_api/web/GetFolderByServerRelativeUrl('/Folder Name')/ListItemAllFields
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Content-Type: "application/json"
Content-Length: {length of request body as integer}
If-Match: "{etag or *}"
X-HTTP-Method: "MERGE"
X-RequestDigest: "{form_digest_value}"
{
"__metadata": {
"type": "{odata.type from previous call}"
},
"Title": "New name",
"FileLeafRef": "New name"
}
次の例は、フォルダーを削除する方法を示しています。
POST https://{site_url}/_api/web/GetFolderByServerRelativeUrl('/Folder Name')
Authorization: "Bearer " + accessToken
If-Match: "{etag or *}"
X-HTTP-Method: "DELETE"
X-RequestDigest: "{form_digest_value}"
REST を使用してファイルを操作する
次の例は、フォルダー内のすべてのファイルを取得する方法を示しています。
GET https://{site_url}/_api/web/GetFolderByServerRelativeUrl('/Folder Name')/Files
method: GET
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
次の例は、特定のファイルを取得する方法を示しています。
GET https://{site_url}/_api/web/GetFolderByServerRelativeUrl('/Folder Name')/Files('{file_name}')/$value
Authorization: "Bearer " + accessToken
次の例のように、URL がわかっている場合は、ファイルを取得することもできます。
GET https://{site_url}/_api/web/GetFileByServerRelativeUrl('/Folder Name/{file_name}')/$value
Authorization: "Bearer " + accessToken
次のコードサンプルは、上記の REST エンドポイントと C# を使用して、ファイルのURLがわかった場合にファイルを取得する方法を示しています。
/// <summary>
/// Download File Via Rest API
/// </summary>
/// <param name="webUrl">https://xxxxx/sites/DevSite</param>
/// <param name="credentials"></param>
/// <param name="documentLibName">MyDocumentLibrary</param>
/// <param name="fileName">test.docx</param>
/// <param name="path">C:\\</param>
public static void DownloadFileViaRestAPI(string webUrl, ICredentials credentials, string documentLibName, string fileName, string path)
{
webUrl = webUrl.EndsWith("/") ? webUrl.Substring(0, webUrl.Length - 1) : webUrl;
string webRelativeUrl = null;
if (webUrl.Split('/').Length > 3)
{
webRelativeUrl = "/" + webUrl.Split(new char[] { '/' }, 4)[3];
}
else
{
webRelativeUrl = "";
}
using (WebClient client = new WebClient())
{
client.Headers.Add("X-FORMS_BASED_AUTH_ACCEPTED", "f");
client.Credentials = credentials;
Uri endpointUri = new Uri(webUrl + "/_api/web/GetFileByServerRelativeUrl('" + webRelativeUrl + "/" + documentLibName + "/" + fileName + "')/$value");
byte[] data = client.DownloadData(endpointUri);
FileStream outputStream = new FileStream(path + fileName, FileMode.OpenOrCreate | FileMode.Append, FileAccess.Write, FileShare.None);
outputStream.Write(data, 0, data.Length);
outputStream.Flush(true);
outputStream.Close();
}
}
static void Main(string[] args)
{
string siteURL = "https://xxxxx/sites/DevSite";
//set credential of SharePoint online
SecureString secureString = new SecureString();
foreach (char c in "Password".ToCharArray())
{
secureString.AppendChar(c);
}
ICredentials credentials = new SharePointOnlineCredentials("xxxxxx.onmicrosoft.com", secureString);
//set credential of SharePoint 2013(On-Premises)
//string userName = "Administrator";
//string password = "xxxxxxx";
//string domain = "CONTOSO";
//ICredentials credentials = new NetworkCredential(userName, password, domain);
DownloadFileViaRestAPI(siteURL, credentials, "MyDocumentLib", "test.docx", "c:\\");
Console.WriteLine("success");
Console.ReadLine();
}
次の例は、ファイルを作成してフォルダーに追加する方法を示しています。
POST https://{site_url}/_api/web/GetFolderByServerRelativeUrl('/Folder Name')/Files/add(url='a.txt',overwrite=true)
Authorization: "Bearer " + accessToken
Content-Length: {length of request body as integer}
X-RequestDigest: "{form_digest_value}"
"Contents of file"
次の例は、PUT メソッドを使用してファイルを更新する方法を示しています。
注:
PUT は、ファイルの更新に使用できる唯一の方法です。 MERGE メソッドは使用できません。
POST https://{site_url}/_api/web/GetFileByServerRelativeUrl('/Folder Name/{file_name}')/$value
Authorization: "Bearer " + accessToken
Content-Length: {length of request body as integer}
X-HTTP-Method: "PUT"
X-RequestDigest: "{form_digest_value}"
"Contents of file"
ファイルのメタデータを更新する場合は、リスト アイテムとしてファイルに到達するエンドポイントを作成する必要があります。 この操作を行うことができるのは、各フォルダーがリストでもあり、各ファイルがリスト アイテムでもあるからです。 https://{site_url}/_api/web/lists/getbytitle('Documents')/items({item_id}) のようなエンドポイントを作成します。 リスト アイテムのメタデータを更新する方法については、「REST を使用したリストとリスト アイテムの操作」を参照してください。
更新するまでファイルが他の人によって変更されないようにするため、ファイルをチェックアウトすることもできます。 また、更新した後は、他のユーザーが操作できるようにファイルをチェックインして戻す必要もあります。
次の例は、ファイルをチェックアウトする方法を示しています。
POST https://{site_url}/_api/web/GetFileByServerRelativeUrl('/Folder Name/{file_name}')/CheckOut(),
Authorization: "Bearer " + accessToken
X-RequestDigest: "{form_digest_value}"
次の例は、ファイルをチェックインする方法を示しています。
POST https://{site_url}/_api/web/GetFileByServerRelativeUrl('/Folder Name/{file_name}')/CheckIn(comment='Comment',checkintype=0)
Authorization: "Bearer " + accessToken
X-RequestDigest: "{form_digest_value}"
次の例は、ファイルを削除する方法を示しています。
POST https://{site_url}/_api/web/GetFileByServerRelativeUrl('/Folder Name/{file_name}')
Authorization: "Bearer " + accessToken
If-Match: "{etag or *}"
X-HTTP-Method: "DELETE"
X-RequestDigest: "{form_digest_value}"
REST を使用して大きなファイルを操作する
1.5 メガバイト (MB) を超えるバイナリ ファイルをアップロードする必要がある場合は、REST インターフェイスを使用するのが唯一の方法です。 SharePoint JavaScript オブジェクト モデルを使用して 1.5 MB 未満のバイナリ ファイルをアップロードする方法を示すコード例については、「SharePoint の JavaScript ライブラリ コードを使用して基本的な操作を完了する」を参照してください。 REST を使用して作成できるバイナリ ファイルの最大サイズは 2 ギガバイト (GB) です。
次の例は、大きなバイナリ ファイルを作成する方法を示しています。
警告
このアプローチは、Internet Explorer 10 と他の最新バージョンのブラウザーでのみ使用できます。
POST https://{site_url}/_api/web/GetFolderByServerRelativeUrl('/Folder Name')/Files/Add(url='{file_name}', overwrite=true)
Authorization: "Bearer " + accessToken
Content-Length: {length of request body as integer}
X-RequestDigest: "{form_digest_value}"
Contents of binary file
次のコード サンプルは、この REST エンドポイントと JSOM クロスドメイン ライブラリを使用してファイルを作成する方法を示しています。
function uploadFileBinary() {
XDomainTestHelper.clearLog();
var requestExecutor;
if (document.getElementById("TxtViaUrl").value.length > 0) {
requestExecutor = new SP.RequestExecutor(document.getElementById("TxtWebUrl").value, document.getElementById("TxtViaUrl").value);
}
else {
requestExecutor = 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"
};
requestExecutor.executeAsync(info);
}
REST を使用してリスト アイテムに添付されたファイルを操作する
次の例は、リスト アイテムに添付されているすべてのファイルを取得する方法を示しています。
GET https://{site_url}/_api/web/lists/getbytitle('{list_title}')/items({item_id})/AttachmentFiles/
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
次の例は、リスト アイテムに添付されているファイルを取得する方法を示しています。
GET https://{site_url}/_api/web/lists/getbytitle('{list_title}')/items({item_id})/AttachmentFiles('{file_name}')/$value
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
次の例は、リスト アイテムの添付ファイルを作成する方法を示しています。
POST https://{site_url}/_api/web/lists/getbytitle('{list_title}')/items({item_id})/AttachmentFiles/ add(FileName='{file_name}')
Authorization: "Bearer " + accessToken
Content-Length: {length of request body as integer}
X-RequestDigest: "{form_digest_value}"
"Contents of file"
次の例は、PUT メソッドを使用してリスト アイテムの添付ファイルを更新する方法を示しています。
注:
PUT は、ファイルの更新に使用できる唯一の方法です。 MERGE メソッドは使用できません。
POST https://{site_url}/_api/web/lists/getbytitle('{list_title}')/items({item_id})/AttachmentFiles('{file_name}')/$value
Authorization: "Bearer " + accessToken
Content-Length: {length of request body as integer}
X-HTTP-Method: "PUT"
X-RequestDigest: "{form_digest_value}"
"Contents of file"