ユーザー、グループ、およびロール REST API リファレンス

[アーティクル]
07/18/2016

User、Group、RoleAssigment、RoleDefinition、UserCustomAction、および関連したリソースの REST API について説明します。

適用対象: apps for SharePoint | SharePoint Foundation 2013 | SharePoint Online | SharePoint Server 2013

この記事の内容
この記事の要求の例について
SharePoint 2013 ユーザーおよびグループ REST 構文の探索
Group リソース
GroupCollection リソース
RoleAssignment リソース
RoleAssignmentCollection リソース
RoleDefinition リソース
RoleDefinitionCollection リソース
RoleDefinitionBindingCollection リソース
User リソース
UserCollection リソース
UserCustomAction リソース
UserCustomActionCollection リソース
追加リソース

この記事の要求の例について

この記事の要求の例は、クロスドメイン要求を行うためにクロスドメインライブラリ (SP.RequestExecutor.js) を使用していることを前提としています。このため、エンドポイント URI で SP.AppContextSite を使用します。詳細については、「クロスドメインライブラリを使用してアドインから SharePoint 2013 のデータにアクセスする」を参照してください。

要求の例を使用する前に、次の操作を実行してください。

<アプリ web url>、<ホスト web url>、および ID、名前、SharePoint エンティティのパスなどその他プレースホルダーのデータを変更します。
クロスドメインライブラリを使用していない場合は、すべての POST 要求のフォームダイジェストの値を送信する X-RequestDigest ヘッダー、および要求本文でデータを送信する POST 要求のための content-length ヘッダーを含めます。
クロスドメイン要求を行わない場合は、SP.AppContextSite(@target) および ?@target='<host web url>' をエンドポイント URI から削除します。
OAuth を使用する場合は、Authorization ヘッダー ("Authorization": "Bearer " + <access token>) を含めて OAuth アクセストークンを送信します。
要求の例の url および body プロパティ値から改行を削除します。改行は、例を分かりやすくするために追加されています。
サーバーが Atom 形式で応答を返すようにするには、"accept": "application/json; odata=verbose" ヘッダーを削除します。

クロスドメインライブラリ、OAuth、および SharePoint REST サービスの使用法についての詳細は、「その他の技術情報」を参照してください。要求形式についての詳細は、「環境によって異なる REST 要求の方法」および「REST 要求で使うプロパティ」を参照してください。

ヒント

SharePoint Online REST サービスは、OData $batch クエリオプションを使用して複数の要求を、サービスに対する 1 つの呼び出しに結合できます。詳細とコードサンプルへのリンクについては、「REST API によりバッチ要求を発行する」をご覧ください。このオプションは、オンプレミスの SharePoint ではサポートされていません。

SharePoint 2013 ユーザーおよびグループ REST 構文の探索

SharePoint 2013 ユーザーおよびグループの REST 構文を視覚的に表示します。

その他の SharePoint REST 構文の図を探索します。

ファイルおよびフォルダー | リストおよびリストアイテム

すべての SharePoint REST 構文の図が統合された PDF をダウンロードします。

Group リソース

SharePoint サイト中のユーザーの集まりを表します。Group は、SP.Principal の一種です。

エンドポイント URI | プロパティ | OData 表現

エンドポイント URI

http://<site url>/_api/web/sitegroups(<group id>)

サポートされる HTTP メソッド

GET | POST | MERGE | PUT

要求の例

GET 要求の例: グループを取得します

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /sitegroups(5)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

LoginName によりグループを取得することもできます。「GetByName メソッド」をご覧ください。

MERGE 要求の例: グループを変更します

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /sitegroups(5)
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata':{ 'type': 'SP.Group' }, 'Description':'New description of the group' }",
  headers: {
    "content-type": "application/json; odata=verbose",
    "X-HTTP-Method": "MERGE"
  },
  success: successHandler,
  error: errorHandler
});

グループにユーザーを追加するには、「UserCollection 要求例」に示すとおり、グループのユーザーコレクションにユーザーを追加します。グループからユーザーを削除するには、UserCollection リソースの RemoveById メソッドまたは RemoveByLoginName メソッドを使用します。

PUT 要求の例: グループを置き換えます

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /sitegroups(30)
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata':{ 'type': 'SP.Group' }, 'Title':'Training',
    'Description':'Description of new group', 'AllowMembersEditMembership':'false',
    'AllowRequestToJoinLeave':'false', 'AutoAcceptRequestToJoinLeave':'false',
    'OnlyAllowMembersViewMembership':'true', 'RequestToJoinLeaveEmailSetting':'true' }",
  headers: {
    "content-type": "application/json; odata=verbose",
    "X-HTTP-Method": "PUT"
  },
  success: successHandler,
  error: errorHandler
});

RemoveById メソッドまたは RemoveByLoginName メソッドを使用してグループを削除します。グループを作成するには、POST 要求を GroupCollection リソースに送ります。例については、「GroupCollection 要求例」をご覧ください。

Group のプロパティ

プロパティを取得するには、次の例に示すように、GET 要求をプロパティエンドポイントに送ります。

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /sitegroups(5)/<property name>
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

