REST API および jQuery を使用してファイルをアップロードするUpload a file by using the REST API and jQuery

この記事のコード例では、REST インターフェイスと jQuery AJAX 要求を使用して、ローカル ファイルをドキュメント ライブラリに追加してから、アップロードしたファイルを表すリスト アイテムのプロパティを変更します。The code examples in this article use the REST interface and jQuery AJAX requests to add a local file to the Documents library, and then change properties of the list item that represents the uploaded file.

この処理は次の大まかな手順で行われます。This process uses the following high-level steps:

  1. FileReader API (HTML5 のサポートが必要) を使用して、ローカル ファイルを配列バッファーに変換します。 jQuery(document).ready 関数により、ブラウザーで FileReader API がサポートされているかどうかを確認します。Convert the local file to an array buffer by using the FileReader API, which requires HTML5 support. The jQuery(document).ready function checks for FileReader API support in the browser.

  2. フォルダーのファイル コレクションに Add メソッドを使用し、ファイルを 共有ドキュメント フォルダーに追加します。配列バッファーは POST 要求の本文で渡されます。Add the file to the Shared Documents folder by using the Add method on the folder's file collection. The array buffer is passed in the body of the POST request.

    これらの例ではファイル コレクションに到達するために getfolderbyserverrelativeurl エンドポイントを使用しますが、リスト エンドポイント (例: …/_api/web/lists/getbytitle('<list title>')/rootfolder/files/add) も使用できます。These examples use the getfolderbyserverrelativeurl endpoint to reach the file collection, but you can also use a list endpoint (example: …/_api/web/lists/getbytitle('<list title>')/rootfolder/files/add).

  3. アップロードしたファイルの ListItemAllFields プロパティを使用して、アップロードしたファイルに対応するリスト項目を取得します。Get the list item that corresponds to the uploaded file by using the ListItemAllFields property of the uploaded file.

  4. MERGE 要求を使用して、リスト アイテムの表示名とタイトルを変更します。Change the display name and title of the list item by using a MERGE request.

コード例の実行Running the code examples

この記事の両方のコード例では、REST API と jQuery AJAX 要求を使用して、ファイルを共有ドキュメント フォルダーにアップロードしてから、リスト アイテムのプロパティを変更します。Both code examples in this article use the REST API and jQuery AJAX requests to upload a file to the Shared Documents folder and then change list item properties.

最初の例は、SharePoint ホスト型アドインでファイルをホスト Web にアップロードする際に行うように、SP.AppContextSite を使用して複数の SharePoint ドメインにまたがって呼び出しを行います。The first example uses SP.AppContextSite to make calls across SharePoint domains, like a SharePoint-hosted add-in would do when uploading files to the host web.

2 番目の例では、SharePoint ホスト型アドインがファイルをアドイン Web にアップロードするときのように、または、サーバー上で実行されているソリューションがファイルをアップロードするときのように、同一ドメイン呼び出しを行います。The second example makes same-domain calls, like a SharePoint-hosted add-in would do when uploading files to the add-in web, or a solution that's running on the server would do when uploading files.

注意

JavaScript で記述されたプロバイダー向けのホスト型アドインは、SP.RequestExecutor クロスドメイン ライブラリを使用して SharePoint ドメインに要求を送信する必要があります。Provider-hosted add-ins written in JavaScript must use the SP.RequestExecutor cross-domain library to send requests to a SharePoint domain. 例については、「クロスドメイン ライブラリを使用してファイルをアップロードする」を参照してください。For an example, see upload a file by using the cross-domain library.

この記事の例を使用するには、次のものが必要です。To use the examples in this article, you'll need the following:

  • SharePoint Server または SharePoint Online。SharePoint Server or SharePoint Online.

  • コードを実行するユーザーのドキュメント ライブラリに対する書き込みアクセス許可。Write permissions to the Documents library for the user running the code. SharePoint アドインを開発している場合は、List スコープでアドイン書き込みアクセス許可を指定できます。If you're developing a SharePoint Add-in, you can specify Write add-in permissions at the List scope.

  • FileReader API (HTML5) 対応のブラウザー。Browser support for the FileReader API (HTML5).

  • ページ マークアップでの jQuery ライブラリの参照。次に例を示します。A reference to the jQuery library in your page markup. For example:

    <script src="https://ajax.aspnetcdn.com/ajax/jQuery/jquery-1.9.1.min.js" type="text/javascript"></script>
    
  • ページ マークアップの次のコントロール。The following controls in your page markup.

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

コード例 1: REST API と jQuery を使用して、ファイルを複数の SharePoint ドメインにまたがってアップロードするCode example 1: Upload a file across SharePoint domains by using the REST API and jQuery

次のコード例では SharePoint REST API および jQuery AJAX 要求を使用してファイルを ドキュメント ライブラリにアップロードし、ファイルを表すリスト項目のプロパティを変更します。この例のコンテキストは、ファイルをホスト Web 上のフォルダーにアップロードする SharePoint でホスト型アドインのものです。The following code example uses the SharePoint REST API and jQuery AJAX requests to upload a file to the Documents library and to change properties of the list item that represents the file. The context for this example is a SharePoint-hosted add-in that uploads a file to a folder on the host web.

この例を使用するには、これらの要件を満たす必要があります。You need to meet these requirements to use this example.

'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("&amp;");
    for (var i = 0; i < params.length; i = i + 1) {
        var singleParam = params[i].split("=");
        if (singleParam[0] == paramToRetrieve) return singleParam[1];
    }
}

コード例 2: REST API と jQuery を使用して、ファイルを同一ドメインにアップロードするCode example 2: Upload a file in the same domain by using the REST API and jQuery

次のコード例では SharePoint REST API および jQuery AJAX 要求を使用してファイルを ドキュメント ライブラリにアップロードし、ファイルを表すリスト項目のプロパティを変更します。この例のコンテキストは、サーバー上で実行されているソリューションのものです。このコードは、ファイルをアドイン Web にアップロードする SharePoint ホスト型アドインのものと似ています。The following code example uses the SharePoint REST API and jQuery AJAX requests to upload a file to the Documents library and to change properties of the list item that represents the file. The context for this example is a solution that's running on the server. The code would be similar in a SharePoint-hosted add-in that uploads files to the add-in web.

この例を実行する前に、これらの要件を満たす必要があります。You need to meet these requirements before you can run this example.

'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);
}

関連項目See also