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

本篇主要通过两个代码示例来展示如何应用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/getby (\'<list >\')/rootfolder/files/add。

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

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

运行代码示例

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

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

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

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

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

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

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

<  src=\"https://ajax.aspnetcdn.com/ajax/jQuery/jquery-1.9.1.min.js\" type=\"text/ \"></ >

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

<input id=\"getFile\" type=\"file\"/><br />
  <input id=\"displayName\" type=\"text\" value=\"Enter a unique name\" /><br />
  <input id=\"addFileButton\" type=\"button\" value=\"Upload\"  =\"uploadFile()\"/>

代码示例一：使用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   of the list item.
                var changeItem = updateListItem(listItem.d.__ data);
                changeItem.done(function (data, status, xhr) {
                    alert(\'file uploaded and updated\');
                });
                changeItem.fail( );
            });
            getItem.fail( );
        });
        addFile.fail( );
    });
    getFile.fail( );

    // Get the local file as an array buffer.
    function getFileBuffer() {
        var deferred = jQuery.Deferred();
        var reader = new FileReader();
        reader. end = function (e) {
            deferred.resolve(e.target.result);
        }
        reader.  = 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   of the list item.
    function updateListItem(item data) {

        // Construct the endpoint.
        // Specify the host web as the context site.
        var listItemUri = item data.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  .
        // The example gets the list item type from the item\'s  data, but you can also get it from the
        // ListItemEntityTypeFullName property of the list.
        var body = String.format(\"{{\'__ data\':{{\'type\':\'{0}\'}},\'FileLeafRef\':\'{1}\',\' \':\'{2}\'}}\",
            item data.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\": item data.etag,
                \"X-HTTP-Method\": \"MERGE\"
            }
        });
    }
}

// Display error messages. 
function  (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   of the list item.
                var changeItem = updateListItem(listItem.d.__ data);
                changeItem.done(function (data, status, xhr) {
                    alert(\'file uploaded and updated\');
                });
                changeItem.fail( );
            });
            getItem.fail( );
        });
        addFile.fail( );
    });
    getFile.fail( );

    // Get the local file as an array buffer.
    function getFileBuffer() {
        var deferred = jQuery.Deferred();
        var reader = new FileReader();
        reader. end = function (e) {
            deferred.resolve(e.target.result);
        }
        reader.  = 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   of the list item.
    function updateListItem(item data) {

        // Define the list item changes. Use the FileLeafRef property to change the display name. 
        // For simplicity, also use the name as the  . 
        // The example gets the list item type from the item\'s  data, but you can also get it from the
        // ListItemEntityTypeFullName property of the list.
        var body = String.format(\"{{\'__ data\':{{\'type\':\'{0}\'}},\'FileLeafRef\':\'{1}\',\' \':\'{2}\'}}\",
            item data.type, newName, newName);

        // Send the request and return the promise.
        // This call does not return response content from the server.
        return jQuery.ajax({
            url: item data.uri,
            type: \"POST\",
            data: body,
            headers: {
                \"X-RequestDigest\": jQuery(\"#__REQUESTDIGEST\").val(),
                \"content-type\": \"application/json;odata=verbose\",
                \"content-length\": body.length,
                \"IF-MATCH\": item data.etag,
                \"X-HTTP-Method\": \"MERGE\"
            }
        });
    }
}

// Display error messages. 
function  (error) {
    alert(error.responseText);
}

本篇就到这里。