プロパティ	型	R/W	リソースとともに返される	説明
AllowMembersEditMembership	Boolean	RW	はい	グループメンバーがグループのメンバーシップを編集できるかどうかを示す値を取得または設定します。
AllowRequestToJoinLeave	Boolean	RW	はい	グループのメンバーシップやグループからの脱退をユーザーが要求できるかどうかを示す値を取得または設定します。
AutoAcceptRequestToJoinLeave	Boolean	RW	いいえ	グループに対する参加または脱退の要求を自動的に受け入れることができるかどうかを示す値を取得または設定します。
CanCurrentUserEditMembership	Boolean	R	いいえ	現在のユーザーがグループのメンバーシップを編集できるかどうかを示す値を取得します。
CanCurrentUserManageGroup	Boolean	R	いいえ	現在のユーザーがグループを管理できるかどうかを示す値を取得します。
CanCurrentUserViewMembership	Boolean	R	いいえ	現在のユーザーがグループのメンバーシップを表示できるかどうかを示す値を取得します。
Description	String	RW	はい	グループの説明を取得または設定します。
Id	Int32	R	はい	ユーザーまたはグループのメンバー識別子を示す値を取得します。
IsHiddenInUI	Boolean	R	はい	このメンバーを UI で非表示にする必要があるかどうかを示す値を取得します。
LoginName	String	R	はい	グループの名前を取得します。
OnlyAllowMembersViewMembership	Boolean	RW	はい	グループメンバーのみがグループのメンバーシップを表示できるかどうかを示す値を取得または設定します。
Owner	SP.Principal	RW	いいえ	制御セキュリティの権限を割り当てられたユーザーまたは別のグループである所有者を、取得または設定します。
OwnerTitle	String	R	はい	このグループの所有者の名前を取得します。
RequestToJoinLeaveEmailSetting	String	RW	はい	メンバーシップの要求の送信先となる電子メールアドレスを取得または設定します。
PrincipalType	Int32	R	はい	プリンシパルの種類が含まれている値を取得します。ビット単位の SP.PrincipalType 値を表します。None = 0、User = 1、DistributionList = 2、SecurityGroup = 4、SharePointGroup = 8、All = 15。
Title	String	RW	はい	プリンシパルの名前を指定する値を取得または設定します。
Users	SP.UserCollection	R	いいえ	グループ内のすべてのユーザーを表すユーザーオブジェクトのコレクションを取得します。

OData 表現

次の例は、JSON 形式による Group リソースを表します。

    {"d":{
      "__metadata":{,
        "id":"https://<site url>/_api/Web/SiteGroups/GetById(5)",
        "uri":"https://<site url>/_api/Web/SiteGroups/GetById(5)",
       "type":"SP.Group"
      },
      "Owner":{"__deferred":{"uri":"https://<site url>/_api/Web/SiteGroups/GetById(5)/Owner"}},
      "Users":{"__deferred":{"uri":"https://<site url>/_api/Web/SiteGroups/GetById(5)/Users"}},
      "Id":5,
      "IsHiddenInUI":false,
      "LoginName":"Members",
      "Title":"Members",
      "PrincipalType":8,
      "AllowMembersEditMembership":false,
      "AllowRequestToJoinLeave":false,
      "AutoAcceptRequestToJoinLeave":false,
      "Description":"Use this group to grant people contribute permissions to the SharePoint site: ",
      "OnlyAllowMembersViewMembership":false,
      "OwnerTitle":"Owners",
      "RequestToJoinLeaveEmailSetting":""
    }}

GroupCollection リソース

Group リソースのコレクションを表します。

エンドポイント URI | メソッド | OData 表現

エンドポイント URI

http://<site url>/_api/web/sitegroups

サポートされる HTTP メソッド

GET | POST

要求の例

GET 要求の例: ルートサイトのグループを取得します

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /sitegroups
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GET 要求の例: グループを取得します

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /sitegroups(5)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

LoginName によりグループを取得することもできます。「GetByName メソッド」をご覧ください。

POST 要求の例: グループを作成します

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /sitegroups
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata':{ 'type': 'SP.Group' }, 'Title':'New Group' }",
  headers: { "content-type": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

グループの変更方法については、「Group 要求の例」をご覧ください。

GroupCollection メソッド

GetById
GetByName
RemoveById
RemoveByLoginName

GetById メソッド

グループのメンバー ID に基づいてコレクションからグループを返します。

エンドポイント	/getbyid(<group id>)
HTTP メソッド	GET
パラメーター	型: Int32 取得するグループの ID。
応答	型: SP.Group 指定されたグループ。

要求の例

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups
    /getbyid(5)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

または単に、GroupCollection リソースのグループ ID を指定することもできます。例: …/_api/web/sitegroups(5)

GetByName メソッド

グループの名前に基づいて、コレクションからクロスサイトグループを返します。

エンドポイント	/getbyname('<group name>')
HTTP メソッド	GET
パラメーター	型: String グループの名前。グループ名は、LoginName プロパティで指定します。
応答	型: SP.Group 指定されたグループ。

要求の例

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups
    /getbyname('content site owners')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

RemoveById メソッド

指定されたメンバー ID を持つグループを、コレクションから削除します。

エンドポイント	/removebyid(<group id>)
HTTP method	POST
パラメーター	型: Int32 削除するグループの ID。
応答	なし

要求の例

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups
    /removebyid(17)
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

RemoveByLoginName メソッド

指定された名前を持つクロスサイトグループをコレクションから削除します。

エンドポイント	/removebyloginname('<group name>')
HTTP method	POST
パラメーター	型: String 削除するグループの名前。グループ名はLoginName プロパティで指定します。
応答	なし

要求の例

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups
    /removebyloginname('training')
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

OData 表現

次の例は、JSON 形式による GroupCollection リソースを表します。

    {"d":{
      "results":[{
        "__metadata":{
          "id":"https://<site url>/_api/Web/SiteGroups/GetById(7)",
          "uri":"https://<site url>/_api/Web/SiteGroups/GetById(7)",
          "type":"SP.Group"
        },
        "Owner":{"__deferred":{"uri":"https://<site url>/_api/Web/SiteGroups/GetById(7)/Owner"}},
        "Users":{"__deferred":{"uri":"https://<site url>/_api/Web/SiteGroups/GetById(7)/Users"}},
        "Id":7,
        "IsHiddenInUI":false,
        "LoginName":"Excel Services Viewers",
        "Title":"Excel Services Viewers",
        "PrincipalType":8,
        "AllowMembersEditMembership":false,
        "AllowRequestToJoinLeave":false,
        "AutoAcceptRequestToJoinLeave":false,
        "Description":"Members of this group can view pages, list items, and documents. If the document has a server rendering available, they can only view the document using the server rendering.",
        "OnlyAllowMembersViewMembership":true,
        "OwnerTitle":"Owners",
        "RequestToJoinLeaveEmailSetting":null
        },{
        "__metadata":{
          "id":"https://<site url>/_api/Web/SiteGroups/GetById(5)",
          "uri":"https://<site url>/_api/Web/SiteGroups/GetById(5)",
          "type":"SP.Group"
        },
        "Owner":{"__deferred":{"uri":"https://<site url>/_api/Web/SiteGroups/GetById(5)/Owner"}},
        "Users":{"__deferred":{"uri":"https://<site url>/_api/Web/SiteGroups/GetById(5)/Users"}},
        "Id":5,
        "IsHiddenInUI":false,
        "LoginName":"Members",
        "Title":"Members",
        "PrincipalType":8,
        "AllowMembersEditMembership":false,
        "AllowRequestToJoinLeave":false,
        "AutoAcceptRequestToJoinLeave":false,
        "Description":"Use this group to grant people contribute permissions to the SharePoint site: ",
        "OnlyAllowMembersViewMembership":false,
        "OwnerTitle":"Owners",
        "RequestToJoinLeaveEmailSetting":""
        },
        ...
      }]
    }}

