SharePoint REST API - 使用REST API和jQuery上传一个文件

叁歲伎倆 2022-04-03 08:10 213阅读 0赞

本篇主要通过两个代码示例来展示如何应用REST API和jQuery上传文件到SharePoint。

示例会使用REST接口和jQuery AJAX请求来将一个本地文件添加到SharePoint文档库并修改它的一些属性。主要有以下几个操作步骤：

1. 使用FileReader API将本地文件转换成数组（需要HTML5支持），jQuery的(document).ready函数会检查浏览器对FileReader API的支持情况。

2. 使用文件夹的文件集合对象的Add方法将文件添加到文档库，将数组缓冲放到POST请求的body里。本文介绍的示例会使用getfolderbyserverrelativeurl端点来获取文件集合对象，如果不用这个，你也可以使用列表端点如…/\_api/web/lists/getbytitle('<list title>')/rootfolder/files/add。

3. 使用ListItemAllFields属性来获取与上传文件相对应的列表项。

4. 使用MERGE请求来更改列表项的标题和显示名。

**运行代码示例**

本文中的两个代码示例使用REST API和jQuery AJAX请求来上传文件到文档库，然后更改对应列表项的属性。第一个例子使用SP.AppContextSite来跨SharePoint域进行调用，就像SharePoint承载的Add-in在上传文件到承载它的网站时做的那样。另一个例子是在同域调用的，就像上传到Add-in所在的网站时做的那样。

注意用JavaScript编写的提供程序承载的Add-in必须使用SP.RequestExecutor跨域库来向SharePoint域发送请求。

使用本文提到的示例，你需要做以下事情：

1. 首先你要有SharePoint Server 2013、2016或者是Online的环境。

2. 执行代码的用户需要有对文档库的写权限，如果你开发的是一个SharePoint Add-in的话，你可以在列表范围指定写权限。

3. 支持FileReader API（HTML5）的浏览器。

4. 在你的页面中引用jQuery库，例如：

5. 在你的页面中添加以下控件：

**代码示例一：使用REST API和jQuery跨SharePoint域上传文件**

大师傅下面的代码示例将文件上传到承载SharePoint Add-in的SharePoint网站。

