REST インターフェイスを使用してリストにカスタム アクセス許可を設定するSet custom permissions on a list by using the REST interface

SharePoint のサイト、リスト、およびリスト アイテムは、SecurableObject の種類です。SharePoint sites, lists, and list items are types of SecurableObject. 既定では、セキュリティ設定が可能なオブジェクトは親のアクセス許可を継承します。By default, a securable object inherits the permissions of its parent. オブジェクトのカスタム アクセス許可を設定するには、継承を解除して、親からのアクセス許可の継承を停止した後、ロールの割り当てを追加または削除して、新しいアクセス許可を定義する必要があります。To set custom permissions for an object, you need to break its inheritance so that it stops inheriting permissions from its parent, and then define new permissions by adding or removing role assignments.

注意

詳細なアクセス許可の設定に関する記事へのリンクは、「関連項目」セクションを参照してください。See the See also section for links to articles about setting fine-grained permissions.

この記事のコードの例は、リストのカスタム アクセス許可を設定して、グループのアクセス許可を変更します。例では REST インターフェイスを使用して、次の処理を行います。The code example in this article sets custom permissions on a list, and then changes a group's permissions to it. The example uses the REST interface to:

  • ターゲット グループの ID を取得します。例では、グループ ID を使用して、リストのグループの現在のロールのバインドを取得し、新しいロールをリストに追加しています。Get the ID of the target group. The example uses the group ID to get the current role bindings for the group on the list and to add the new role to the list.

  • グループの新しいアクセス許可を定義するロール定義の ID を取得します。この ID は新しいロールをリストに追加するために使用します。この例では、新しいロールに対して既存のロール定義を使用していますが、オプションで新しいロール定義を作成することもできます。Get the ID of the role definition that defines the new permissions for the group. The ID is used to add the new role to the list. This example uses an existing role definition for the new role, but you can optionally create a new role definition.

  • BreakRoleInheritance メソッドを使用してリストのロールの継承を解除します。Break role inheritance on the list by using the BreakRoleInheritance method. 例では、ロールの継承を解除しますが、現在のロールのセットは保持します。The example breaks role inheritance but keeps the current set of roles. (または、ロールの割り当てをコピーせずに、現在のユーザーを管理アクセス許可レベルに追加する方法も選択できます。)(Alternatively, you can choose not to copy any role assignments and to add the current user to the Manage permission level.)

  • DELETE 要求をロールの割り当てエンドポイントに送信することで、リストに対するグループの現在のロール割り当てを削除します。(ロールの割り当てをコピーしないことを選択した場合は、この手順をスキップします。)Remove the group's current role assignment on the list by sending a DELETE request to the role assignment endpoint. (If you choose not to copy any role assignments, you would skip this step.)

  • AddRoleAssignment メソッドを使用してグループのロールの割り当てをリストに追加します。これにより、グループがロール定義にバインドされ、ロールがリストに追加されます。Add a role assignment for the group to the list by using the AddRoleAssignment method, which binds the group to the role definition and adds the role to the list.

この記事の例を使用するための前提条件Prerequisites for using the example in this article

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

  • SharePoint 開発環境 (オンプレミス シナリオではアプリの分離が必要)A SharePoint development environment (app isolation required for on-premises scenarios)

  • Office Developer Tools for Visual Studio 2012 を含む Visual Studio 2012 か Visual Studio 2013、またはそれ以降のバージョンVisual Studio 2012 or Visual Studio 2013 with Office Developer Tools for Visual Studio 2012, or later

Web スコープで Full Control アドインのアクセス許可を設定することも必要です。リストのアクセス許可を変更するのに十分なアクセス許可を持っているユーザー (リストの所有者など) だけが、このアドインを実行できます。You'll also need to set Full Control add-in permissions at the Web scope. Only users who have sufficient permissions to change list permissions (such as site owners) can run this add-in.

例: REST インターフェイスを使用してリストにカスタム アクセス許可を設定するExamples: Set custom permissions on a list by using the REST interface