RoleAssignment リソース

Web サイト、リスト、またはリストアイテム上でユーザーまたはグループに対するセキュリティ設定が可能なオブジェクトのロール割り当てを定義します。

エンドポイント URI | プロパティ | メソッド | OData 表現

エンドポイント URI

http://<site url>/_api/web/roleassignments(<principal id>)

サポートされる HTTP メソッド

GET | POST | DELETE

要求の例

GET 要求の例: ロールの割り当てを取得します

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roleassignments(3)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

DELETE 要求の例: ロールの割り当てを削除します

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roleassignments(3)
    ?@target='<host web url>'",
  method: "POST",
  headers: { "X-HTTP-Method": "DELETE" },
  success: successHandler,
  error: errorHandler
});

または、RemoveRoleAssignment メソッドを使用してロールの割り当てを削除することができます。ロールの割り当てを作成するには、AddRoleAssignment メソッドを使用します。

RoleAssignment のプロパティ

プロパティを取得するには、次の例に示すように、GET 要求をプロパティエンドポイントに送ります。

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /roleassignments(3)/<property name>
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

プロパティ	型	R/W	リソースとともに返される	説明
Member	SP.Principal	R	いいえ	ロールの割り当てに対応するユーザーまたはグループを取得します。
PrincipalId	Int32	R	はい	ロールの割り当ての一意識別子。
RoleDefinitionBindings	SP.RoleDefinitionCollection	R	いいえ	ロールの割り当てのロール定義バインドのコレクションを取得します。

RoleAssignment メソッド

DeleteObject

DeleteObject メソッド

ロールの割り当てを削除するために推奨される方法は、「RoleAssignment 要求の例」に示すように、RemoveRoleAssignment メソッドを使用するか、DELETE 要求を RoleAssignment リソースエンドポイントに送ることです。

OData 表現

次の例は、JSON 形式による RoleAssignment リソースを表します。

    {"d":{
      "__metadata":{,
        "id":"https://<site url>/_api/Web/RoleAssignments/GetByPrincipalId(3)",
        "uri":"https://<site url>/_api/Web/RoleAssignments/GetByPrincipalId(3)",
        "type":"SP.RoleAssignment"
      },
      "Member":{"__deferred":{"uri":"https://<site url>/_api/Web/RoleAssignments/GetByPrincipalId(3)/Member"}},
      "RoleDefinitionBindings":{"__deferred":{"uri":"https://<site url>/_api/Web/RoleAssignments/GetByPrincipalId(3)/RoleDefinitionBindings"}},
      "PrincipalId":3
    }}

RoleAssignmentCollection リソース

RoleAssignment リソースのコレクションを表します。

エンドポイント URI | プロパティ | メソッド | OData 表現

エンドポイント URI

http://<site url>/_api/web/roleassignments

サポートされる HTTP メソッド

GET | POST

要求の例

GET 要求の例: ロールの割り当てを取得します

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roleassignments(3)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

ロールの割り当てを削除するには、AddRoleAssignment メソッドを使用します。ロールの割り当てを削除するには、「RoleAssignment 要求例」に示すように、RemoveRoleAssignment メソッドを使用するか、DELETE 要求を RoleAssignment リソースエンドポイントに送ります。

RoleAssignmentCollection のプロパティ

プロパティを取得するには、次の例に示すように、GET 要求をプロパティエンドポイントに送ります。

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roleassignments(3)/groups
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

プロパティ	型	R/W	リソースとともに返される	説明
Groups	SP.GroupCollection	R	いいえ	このセキュリティ設定が可能なオブジェクトのアクセス制御リスト (ACL) に直接属するグループを取得します。

RoleAssignmentCollection メソッド

AddRoleAssignment
GetByPrincipalId
RemoveRoleAssignment

AddRoleAssignment メソッド

指定されたプリンシパルとロール定義を持つ新しいロール割り当てをコレクションに追加します。

エンドポイント	/addroleassignment(principalid、roledefid)
パラメーター	principalid 型: Int32 アクセス許可を割り当てるユーザーまたはグループの ID。 roledefid 型: Int32 割り当てるアクセス許可を定義するロール定義の ID。ロール定義を作成する方法の例については、「RoleDefinitionCollection 要求の例」をご覧ください。
HTTP method	POST
応答	なし

要求の例

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roleassignments
    /addroleassignment(principalid=21, roledefid=1073741827)
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

権限を継承するオブジェクトでこのメソッドを使用するには、最初にオブジェクトで BreakRoleInheritance メソッドを呼び出す必要があります。「REST インターフェイスを使用してリストにカスタムアクセス許可を設定する」を参照してください。

GetByPrincipalId メソッド

指定されたプリンシパル ID と関連付けられているロール割り当てをコレクションから取得します。

エンドポイント	/getbyprincipalid(<prinicipal id>)
パラメーター	型: Int32 取得するロールの割り当ての PrincipalId。
HTTP method	GET
応答	型: SP.RoleAssignment 指定されたロールの割り当て。

要求の例

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roleassignments
    /getbyprincipalid(3)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

または単に、 RoleAssignmentCollection リソースでロール割り当てのプリンシパル ID を指定することもできます。例: …/_api/web/roleassignments(3)

RemoveRoleAssignment メソッド

指定されたプリンシパルとロール定義を持つ新しいロール割り当てをコレクションから削除します。

エンドポイント	/removeroleassignment(principalid、roledefid)
パラメーター	principalid 型: Int32 ロール割り当ての中のユーザーまたはグループの ID。 roledefid 型: Int32 ロール割り当ての中のユーザーまたはグループの ID。
HTTP method	POST
応答	なし

要求の例

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roleassignments
    /removeroleassignment(principalid=21, roledefid=1073741827)
    ?@target='<host web url>'",
  method: "POST",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