'use strict';
    
    var appWebUrl, hostWebUrl;
    
    jQuery(document).ready(function () {
    
        // Check for FileReader API (HTML5) support.
        if (!window.FileReader) {
            alert('This browser does not support the FileReader API.');
        }
    
        // Get the add-in web and host web URLs.
        appWebUrl = decodeURIComponent(getQueryStringParameter("SPAppWebUrl"));
        hostWebUrl = decodeURIComponent(getQueryStringParameter("SPHostUrl"));
    });
    
    // Upload the file.
    // You can upload files up to 2 GB with the REST API.
    function uploadFile() {
    
        // Define the folder path for this example.
        var serverRelativeUrlToFolder = '/shared documents';
    
        // Get test values from the file input and text input page controls.
        // The display name must be unique every time you run the example.
        var fileInput = jQuery('#getFile');
        var newName = jQuery('#displayName').val();
    
        // Initiate method calls using jQuery promises.
        // Get the local file as an array buffer.
        var getFile = getFileBuffer();
        getFile.done(function (arrayBuffer) {
    
            // Add the file to the SharePoint folder.
            var addFile = addFileToFolder(arrayBuffer);
            addFile.done(function (file, status, xhr) {
    
                // Get the list item that corresponds to the uploaded file.
                var getItem = getListItem(file.d.ListItemAllFields.__deferred.uri);
                getItem.done(function (listItem, status, xhr) {
    
                    // Change the display name and title of the list item.
                    var changeItem = updateListItem(listItem.d.__metadata);
                    changeItem.done(function (data, status, xhr) {
                        alert('file uploaded and updated');
                    });
                    changeItem.fail(onError);
                });
                getItem.fail(onError);
            });
            addFile.fail(onError);
        });
        getFile.fail(onError);
    
        // Get the local file as an array buffer.
        function getFileBuffer() {
            var deferred = jQuery.Deferred();
            var reader = new FileReader();
            reader.onloadend = function (e) {
                deferred.resolve(e.target.result);
            }
            reader.onerror = function (e) {
                deferred.reject(e.target.error);
            }
            reader.readAsArrayBuffer(fileInput[0].files[0]);
            return deferred.promise();
        }
    
        // Add the file to the file collection in the Shared Documents folder.
        function addFileToFolder(arrayBuffer) {
    
            // Get the file name from the file input control on the page.
            var parts = fileInput[0].value.split('\\');
            var fileName = parts[parts.length - 1];
    
            // Construct the endpoint.
            var fileCollectionEndpoint = String.format(
                "{0}/_api/sp.appcontextsite(@target)/web/getfolderbyserverrelativeurl('{1}')/files" +
                "/add(overwrite=true, url='{2}')?@target='{3}'",
                appWebUrl, serverRelativeUrlToFolder, fileName, hostWebUrl);
    
            // Send the request and return the response.
            // This call returns the SharePoint file.
            return jQuery.ajax({
                url: fileCollectionEndpoint,
                type: "POST",
                data: arrayBuffer,
                processData: false,
                headers: {
                    "accept": "application/json;odata=verbose",
                    "X-RequestDigest": jQuery("#__REQUESTDIGEST").val(),
                    "content-length": arrayBuffer.byteLength
                }
            });
        }
    
        // Get the list item that corresponds to the file by calling the file's ListItemAllFields property.
        function getListItem(fileListItemUri) {
    
            // Construct the endpoint.
            // The list item URI uses the host web, but the cross-domain call is sent to the
            // add-in web and specifies the host web as the context site.
            fileListItemUri = fileListItemUri.replace(hostWebUrl, '{0}');
            fileListItemUri = fileListItemUri.replace('_api/Web', '_api/sp.appcontextsite(@target)/web');
            
            var listItemAllFieldsEndpoint = String.format(fileListItemUri + "?@target='{1}'",
                appWebUrl, hostWebUrl);
    
            // Send the request and return the response.
            return jQuery.ajax({
                url: listItemAllFieldsEndpoint,
                type: "GET",
                headers: { "accept": "application/json;odata=verbose" }
            });
        }
    
        // Change the display name and title of the list item.
        function updateListItem(itemMetadata) {
    
            // Construct the endpoint.
            // Specify the host web as the context site.
            var listItemUri = itemMetadata.uri.replace('_api/Web', '_api/sp.appcontextsite(@target)/web');
            var listItemEndpoint = String.format(listItemUri + "?@target='{0}'", hostWebUrl);
    
            // Define the list item changes. Use the FileLeafRef property to change the display name. 
            // For simplicity, also use the name as the title.
            // The example gets the list item type from the item's metadata, but you can also get it from the
            // ListItemEntityTypeFullName property of the list.
            var body = String.format("{
       {'__metadata':{
       {'type':'{0}'}},'FileLeafRef':'{1}','Title':'{2}'}}",
                itemMetadata.type, newName, newName);
    
            // Send the request and return the promise.
            // This call does not return response content from the server.
            return jQuery.ajax({
                url: listItemEndpoint,
                type: "POST",
                data: body,
                headers: {
                    "X-RequestDigest": jQuery("#__REQUESTDIGEST").val(),
                    "content-type": "application/json;odata=verbose",
                    "content-length": body.length,
                    "IF-MATCH": itemMetadata.etag,
                    "X-HTTP-Method": "MERGE"
                }
            });
        }
    }
    
    // Display error messages. 
    function onError(error) {
        alert(error.responseText);
    }
    
    // Get parameters from the query string.
    // For production purposes you may want to use a library to handle the query string.
    function getQueryStringParameter(paramToRetrieve) {
        var params = document.URL.split("?")[1].split("&");
        for (var i = 0; i < params.length; i = i + 1) {
            var singleParam = params[i].split("=");
            if (singleParam[0] == paramToRetrieve) return singleParam[1];
        }
    }

代码示例二：使用REST API和jQuery将文件上传到同域网站