次の例に、SharePoint ホスト型アドインの App.js ファイルの内容を示します。最初の例は、JavaScript クロス ドメイン ライブラリを使用して HTTP 要求を作成して送信します。2 番目の例は、jQuery AJAX 要求を使用します。The following examples represent the contents of the App.js file in a SharePoint-hosted add-in. The first example uses the JavaScript cross-domain library to build and send HTTP requests. The second example uses jQuery AJAX requests.

コードを実行する前に、プレースホルダーの値を実際の値に置き換えます。Before you run the code, replace the placeholder values with actual values. 別の言語や環境を使用している場合、いくつかの要求コンポーネントを追加または変更する必要があります。If you're using a different language or environment, you need to add or change some request components. 詳細については、「環境によって異なる REST 要求の方法」を参照してください。For more information, see How REST requests differ by environment.

例 1: クロスドメイン ライブラリの要求Example 1: Cross-domain library requests

'use strict';

// Change placeholder values before you run this code.
var listTitle = 'List 1';
var groupName = 'Group A';
var targetRoleDefinitionName = 'Contribute';
var appweburl;
var hostweburl;
var executor;
var groupId;
var targetRoleDefinitionId;

$(document).ready( function() {

    //Get the URI decoded URLs.
    hostweburl = decodeURIComponent(getQueryStringParameter("SPHostUrl"));
    appweburl = decodeURIComponent(getQueryStringParameter("SPAppWebUrl"));

    // Load the cross-domain library file and continue to the custom code.
    var scriptbase = hostweburl + "/_layouts/15/";
    $.getScript(scriptbase + "SP.RequestExecutor.js", getTargetGroupId);
});

// Get the ID of the target group.
function getTargetGroupId() {
    executor = new SP.RequestExecutor(appweburl);
    var endpointUri = appweburl + "/_api/SP.AppContextSite(@target)/web/sitegroups/getbyname('";
    endpointUri += groupName + "')/id" + "?@target='" + hostweburl + "'";

    executor.executeAsync({
        url: endpointUri,
        method: 'GET',
        headers: { 'accept':'application/json;odata=verbose' },
        success: function(responseData) {
            var jsonObject = JSON.parse(responseData.body);
            groupId = jsonObject.d.Id;
            getTargetRoleDefinitionId();
        },
        error: errorHandler
   });
}

// Get the ID of the role definition that defines the permissions
// you want to assign to the group.
function getTargetRoleDefinitionId() {
    var endpointUri = appweburl + "/_api/SP.AppContextSite(@target)/web/roledefinitions/getbyname('";
    endpointUri += targetRoleDefinitionName + "')/id" + "?@target='" + hostweburl + "'";

    executor.executeAsync({
        url: endpointUri,
        method: 'GET',
        headers: { 'accept':'application/json;odata=verbose' },
        success: function(responseData) {
            var jsonObject = JSON.parse(responseData.body)
            targetRoleDefinitionId = jsonObject.d.Id;
            breakRoleInheritanceOfList();
        },
        error: errorHandler
    });
}

// Break role inheritance on the list.
function breakRoleInheritanceOfList() {
    var endpointUri = appweburl + "/_api/SP.AppContextSite(@target)/web/lists/getbytitle('";
    endpointUri += listTitle + "')/breakroleinheritance(true)?@target='" + hostweburl + "'";

    executor.executeAsync({
        url: endpointUri,
        method: 'POST',
        headers: { 'X-RequestDigest':$('#__REQUESTDIGEST').val() },
        success: deleteCurrentRoleForGroup,
        error: errorHandler
    });
}

// Remove the current role assignment for the group on the list.
function deleteCurrentRoleForGroup() {
    var endpointUri = appweburl + "/_api/SP.AppContextSite(@target)/web/lists/getbytitle('";
    endpointUri += listTitle + "')/roleassignments/getbyprincipalid('" + groupId + "')?@target='" + hostweburl + "'";

    executor.executeAsync({
        url: endpointUri,
        method: 'POST',
        headers: { 
            'X-RequestDigest':$('#__REQUESTDIGEST').val(),
            'X-HTTP-Method':'DELETE'
        },
        success: setNewPermissionsForGroup,
        error: errorHandler
    });
}