OData 表現

次の例は、JSON 形式による RoleAssignmentCollection リソースを表します。

    {"d":{
      "results":[{
        "__metadata":{
          "id":"http://<site url>/_api/Web/RoleAssignments/GetByPrincipalId(1)",
          "uri":"http://<site url>/_api/Web/RoleAssignments/GetByPrincipalId(1)",
          "type":"SP.RoleAssignment"
        },
        "Member":{"__deferred":{"uri":"http://<site url>/_api/Web/RoleAssignments/GetByPrincipalId(1)/Member"}},
        "RoleDefinitionBindings":{"__deferred":{"uri":"http://<site url>/_api/Web/RoleAssignments/GetByPrincipalId(1)/RoleDefinitionBindings"}},
        "PrincipalId":1
        },{
        "__metadata":{
          "id":"http://<site url>/_api/Web/RoleAssignments/GetByPrincipalId(3)",
          "uri":"http://<site url>/_api/Web/RoleAssignments/GetByPrincipalId(3)",
          "type":"SP.RoleAssignment"
        },
        "Member":{"__deferred":{"uri":"http://<site url>/_api/Web/RoleAssignments/GetByPrincipalId(3)/Member"}},
        "RoleDefinitionBindings":{"__deferred":{"uri":"http://<site url>/_api/Web/RoleAssignments/GetByPrincipalId(3)/RoleDefinitionBindings"}},
        "PrincipalId":3
        },{
        ...
      }]
    }}

RoleDefinition リソース

名前、説明、および権利セットを含む 1 つのロール定義を設定します。

エンドポイント URI | プロパティ | メソッド | OData 表現

エンドポイント URI

http://<site url>/_api/web/roledefinitions(<role definition id>)

サポートされる HTTP メソッド

GET | POST | DELETE | MERGE | PUT

要求の例

GET 要求の例: ロール定義の取得

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roledefinitions(1073741829)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

MERGE 要求の例: ロール定義の変更

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roledefinitions(1073741928)
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata': { 'type': 'SP.RoleDefinition' }, 'BasePermissions':
    { '__metadata': { 'type': 'SP.BasePermissions' }, 'High': '48' } }",
  headers: {
    "content-type": "application/json; odata=verbose",
    "X-HTTP-Method": "MERGE"
  },
  success: successHandler,
  error: errorHandler
});

PUT 要求例: ロール定義の置き換え

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roledefinitions(1073741928)
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata': { 'type': 'SP.RoleDefinition' }, 'BasePermissions':
    { '__metadata': { 'type': 'SP.BasePermissions' }, 'High': '48' }, 
   'Description': 'New description', 'Name': 'New name', 'Order': 170 }",
  headers: {
    "content-type": "application/json; odata=verbose",
    "X-HTTP-Method": "PUT"
  },
  success: successHandler,
  error: errorHandler
});

DELETE 要求例: ロール定義の削除

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roledefinitions(1073741928)
    ?@target='<host web url>'",
  method: "POST",
  headers: { "X-HTTP-Method": "DELETE" },
  success: successHandler,
  error: errorHandler
});

ロール定義を作成する方法の例については、「RoleDefinitionCollection 要求の例」をご覧ください。

RoleDefinition のプロパティ

プロパティを取得するには、次の例に示すように、GET 要求をプロパティエンドポイントに送ります。

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /roledefinitions(1073741829)/<property name>
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

プロパティ	型	R/W	リソースとともに返される	説明
BasePermissions	SP.BasePermissions	RW	はい	ロール定義に対する基本的なアクセス許可を指定する値を取得または設定します。
Description	String	RW	はい	ロール定義の説明を指定する値を取得または設定します。
Hidden	Boolean	R	はい	ロール定義が表示されるかどうかを示す値を取得します。
Id	Int32	R	はい	ロール定義の ID を示す値を取得します。
Name	String	RW	はい	ロール定義名を指定する値を取得または設定します。
Order	Int32	RW	はい	サイトコレクションの [アクセス許可レベル] ページでの順序位置を指定する値を取得または設定します。
RoleTypeKind	Int32	R	はい	ロール定義の種類を示す値を取得します。SP.RoleType 値を表します。ロールの種類の値のリストの詳細は, .NET クライアントオブジェクトモデルリファレンスの「RoleType」を参照してください。

RoleDefinition メソッド

DeleteObject

DeleteObject メソッド

ロール割り当てを削除するために推奨される方法は、「RoleDefinition 要求の例」に示すように、DELETE 要求を RoleDefinition リソースエンドポイントに送ることです。

OData 表現

次の例は、JSON 形式による RoleDefinition リソースを表します。

    {"d":{
      "__metadata":{,
        "id":"https://<site url>/_api/Web/RoleDefinitions(1073741829)",
        "uri":"https://<site url>/_api/Web/RoleDefinitions(1073741829)",
        "type":"SP.RoleDefinition"
      },
      "BasePermissions":{"__metadata":{"type":"SP.BasePermissions"}, "High":"2147483647", "Low":"4294967295"},
      "Description":"Has full control.",
      "Hidden":false,
      "Id":1073741829,
      "Name":"Full Control",
      "Order":1,
      "RoleTypeKind":5
    }}

RoleDefinitionCollection リソース

RoleDefinition リソースのコレクションを表します。

エンドポイント URI | メソッド | OData 表現

エンドポイント URI

http://<site url>/_api/web/roledefinitions

サポートされる HTTP メソッド

GET | POST

要求の例

GET 要求の例: ロール定義を取得します

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roledefinitions(1073741829)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

POST 要求の例: ロール定義を作成します

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roledefinitions
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata': { 'type': 'SP.RoleDefinition' }, 'BasePermissions': 
    { '__metadata': { 'type': 'SP.BasePermissions' }, 'High': '176' , 'Low': '138612801' }, 
    'Description': 'New description', 'Name': 'New role', 'Order': 180 }",
  headers: {
    "accept": "application/json; odata=verbose",
    "content-type": "application/json; odata=verbose"
  },
  success: successHandler,
  error: errorHandler
});

ロール定義を変更、または削除する方法の例については、「RoleDefinition 要求例」をご覧ください。

RoleDefinitionCollection メソッド

GetById
GetByName
GetByType

GetById メソッド