'use strict';
    
    jQuery(document).ready(function () {
    
        // Check for FileReader API (HTML5) support.
        if (!window.FileReader) {
            alert('This browser does not support the FileReader API.');
        }
    });
    
    // Upload the file.
    // You can upload files up to 2 GB with the REST API.
    function uploadFile() {
    
        // Define the folder path for this example.
        var serverRelativeUrlToFolder = '/shared documents';
    
        // Get test values from the file input and text input page controls.
        var fileInput = jQuery('#getFile');
        var newName = jQuery('#displayName').val();
    
        // Get the server URL.
        var serverUrl = _spPageContextInfo.webAbsoluteUrl;
    
        // Initiate method calls using jQuery promises.
        // Get the local file as an array buffer.
        var getFile = getFileBuffer();
        getFile.done(function (arrayBuffer) {
    
            // Add the file to the SharePoint folder.
            var addFile = addFileToFolder(arrayBuffer);
            addFile.done(function (file, status, xhr) {
    
                // Get the list item that corresponds to the uploaded file.
                var getItem = getListItem(file.d.ListItemAllFields.__deferred.uri);
                getItem.done(function (listItem, status, xhr) {
    
                    // Change the display name and title of the list item.
                    var changeItem = updateListItem(listItem.d.__metadata);
                    changeItem.done(function (data, status, xhr) {
                        alert('file uploaded and updated');
                    });
                    changeItem.fail(onError);
                });
                getItem.fail(onError);
            });
            addFile.fail(onError);
        });
        getFile.fail(onError);
    
        // Get the local file as an array buffer.
        function getFileBuffer() {
            var deferred = jQuery.Deferred();
            var reader = new FileReader();
            reader.onloadend = function (e) {
                deferred.resolve(e.target.result);
            }
            reader.onerror = function (e) {
                deferred.reject(e.target.error);
            }
            reader.readAsArrayBuffer(fileInput[0].files[0]);
            return deferred.promise();
        }
    
        // Add the file to the file collection in the Shared Documents folder.
        function addFileToFolder(arrayBuffer) {
    
            // Get the file name from the file input control on the page.
            var parts = fileInput[0].value.split('\\');
            var fileName = parts[parts.length - 1];
    
            // Construct the endpoint.
            var fileCollectionEndpoint = String.format(
                    "{0}/_api/web/getfolderbyserverrelativeurl('{1}')/files" +
                    "/add(overwrite=true, url='{2}')",
                    serverUrl, serverRelativeUrlToFolder, fileName);
    
            // Send the request and return the response.
            // This call returns the SharePoint file.
            return jQuery.ajax({
                url: fileCollectionEndpoint,
                type: "POST",
                data: arrayBuffer,
                processData: false,
                headers: {
                    "accept": "application/json;odata=verbose",
                    "X-RequestDigest": jQuery("#__REQUESTDIGEST").val(),
                    "content-length": arrayBuffer.byteLength
                }
            });
        }
    
        // Get the list item that corresponds to the file by calling the file's ListItemAllFields property.
        function getListItem(fileListItemUri) {
    
            // Send the request and return the response.
            return jQuery.ajax({
                url: fileListItemUri,
                type: "GET",
                headers: { "accept": "application/json;odata=verbose" }
            });
        }
    
        // Change the display name and title of the list item.
        function updateListItem(itemMetadata) {
    
            // Define the list item changes. Use the FileLeafRef property to change the display name. 
            // For simplicity, also use the name as the title. 
            // The example gets the list item type from the item's metadata, but you can also get it from the
            // ListItemEntityTypeFullName property of the list.
            var body = String.format("{
       {'__metadata':{
       {'type':'{0}'}},'FileLeafRef':'{1}','Title':'{2}'}}",
                itemMetadata.type, newName, newName);
    
            // Send the request and return the promise.
            // This call does not return response content from the server.
            return jQuery.ajax({
                url: itemMetadata.uri,
                type: "POST",
                data: body,
                headers: {
                    "X-RequestDigest": jQuery("#__REQUESTDIGEST").val(),
                    "content-type": "application/json;odata=verbose",
                    "content-length": body.length,
                    "IF-MATCH": itemMetadata.etag,
                    "X-HTTP-Method": "MERGE"
                }
            });
        }
    }
    
    // Display error messages. 
    function onError(error) {
        alert(error.responseText);
    }

本篇就到这里。