// Add the new role assignment for the group on the list.
function setNewPermissionsForGroup() {
    var endpointUri = appweburl + "/_api/SP.AppContextSite(@target)/web/lists/getbytitle('";
    endpointUri += listTitle + "')/roleassignments/addroleassignment(principalid=" + groupId;
    endpointUri += ",roledefid=" + targetRoleDefinitionId + ")?@target='" + hostweburl + "'";

    executor.executeAsync({
        url: endpointUri,
        method: 'POST',
        headers: { 'X-RequestDigest':$('#__REQUESTDIGEST').val() },
        success: successHandler,
        error: errorHandler
    });
}

// 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];
    }
}

function successHandler() {
    alert('Request succeeded.');
} 

function errorHandler(xhr, ajaxOptions, thrownError) {
    alert('Request failed: ' + xhr.status + '\n' + thrownError + '\n' + xhr.responseText);
}

例 2: JQuery AJAX の要求Example 2: jQuery AJAX requests

// Change placeholder values before you run this code.
var siteUrl = 'http://server/site';
var listTitle = 'List 1';
var groupName = 'Group A';
var targetRoleDefinitionName = 'Contribute';
var groupId;
var targetRoleDefinitionId;

$(document).ready( function() {
    getTargetGroupId();
});

// Get the ID of the target group.
function getTargetGroupId() {
    $.ajax({
        url: siteUrl + '/_api/web/sitegroups/getbyname(\'' + groupName + '\')/id',
        type: 'GET',
        headers: { 'accept':'application/json;odata=verbose' },
        success: function(responseData) {
            groupId = responseData.d.Id;
            getTargetRoleDefinitionId();
        },
        error: errorHandler
   });
}

// Get the ID of the role definition that defines the permissions
// you want to assign to the group.
function getTargetRoleDefinitionId() {
    $.ajax({
        url: siteUrl + '/_api/web/roledefinitions/getbyname(\''
            + targetRoleDefinitionName + '\')/id',
        type: 'GET',
        headers: { 'accept':'application/json;odata=verbose' },
        success: function(responseData) {
            targetRoleDefinitionId = responseData.d.Id;
            breakRoleInheritanceOfList();
        },
        error: errorHandler
    });
}

// Break role inheritance on the list.
function breakRoleInheritanceOfList() {
    $.ajax({
        url: siteUrl + '/_api/web/lists/getbytitle(\'' + listTitle
            + '\')/breakroleinheritance(true)',
        type: 'POST',
        headers: { 'X-RequestDigest':$('#__REQUESTDIGEST').val() },
        success: deleteCurrentRoleForGroup,
        error: errorHandler
    });
}

// Remove the current role assignment for the group on the list.
function deleteCurrentRoleForGroup() {
    $.ajax({
        url: siteUrl + '/_api/web/lists/getbytitle(\'' + listTitle
            + '\')/roleassignments/getbyprincipalid(' + groupId + ')',
        type: 'POST',
        headers: { 
            'X-RequestDigest':$('#__REQUESTDIGEST').val(),
            'X-HTTP-Method':'DELETE'
        },
        success: setNewPermissionsForGroup,
        error: errorHandler
    });
}

// Add the new role assignment for the group on the list.
function setNewPermissionsForGroup() {
    $.ajax({
        url: siteUrl + '/_api/web/lists/getbytitle(\'' + listTitle
            + '\')/roleassignments/addroleassignment(principalid='
            + groupId + ',roledefid=' + targetRoleDefinitionId + ')',
        type: 'POST',
        headers: { 'X-RequestDigest':$('#__REQUESTDIGEST').val() },
        success: successHandler,
        error: errorHandler
    });
}

function successHandler() {
    alert('Request succeeded.');
} 

function errorHandler(xhr, ajaxOptions, thrownError) {
    alert('Request failed: ' + xhr.status + '\n' + thrownError + '\n' + xhr.responseText);
}

関連項目See also