指定された ID を持つロール定義をコレクションから取得します。

エンドポイント	/getbyid(<role definition id>)
パラメーター	型: Int32 ロール定義の ID。
HTTP method	GET
応答	型: SP.RoleDefinition 指定されたロール定義。

要求の例

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roledefinitions
    /getbyid(1073741829)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

または単に、RoleDefinitionCollection リソースのロール定義 ID を指定することもできます。例: …/_api/web/roledefinitions(1073741829)

GetByName メソッド

指定された名前を持つロール定義を取得します。

エンドポイント	/getbyname('<role definition name>')
パラメーター	型: String ロール定義の名前。
HTTP method	GET
応答	型: SP.RoleDefinition 指定されたロール定義。

要求の例

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roledefinitions
    /getbyname('contribute')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GetByType メソッド

指定されたロールの種類を持つロール定義を取得します。

エンドポイント	/getbytype(<role definition type>)
パラメーター	型: Int32 ロール定義の RoleTypeKind。ロールの種類の値のリストの詳細は, .NET クライアントオブジェクトモデルリファレンスの「RoleType」を参照してください。
HTTP method	GET
応答	型: SP.RoleDefinition 指定されたロール定義。

要求の例

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roledefinitions
    /getbytype(5)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

OData 表現

次の例は、JSON 形式によるRoleDefinitionCollection リソースを表します。

    {"d":{
      "results":[{
        "__metadata":{
          "id":"https://<site url>/_api/Web/RoleDefinitions(1073741829)",
          "uri":"https://<site url>/_api/Web/RoleDefinitions(1073741829)",
          "type":"SP.RoleDefinition"
        },{
        "__metadata":{
          "type":"SP.BasePermissions"},
          "High":"2147483647",
          "Low":"4294967295"
        },
        "Description":"Has full control.",
        "Hidden":false,
        "Id":1073741829,
        "Name":"Full Control",
        "Order":1,
        "RoleTypeKind":5
        },{
        ...
      }]
    }}

RoleDefinitionBindingCollection リソース

ロール割り当てオブジェクトにバインドされたロール定義を定義します。

エンドポイント URI | OData 表現

エンドポイント URI

http://<site url>/_api/web/roleassignments(<role assignment id>)/roledefinitionbindings

サポートされる HTTP メソッド

GET

要求の例

GET 要求の例: ロール割り当てに対するロール定義のバンドを取得します

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roleassignments(7)
    /roledefinitionbindings
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler});

ロール定義にプリンシパル (ユーザーまたはグループ) をバインドするロールの割り当てを作成するには、AddRoleAssignment メソッドを使用します。ロール割り当てを削除するには、「RoleAssignment 要求例」に示すように、RemoveRoleAssignment メソッドを使用するか、DELETE 要求を RoleAssignment リソースエンドポイントに送ります。

OData 表現

次の例は、JSON 形式による RoleDefinitionBindingCollection リソースを表します。

    {"d":{
      "results":[{
        "__metadata":{
          "id":"http://<site url>/_api/Web/RoleDefinitions(1073741829)",
          "uri":"http://<site url>/_api/Web/RoleDefinitions(1073741829)",
          "type":"SP.RoleDefinition"
        },{
        "__metadata":{
          "type":"SP.BasePermissions"},
          "High":"2147483647",
          "Low":"4294967295"
        },
        "Description":"Has full control.",
        "Hidden":false,
        "Id":1073741829,
        "Name":"Full Control",
        "Order":1,
        "RoleTypeKind":5
        },{
        "__metadata":{
          "id":"http://<site url>/_api/Web/RoleDefinitions(1073741827)",
          "uri":"http://<site url>/_api/Web/RoleDefinitions(1073741827)",
          "type":"SP.RoleDefinition"
        },{
        "__metadata":{
          "type":"SP.BasePermissions"},
          "High":"432",
          "Low":"1011028719"
        },
        "Description":"Can view, add, update, and delete list items and documents.",
        "Hidden":false,
        "Id":1073741827,
        "Name":"Contribute",
        "Order":64,
        "RoleTypeKind":3
      }]
    }}

User リソース

Microsoft SharePoint Foundation 内のユーザーを表します。User は、SP.Principal の一種です。SP.Principal.

エンドポイント URI | プロパティ | OData 表現

エンドポイント URI

http://<site url>/_api/web/sitegroups(<group id>)/users(@v)?@v='<login name>'
http://<site url>/_api/web/siteusers(@v)?@v='<login name>'

ユーザーのログイン名の形式は、表 1 に示すように、SharePoint 環境により異なります。

表 1 ログイン名の形式

SharePoint 環境	ログイン名の形式例	クエリ文字列で別名を使用してログイン名を渡す方法
フォームを使用した SharePoint Online、または SharePoint 2013 オンプレミス	i:0#.f\|membership\|user@domain.com	…/users(@v)?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'
Windows クレームを使用した SharePoint 2013 オンプレミス	i:0#.w\|domain\user	…/users(@v)?@v='i%3A0%23.w%7Cdomain\user'
SAML クレームを使用した SharePoint 2013 オンプレミス	i:05:t\|adfs with roles\|user@domain.com	…/users(@v)?@v='i%3A05%3At%7Cadfs+with+roles%7Cuser%40domain.com'

注意

SAML (Security Assertion Markup Language) ベースのクレーム認証の例で使用するログイン名の形式は、 (ID クレーム) で電子メールアドレスまたはユーザーのプリンシパル名を使用するように構成されていることを前提としています。SAML クレーム認証は、SharePoint でホストされるアプリでは使用できません。

サポートされる HTTP メソッド

GET | POST | DELETE | MERGE | PUT

要求の例

GET 要求の例: ログイン名によりサイトからユーザーを取得します

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/siteusers(@v)
    ?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'
    &@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GET 要求の例: ID によりサイトからユーザーを取得します

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/getuserbyid(16)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GET 要求の例: ログイン名によりグループからユーザーを取得します

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups(7)
    /users(@v)?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'
    &@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

電子メールアドレスまたは ID によりグループからユーザーを取得することもできます。「GetByEmail メソッド」と「GetById メソッド」をご覧ください。

MERGE 要求の例: ユーザーの変更

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups(7)
    /users(@v)?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'
    &@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata':{ 'type': 'SP.User' }, 'Title':'New display name' }",
  headers: {
    "content-type": "application/json; odata=verbose",
    "X-HTTP-Method": "MERGE"
  },
  success: successHandler,
  error: errorHandler
});

PUT 要求の例: ユーザーを置き換えます

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups(7)
    /users(@v)?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'
    &@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata': { 'type': 'SP.User' }, 'Email':'user2@domain.com', 'IsSiteAdmin':false, 'Title':'User 2' }",
  headers: {
    "content-type": "application/json; odata=verbose",
    "X-HTTP-Method": "PUT"
  },
  success: successHandler,
  error: errorHandler});

グループにユーザーを追加する方法の例については、「UserCollection 要求例」をご覧ください。

DELETE 要求の例: グループからユーザーを削除します

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups(7)
    /users/getbyid(18)
    &@target='<host web url>'",
  method: "POST",
  headers: { "X-HTTP-Method": "DELETE" },
  success: successHandler,
  error: errorHandler
});

User リソースの DELETE メソッドを使用してユーザーを削除するには、GetById メソッドまたは GetByEmail メソッドを使用してユーザーコレクションからユーザーを削除する必要があります。または単に UserCollection リソースの RemoveById メソッドまたは RemoveByLoginName メソッドを使用することもできます。

User のプロパティ

プロパティを取得するには、次の例に示すように、GET 要求をプロパティエンドポイントに送ります。

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups(7)
    /users(@v)/<property name>?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'
    &@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

プロパティ	型	R/W	リソースとともに返される	説明
Email	String	RW	はい	このプロパティは、SharePoint Online では使用できません。ユーザーの電子メールアドレスを取得または設定します。
Groups	SP.GroupCollection	R	いいえ	ユーザーがメンバーとして属するグループのコレクションを取得します。
Id	Int32	R	はい	ユーザーまたはグループのメンバー識別子を示す値を取得します。
IsHiddenInUI	Boolean	R	はい	このメンバーを UI で非表示にする必要があるかどうかを示す値を取得します。
IsSiteAdmin	Boolean	RW	はい	ユーザーがサイトコレクション管理者であるかどうかを指定するブール値を取得または設定します。
LoginName	String	R	はい	ユーザーのログイン名を取得します。
PrincipalType	Int32	R	はい	プリンシパルの種類が含まれている値を取得します。ビット単位の SP.PrincipalType 値を表します。None = 0、User = 1、DistributionList = 2、SecurityGroup = 4、SharePointGroup = 8、All = 15。
Title	String	RW	はい	プリンシパルの名前を指定する値を取得または設定します。
UserId	SP.UserIdInfo	R	はい	ユーザーの名前識別子と、ユーザーの名前識別子の発行者を含むユーザー情報を取得します。

OData 表現

次の例は、JSON 形式による User リソースを表します。

    {"d":{
      "__metadata":{,
        "id":"http://<site url>/_api/Web/GetUserById(16)",
        "uri":"http://<site url>/_api/Web/GetUserById(16)",
        "type":"SP.User"
      },
      "Groups":{"__deferred":{"uri":"http://<site url>/_api/Web/GetUserById(16)/Groups"}},
      "Id":16,
      "IsHiddenInUI":false,
      "LoginName":"i:0#.w|domain\\user",
      "Title":"User Display Name",
      "PrincipalType":1,
      "Email":"user@company.com",
      "IsSiteAdmin":false,
      "UserId":{"__metadata":{"type":"SP.UserIdInfo"}, "NameId":"s-0-0-00-000000-0000000000-0000000000-000000", "NameIdIssuer":"issuer id" }
    }}

UserCollection リソース

User リソースのコレクションを表します。

エンドポイント URI | メソッド | OData 表現

エンドポイント URI

http://<site url>/_api/web/siteusers
http://<site url>/_api/web/sitegroups(<group id>)/users

サポートされる HTTP メソッド

GET | POST

要求の例

GET 要求の例: ログイン名によりユーザーを取得します

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/siteusers(@v)
    ?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'
    &@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GET 要求の例: グループのユーザーを取得します

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /sitegroups(7)/users
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

POST 要求の例: グループへのユーザーを追加します

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /sitegroups(7)/users
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata': { 'type': 'SP.User' }, 'LoginName':'i:0#.w|domain\\user' }",
  headers: {
    "accept": "application/json; odata=verbose",
    "content-type": "application/json; odata=verbose"
  },
  success: successHandler,
  error: errorHandler
});

UserCollection メソッド

GetByEmail
GetById
GetByLoginName
RemoveById
RemoveByLoginName

GetByEmail メソッド

指定された電子メールアドレスを持つユーザーを取得します。

エンドポイント	/getbyemail('<email address>')
パラメーター	型: String 取得するユーザーの電子メール。
HTTP method	GET
応答	型: SP.User 指定されたユーザー。

要求の例

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups(7)/users
    /getbyemail('user@domain.com'),
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GetById メソッド

指定されたメンバー識別子 (ID) を持つユーザーを取得します。

エンドポイント	/getbyid(<user id>)
パラメーター	型: Int32 取得するユーザーの ID。
HTTP method	GET
応答	型: SP.User 指定されたユーザー。

要求の例

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups(7)/users
    /getbyid(23)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GetByLoginName メソッド

指定したログイン名を持つユーザーを取得します。

エンドポイント	/getbyloginname(@v)?@v='<login name>'
パラメーター	型: String クエリ文字列で別名として渡された、取得するユーザーのログイン名。例: SharePoint Online または次のフォームを使用したオンプレミス: …/getbyloginname(@v)?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com' Windows クレームを使用したオンプレミス: …/getbyloginname(@v)?@v='i%3A0%23.w%7Cdomain\user' SAML クレームを使用したオンプレミス: …/getbyloginname(@v)?@v='i%3A05%3At%7Cadfs+with+roles%7Cuser%40domain.com'
HTTP method	GET
応答	型: SP.User 指定されたユーザー。

要求の例

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups(7)/users
    /getbyloginname(@v)?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'
    &@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

または単に、UserCollection リソースのログイン名を指定することもできます。例: …/_api/web/siteusers(@v)?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'

RemoveById メソッド

指定された ID を持つユーザーを削除します。

エンドポイント	/removebyid(<user id>)
パラメーター	型: Int32 削除するユーザーの ID
HTTP method	POST
応答	なし

要求の例

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups(7)/users
    /removebyid(24)
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

RemoveByLoginName メソッド

指定されたログイン名を持つユーザーを削除します。

エンドポイント	/removebyloginname(@v)?@v='<login name>')
パラメーター	型: String クエリ文字列で別名として渡された、削除するユーザーのログイン名。例: SharePoint Online または次のフォームを使用したオンプレミス: …/removebyloginname(@v)?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com' Windows クレームを使用したオンプレミス: …/removebyloginname(@v)?@v='i%3A0%23.w%7Cdomain\user' SAML クレームを使用したオンプレミス: …/removebyloginname(@v)?@v='i%3A05%3At%7Cadfs+with+roles%7Cuser%40domain.com'
HTTP method	POST
応答	なし

要求の例

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups(7)/users
    /removebyloginname(@v)?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'
    &@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

OData 表現

次の例は、JSON 形式による UserCollection リソースを表します。

    {"d":{
      "results":[{
        "__metadata":{
          "id":"http://<site url>/_api/Web/GetUserById(16)",
          "uri":"http://<site url>/_api/Web/GetUserById(16)",
          "type":"SP.User"
        },
        "Groups":{"__deferred":{"uri":"http://<site url>/_api/Web/GetUserById(16)/Groups"}},
        "Id":16,
        "IsHiddenInUI":false,
        "LoginName":"i:0#.w|domain\\user1",
        "Title":" User1 Display Name ",
        "PrincipalType":1,
        "Email":"user1@company.com",
        "IsSiteAdmin":false,{
        "__metadata":{
          "type":"SP.UserIdInfo"},
          "NameId":"s-0-0-00-000000-0000000000-0000000000-000000",
          "NameIdIssuer":"issuer id"
        }},{
        "__metadata":{
          "id":"http://<site url>/_api/Web/GetUserById(21)",
          "uri":"http://<site url>/_api/Web/GetUserById(21)",
          "type":"SP.User"},
        "Groups":{"__deferred":{"uri":"http://<site url>/_api/Web/GetUserById(21)/Groups"}},
        "Id":21,
        "IsHiddenInUI":false,
        "LoginName":"i:0#.w|domain\\user2",
        "Title":" User2 Display Name ",
        "PrincipalType":1,
        "Email":"user2@company.com",
        "IsSiteAdmin":false,{
        "__metadata":{
          "type":"SP.UserIdInfo"},
          "NameId":"s-0-0-00-000000-0000000000-0000000000-000001",
          "NameIdIssuer":"issuer id"
        }
      }]
    }}

UserCustomAction リソース

SharePoint リスト、Web サイト、またはサブサイトに関連付けられているカスタムアクションを表します。

エンドポイント URI | プロパティ | メソッド | OData 表現

エンドポイント URI

http://<site url>/_api/web/usercustomactions('<user custom action id>')

サポートされる HTTP メソッド

GET | POST | DELETE | MERGE | PUT

要求の例

GET 要求例: カスタムアクションの取得

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /usercustomactions('83393b01-0b73-4af5-9f0e-9ab0750a4ec4')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

MERGE 要求例: カスタムアクションの変更

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /usercustomactions('83393b01-0b73-4af5-9f0e-9ab0750a4ec4')
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata':{ 'type': 'SP.UserCustomAction' }, 'Title':'New title' }",
  headers: {
    "content-type": "application/json; odata=verbose",
    "X-HTTP-Method": "MERGE"
  },
  success: successHandler,
  error: errorHandler
});

DELETE 要求例: カスタムアクションの削除

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /usercustomactions('83393b01-0b73-4af5-9f0e-9ab0750a4ec4')
    ?@target='<host web url>'",
  method: "POST",
  headers: { "X-HTTP-Method": "DELETE" },
  success: successHandler,
  error: errorHandler
});

カスタムアクションを作成する方法の例については、「UserCustomActionCollection 要求例」をご覧ください。

UserCustomAction のプロパティ

プロパティを取得するには、次の例に示すように、GET 要求をプロパティエンドポイントに送ります。

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /usercustomactions('83393b01-0b73-4af5-9f0e-9ab0750a4ec4')/<property name>
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

プロパティ	型	R/W	リソースとともに返される	説明
CommandUIExtension	String	RW	はい	カスタムアクションのユーザーインターフェイスプロパティを決定する、実装に固有の XML フラグメントを指定する値を取得または設定します。
Description	String	RW	はい	カスタムアクションの説明を取得または設定します。
Group	String	RW	はい	ページ内のカスタムアクションの位置を決定する、実装に固有の値を指定する値を取得または設定します。
Id	GUID	R	はい	カスタムアクションの識別子を示す値を取得します。
ImageUrl	String	RW	はい	カスタムアクションと関連付けられているイメージの URL を取得または設定します。
Location	String	RW	はい	カスタムアクションの場所を取得または設定します。
Name	String	RW	はい	カスタムアクションの名前を取得または設定します。
RegistrationId	String	RW	はい	カスタムアクションが関連付けられているオブジェクトの識別子を指定する値を取得または設定します。
RegistrationType	Int32	RW	はい	カスタムアクションと関連付けられたオブジェクトの種類を指定する値を取得または設定します。SP.UserCustomActionRegistrationType 値を表します。None = 0、List = 1、ContentType = 2、ProgId = 3、FileType = 4。
Rights	SP.BasePermissions	RW	はい	カスタムアクションで必要とされるアクセス許可を指定する値を取得または設定します。
Scope	Boolean	R	はい	カスタムアクションのスコープを示す値を取得します。
ScriptBlock	String	RW	はい	カスタムアクションの実行時に実行される ECMAScript を指定する値を取得または設定します。
ScriptSrc	String	RW	はい	ページで実行する ECMAScript が含まれているファイルの URI を指定する値を取得または設定します。
Sequence	Int32	RW	はい	ページに表示されるカスタムアクションの順序を決定する、実装に固有の値を指定する値を取得または設定します。
Title	String	RW	はい	カスタムアクションの表示タイトルを取得または設定します。
Url	String	RW	はい	このアクションに関連付けられている URL、URI、または ECMAScript (JScript、JavaScript) 関数を取得または設定します。
VersionOfUserCustomAction	String	R	はい	実装に固有のバージョン識別子を示す値を取得します。

UserCustomAction メソッド

DeleteObject

DeleteObject メソッド

ファイルを削除するために推奨される方法は、「UserCustomAction 要求の例」に示すように、DELETE 要求を UserCustomAction リソースエンドポイントに送ることです。

OData 表現

次の例は、JSON 形式による UserCustomAction リソースを表します。

    {"d":{
      "__metadata":{,
        "id":"http://<site url>/_api/Web/UserCustomActions(guid'98bffbf9-c911-4c59-a807-cac99647f889')",
        "uri":"http://<site url>/_api/Web/UserCustomActions(guid'98bffbf9-c911-4c59-a807-cac99647f889')",
        "type":"SP.UserCustomAction"
      },
      "CommandUIExtension":null,
      "Description":"Opens the Shared Documents page",
      "Group":"SiteActions",
      "Id":"98bffbf9-c911-4c59-a807-cac99647f889",
      "ImageUrl":null,
      "Location":"Microsoft.SharePoint.StandardMenu",
      "Name":null,
      "RegistrationId":null,
      "RegistrationType":0,
      "Rights":{"__metadata":{"type":"SP.BasePermissions"}, "High":"0", "Low":"0"},
      "Scope":3,
      "ScriptBlock":null,
      "ScriptSrc":null,
      "Sequence":101,
      "Title":"Open Shared Docs",
      "Url":"http://<site url>/Shared%20Documents/Forms/AllItems.aspx",
      "VersionOfUserCustomAction":"15.0.1.0"
    }}

UserCustomActionCollection リソース

UserCustomAction リソースのコレクションを表します。

エンドポイント URI | メソッド | OData 表現

エンドポイント URI

http://<site url>/_api/web/usercustomactions

サポートされる HTTP メソッド

GET | POST

要求の例

GET 要求の例: サイトのカスタムアクションを取得します

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/usercustomactions
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GET 要求の例: カスタムアクションを取得します

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/usercustomactions('83393b01-0b73-4af5-9f0e-9ab0750a4ec4')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

POST 要求の例: カスタムアクションを作成します

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/usercustomactions
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata': { 'type': 'SP.UserCustomAction' }, 'Location':'Microsoft.SharePoint.StandardMenu',
    'Group':'SiteActions', 'Sequence':'101', 'Title':'Open Shared Docs',
    'Description':'Opens the Shared Documents page', 'Url':'~site/Shared%20Documents/Forms/AllItems.aspx' }",
  headers: {
    "accept": "application/json; odata=verbose",
    "content-type": "application/json; odata=verbose"
  },
  success: successHandler,
  error: errorHandler
});

カスタムアクションを変更、または削除する方法の例については、「UserCustomAction 要求例」をご覧ください。

UserCustomActionCollection メソッド

Clear
GetById

Clear メソッド

コレクション内のすべてのカスタムアクションを削除します。

エンドポイント	/clear
パラメーター	なし
HTTP method	POST
応答	なし

要求の例

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/usercustomactions
    /clear
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

GetById メソッド

指定された識別子を持つカスタムアクションを返します。

エンドポイント	/getbyid(<user custom action id>)
パラメーター	型: Guid 取得するユーザーカスタムアクションの ID
HTTP method	GET
応答	型: SP.UserCustomAction 指定されたユーザーカスタムアクション

要求の例

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/usercustomactions
    /getbyid('83393b01-0b73-4af5-9f0e-9ab0750a4ec4')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

または単に、UserCustomActionCollection リソースのアクション ID を指定することもできます。例: …/_api/web/usercustomactions('83393b01-0b73-4af5-9f0e-9ab0750a4ec4')

OData 表現

次の例は、JSON 形式による UserCustomActionCollection リソースを表します。

    {"d":{
      "results":[{
        "__metadata":{
          "id":"http://<site url>/_api/Web/UserCustomActions(guid'c38d9d91-c5e8-4fbd-9040-52b03024d2a3')",
          "uri":"http://<site url>/_api/Web/UserCustomActions(guid'c38d9d91-c5e8-4fbd-9040-52b03024d2a3')",
          "type":"SP.UserCustomAction"
        },
        "CommandUIExtension":null,
        "Description":"Opens the Site Contents page",
        "Group":"SiteActions",
        "Id":"c38d9d91-c5e8-4fbd-9040-52b03024d2a3",
        "ImageUrl":null,
        "Location":"Microsoft.SharePoint.StandardMenu",
        "Name":"{c38d9d91-c5e8-4fbd-9040-52b03024d2a3}",
        "RegistrationId":null,
        "RegistrationType":0,{
        "__metadata":{ "type":"SP.BasePermissions"}, "High":"0", "Low":"0" },
        "Scope":3,
        "ScriptBlock":null,
        "ScriptSrc":null,
        "Sequence":102,
        "Title":"Open Site Contents",
        "Url":"~site/_layouts/15/viewlsts.aspx",
        "VersionOfUserCustomAction":"15.0.1.0"},{
        "__metadata":{
          "id":"http://<site url>/_api/Web/UserCustomActions(guid'98bffbf9-c911-4c59-a807-cac99647f889')",
          "uri":"http://<site url>/_api/Web/UserCustomActions(guid'98bffbf9-c911-4c59-a807-cac99647f889')",
          "type":"SP.UserCustomAction"},
        "CommandUIExtension":null,
        "Description":"Opens the Shared Documents page",
        "Group":"SiteActions",
        "Id":"98bffbf9-c911-4c59-a807-cac99647f889",
        "ImageUrl":null,
        "Location":"Microsoft.SharePoint.StandardMenu",
        "Name":"{98bffbf9-c911-4c59-a807-cac99647f889}",
        "RegistrationId":null,
        "RegistrationType":0,{
        "__metadata":{ "type":"SP.BasePermissions"}, "High":"0", "Low":"0" },
        "Scope":3,
        "ScriptBlock":null,
        "ScriptSrc":null,
        "Sequence":101,
        "Title":"Open Shared Docs",
        "Url":"http://<site url>/Shared%20Documents/Forms/AllItems.aspx",
        "VersionOfUserCustomAction":"15.0.1.0"
      }]
    }}