Benutzer, Gruppen und Rollen - REST-API-Referenz

Erfahren Sie mehr über die REST-API für User, Group, RoleAssigment, RoleDefinition, UserCustomAction und dazugehörige Ressourcen.

Letzte Änderung: Donnerstag, 17. September 2015

Gilt für: apps for SharePoint | SharePoint Foundation 2013 | SharePoint Online | SharePoint Server 2013

Informationen über die Anforderungsbeispiele in diesem Artikel

Die Anforderungsbeispiele in diesem Artikel gehen davon aus, dass Sie zum Durchführen von domänenübergreifenden Anforderungen die domänenübergreifende Bibliothek (SP.RequestExecutor.js) verwenden, sie verwenden also SP.AppContextSite in der Endpunkt-URI. Weitere Informationen dazu finden Sie unter Zugreifen auf SharePoint 2013-Daten über Add-Ins mithilfe der domänenübergreifenden Bibliothek.

Führen Sie folgende Schritte durch, bevor Sie ein Anforderungsbeispiel verwenden:

• Ändern Sie die <App Web-URL>, <Hostweb-URL> und sonstige Platzhalterdaten wie die IDs, Namen oder Pfade der SharePoint-Entitäten.

• Wenn Sie keine domänenübergreifende Bibliothek verwenden, müssen Sie eine X-RequestDigest-Kopfzeile miteinbeziehen, um den Formulardigestwert in allen POST-Anforderungen zu senden und eine content-length-Kopfzeile für POST-Anforderungen, die Daten im Anforderungstext senden.

• Wenn Sie keine domänenübergreifenden Anforderungen durchführen, müssen Sie SP.AppContextSite(@target) und ?@target='<host web url>' aus der Endpunkt-URI entfernen.

• Wenn Sie OAuth verwenden, müssen Sie eine Authorization-Kopfzeile miteinbeziehen ("Authorization": "Bearer " + <access token>), um den OAuth-Zugriffstoken zu senden.

• Entfernen Sie die Zeilenumbrüche aus den url- und body-Eigenschaftswerten in den Anforderungsbeispielen. Zeilenumbrüchen wurden in den Beispielen hinzugefügt, damit man sie leichter lesen kann.

• Wenn der Server Antworten im Atomformat zurückgeben soll, müssen Sie die "accept": "application/json; odata=verbose"-Kopfzeile entfernen.

Links zu weiteren Informationen zum Verwenden der domänenübergreifenden Bibliothek, OAuth und des SharePoint REST-Diensts finden Sie unter Zusätzliche Ressourcen. Informationen zu Anforderungsformaten finden Sie unter So unterscheiden sich REST-Anforderungen je nach Umgebung und In REST-Anforderungen verwendete Eigenschaften.

Tipp

Der SharePoint Online-REST-Dienst unterstützt die Kombination mehrerer Anforderungen in einem einzelnen Dienstaufruf mithilfe der OData-Abfrageoption $batch. Einzelheiten und Links zu Codebeispielen finden Sie unter Erstellen von Batchanforderungen mit den REST-APIs. Diese Option wird für lokales SharePoint noch nicht unterstützt.

Informationen zu SharePoint 2013-Benutzern und Gruppen in der REST-Syntax

Erfahren Sie mehr über die SharePoint 2013-Benutzer und Gruppen in der REST-Syntax. Weitere SharePoint REST-Syntaxdiagramme: Dateien und Ordner | Listen und Listenelemente Laden Sie das PDF-Dokument aller SharePoint-REST-Syntaxdiagramme herunter.

Gruppenressource

Stellt eine Sammlung der Benutzer in einer SharePoint-Website dar. Eine Gruppe ist ein SP.Principal-Typ.

Endpunkt-URI  |  Eigenschaften  |  OData-Darstellung

Endpunkt-URI

http://<Website-URL>/_api/web/sitegroups(<Gruppen-ID>)

Unterstützte HTTP-Methoden

GET  |  POST  |  MERGE  |  PUT

Anforderungsbeispiele

GET-Anforderungsbeispiel: Abrufen einer Gruppe

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

Sie können eine Gruppe auch mit dem LoginName abrufen. Weitere Informationen dazu finden Sie unter GetByName-Methode.

MERGE-Anforderungsbeispiel: Ändern einer Gruppe

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

Wenn Sie einen Benutzer zu einer Gruppe hinzufügen, müssen Sie den Benutzer zur Benutzersammlung der Gruppe hinzufügen, wie in den UserCollection-Anforderungsbeispielen gezeigt. Um einen Benutzer aus einer Gruppe zu entfernen, verwenden Sie die RemoveById-Methode oder RemoveByLoginName-Methode aus der UserCollection-Ressource.

PUT-Anforderungsbeispiel: Ersetzen von Gruppen

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

Verwenden Sie die RemoveById-Methode oder die RemoveByLoginName-Methode, um eine Gruppe zu löschen. Senden Sie zum Erstellen einer Gruppe eine POST-Anforderung an die GroupCollection-Ressource. Ein Beispiel dazu finden Sie unter GroupCollection-Anforderungsbeispiele.

Gruppeneigenschaften

Senden Sie zum Abrufen einer Eigenschaft eine GET-Anforderung an den Eigenschaftsendpunkt wie im folgenden Beispiel.

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

Eigenschaft	Typ	R/W	Mit Ressource zurückgegeben	Beschreibung
AllowMembersEditMembership	Boolean	RW	Ja	Dient zum Abrufen oder Festlegen eines Werts, der angibt, ob die Gruppenmitglieder die Mitgliedschaft in der Gruppe bearbeiten können.
AllowRequestToJoinLeave	Boolean	RW	Ja	Dient zum Abrufen oder Festlegen eines Werts, der angibt, ob es Benutzern möglich sein soll, eine Mitgliedschaft in der Gruppe sowie das Verlassen der Gruppe anzufordern.
AutoAcceptRequestToJoinLeave	Boolean	RW	Nein	Dient zum Abrufen oder Festlegen eines Werts, der angibt, ob die Anforderung zum Beitreten zur Gruppe oder zum Verlassen der Gruppe automatisch akzeptiert werden kann.
CanCurrentUserEditMembership	Boolean	R	Nein	Ruft einen Wert ab, der angibt, ob der aktuelle Benutzer die Mitgliedschaft der Gruppe bearbeiten kann.
CanCurrentUserManageGroup	Boolean	R	Nein	Ruft einen Wert ab, der angibt, ob der aktuelle Benutzer die Gruppe verwalten kann.
CanCurrentUserViewMembership	Boolean	R	Nein	Ruft einen Wert ab, der angibt, ob der aktuelle Benutzer die Mitgliedschaft der Gruppe anzeigen kann.
Description	String	RW	Ja	Dient zum Abrufen oder Festlegen der Beschreibung der Gruppe.
ID	Int32	R	Ja	Ruft einen Wert ab, der den Mitgliedsbezeichner für den Benutzer oder die Gruppe angibt.
IsHiddenInUI	Boolean	R	Ja	Ruft einen Wert ab, der angibt, ob dieses Element auf der Benutzeroberfläche ausgeblendet werden soll.
LoginName	String	R	Ja	Ruft den Namen der Gruppe ab.
OnlyAllowMembersViewMembership	Boolean	RW	Ja	Dient zum Abrufen oder Festlegen eines Werts, der angibt, ob nur Gruppenmitglieder zum Anzeigen der Mitgliedschaft der Gruppe berechtigt sind.
Owner	SP.Principal	RW	Nein	Dient zum Abrufen oder Festlegen des Besitzers der Gruppe. Hierbei kann es sich um einen Benutzer oder um eine andere Gruppe mit zugewiesenen Berechtigungen zum Steuern der Sicherheit handeln.
OwnerTitle	String	R	Ja	Ruft den Namen für den Besitzer der Gruppe ab.
RequestToJoinLeaveEmailSetting	String	RW	Ja	Dient zum Abrufen oder Festlegen der E-Mail-Adresse, an die Mitgliedschaftsanforderungen gesendet werden.
PrincipalType	Int32	R	Ja	Ruft einen Wert ab, der die Art des Prinzipals enthält. Stellt einen bitweisen SP.PrincipalType-Wert dar: None = 0; User = 1; DistributionList = 2; SecurityGroup = 4; SharePointGroup = 8; All = 15.
Title	String	RW	Ja	Dient zum Abrufen oder Festlegen eines Werts, der den Namen des Prinzipals angibt.
Users	SP.UserCollection	R	Nein	Ruft eine Auflistung von Benutzerobjekten ab, die für alle Benutzer in der Gruppe steht.

OData-Darstellung

Das folgende Beispiel stellt eine Group-Ressource im JSON-Format dar.

    {"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-Ressource

Stellt eine Sammlung von Group-Ressourcen dar.

Endpunkt-URI  |  Methoden  |  OData-Darstellung

Endpunkt-URI

http://<Website-URL>/_api/web/sitegroups

Unterstützte HTTP-Methoden

GET  |  POST

Anforderungsbeispiele

GET-Anforderungsbeispiel: Abrufen von Gruppen aus der Stammwebsite

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-Anforderungsbeispiel: Abrufen einer Gruppe

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

Sie können eine Gruppe auch mit dem LoginName abrufen. Weitere Informationen dazu finden Sie unter GetByName-Methode.

POST-Anforderungsbeispiel: Erstellen einer Gruppe

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

Beispiele zum Ändern einer Gruppe finden Sie unter Gruppenanforderungsbeispiele.

GroupCollection-Methoden

GetById
GetByName
RemoveById
RemoveByLoginName

GetById-Methode

Gibt eine Gruppe aus der Auflistung auf der Grundlage der Mitglieds-ID der Gruppe zurück.

Endpunkt	/getbyid(<Gruppen-ID>)
HTTP-Methode	GET
Parameter	Typ: Int32 Die ID der abzurufenden Gruppe.
Antwort	Typ: SP.Group Die angegebene Gruppe.

  Anforderungsbeispiel

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

Sie können auch nur die Gruppen-ID der GroupCollection-Ressource angeben. Beispiel: …/_api/web/sitegroups(5)

GetByName-Methode

Gibt eine websiteübergreifende Gruppe auf Grundlage des Namens der Gruppe aus der Auflistung zurück.

Endpunkt	/getbyname('<Gruppenname>')
HTTP-Methode	GET
Parameter	Typ: String Der Name der Gruppe. Der Gruppenname ist in der LoginName-Eigenschaft angegeben.
Antwort	Typ: SP.Group Die angegebene Gruppe.

  Anforderungsbeispiel

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-Methode

Entfernt die Gruppe mit der angegebenen Element-ID aus der Auflistung.

Endpunkt	/removebyid(<Gruppen-ID>)
HTTP method	POST
Parameter	Typ: Int32 Die ID der zu entfernenden Gruppe.
Antwort	Keine

  Anforderungsbeispiel

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-Methode

Entfernt die websiteübergreifende Gruppe mit dem angegebenen Namen aus der Auflistung.

Endpunkt	/removebyloginname('<Gruppenname>')
HTTP method	POST
Parameter	Typ: String Der Name der zu entfernenden Gruppe. Der Gruppenname ist in der LoginName-Eigenschaft angegeben.
Antwort	Keine

  Anforderungsbeispiel

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-Darstellung

Das folgende Beispiel stellt eine GroupCollection-Ressource im JSON-Format dar.

    {"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-Ressource

Definiert die Rollenzuweisungen für das sicherungsfähige Objekt für einen Benutzer oder eine Gruppe auf der Website, in der Liste oder im Listenelement.

Endpunkt-URI  |  Eigenschaften  |  Methoden  |  OData-Darstellung

Endpunkt-URI

http://<Website-URL>/_api/web/roleassignments(<Prinzipal-ID>)

Unterstützte HTTP-Methoden

GET  |  POST  |  DELETE

Anforderungsbeispiele

GET-Anforderungsbeispiel: Abrufen einer Rollenzuweisung

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-Anforderungsbeispiel: Löschen einer Rollenzuweisung

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

Sie können auch die RemoveRoleAssignment-Methode verwenden, um eine Rollenzuweisung zu entfernen. Verwenden Sie zum Erstellen einer Rollenzuweisung die AddRoleAssignment-Methode.

RoleAssignment-Eigenschaften

Senden Sie zum Abrufen einer Eigenschaft eine GET-Anforderung an den Eigenschaftsendpunkt wie im folgenden Beispiel.

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

Eigenschaft	Typ	R/W	Mit Ressource zurückgegeben	Beschreibung
Element	SP.Principal	R	Nein	Ruft den entsprechenden Benutzer oder die entsprechende Gruppe für die Rollenzuweisung ab.
PrincipalId	Int32	R	Ja	Der eindeutige Bezeichner der Rollenzuweisung.
RoleDefinitionBindings	SP.RoleDefinitionCollection	R	Nein	Ruft die Auflistung von Rollendefinitionsbindungen für die Rollenzuweisung ab.

RoleAssignment-Methoden

DeleteObject

DeleteObject-Methode

Die empfohlene Option zum Löschen einer Rollenzuweisung ist das Verwenden der RemoveRoleAssignment-Methode oder das Senden einer DELETE-Anforderung an den RoleAssignment-Ressourcenendpunkt, wie in den RoleAssignment-Anforderungsbeispielen gezeigt.

OData-Darstellung

Das folgende Beispiel stellt eine RoleAssignment-Ressource im JSON-Format dar.

    {"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-Ressource

Stellt eine Sammlung von RoleAssignment-Ressourcen dar.

Endpunkt-URI  |  Eigenschaften  |  Methoden  |  OData-Darstellung

Endpunkt-URI

http://<Website-URL>/_api/web/roleassignments

Unterstützte HTTP-Methoden

GET  |  POST

Anforderungsbeispiele

GET-Anforderungsbeispiel: Abrufen einer Rollenzuweisung

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

Verwenden Sie die AddRoleAssignment-Methode zum Erstellen einer Rollenzuweisung. Verwenden Sie zum Löschen einer Rollenzuweisung die RemoveRoleAssignment-Methode oder senden Sie eine DELETE-Anforderung an den RoleAssignment-Ressourcenendpunkt, wie in den RoleAssignment-Anforderungsbeispielen gezeigt.

RoleAssignmentCollection-Eigenschaften

Senden Sie zum Abrufen einer Eigenschaft eine GET-Anforderung an den Eigenschaftsendpunkt wie im folgenden Beispiel.

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

Eigenschaft	Typ	R/W	Mit Ressource zurückgegeben	Beschreibung
Groups	SP.GroupCollection	R	Nein	Ruft die Gruppen ab, die direkt zur Zugriffssteuerungsliste (ACL) dieses sicherungsfähigen Objekts gehören.

RoleAssignmentCollection-Methoden

AddRoleAssignment
GetByPrincipalId
RemoveRoleAssignment

AddRoleAssignment-Methode

Fügt der Auflistung eine neue Rollenzuweisung mit dem angegebenen Prinzipal und den angegebenen Rollendefinitionen hinzu.

Endpunkt	/addroleassignment(principalid, roledefid)
Parameter	principalid Typ: Int32 Die ID des Benutzers oder der Gruppe zum Zuweisen von Berechtigungen. roledefid Typ: Int32 Die ID der Rollendefinition, die die zuzuweisenden Berechtigungen definiert. Ein Beispiel zum Erstellen einer Rollendefinition finden Sie unter RoleDefinitionCollection-Anforderungsbeispiele.
HTTP method	POST
Antwort	Keine

  Anforderungsbeispiel

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

Um diese Methode für ein Objekt zu verwenden, das Berechtigungen erbt, müssen Sie zunächst die BreakRoleInheritance-Methode für das Objekt abrufen. Weitere Informationen dazu finden Sie unter Festlegen von benutzerdefinierten Berechtigungen in einer Liste mit der REST-Schnittstelle.

GetByPrincipalId-Methode

Ruft die der angegebenen Prinzipal-ID zugeordnete Rollenzuweisung aus der Auflistung ab.

Endpunkt	/getbyprincipalid(<Prinizipal-ID>)
Parameter	Typ: Int32 Die PrincipalId der abzurufenden Rollenzuweisung.
HTTP method	GET
Antwort	Typ: SP.RoleAssignment Die angegebene Rollenzuweisung.

  Anforderungsbeispiel

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

Sie können die Prinzipal-ID der Rollenzuweisung auch einfach in der RoleAssignmentCollection-Ressource angeben. Beispiel: …/_api/web/roleassignments(3)

RemoveRoleAssignment-Methode

Entfernt die Rollenzuweisung mit der angegebenen Prinzipal- und Rollendefinition aus der Sammlung.

Endpunkt	/removeroleassignment(principalid, roledefid)
Parameter	principalid Typ: Int32 Die ID des Benutzers oder der Gruppe in der Rollenzuweisung. roledefid Typ: Int32 Die ID der Rollendefinition in der Rollenzuweisung.
HTTP method	POST
Antwort	Keine

  Anforderungsbeispiel

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-Darstellung

Das folgende Beispiel stellt eine RoleAssignmentCollection-Ressource im JSON-Format dar.

    {"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-Ressource

Definiert eine einzelne Rollendefinition einschließlich Name, Beschreibung und Rechtesatz.

Endpunkt-URI  |  Eigenschaften  |  Methoden  |  OData-Darstellung

Endpunkt-URI

http://<Website-URL>/_api/web/roledefinitions(<Rollendefinitions-ID>)

Unterstützte HTTP-Methoden

GET  |  POST  |  DELETE  |  MERGE  |  PUT

Anforderungsbeispiele

GET-Anforderungsbeispiel: Abrufen einer Rollendefinition

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-Anforderungsbeispiel: Ändern einer Rollendefinition

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-Anforderungsbeispiel: Ersetzen einer Rollendefinition

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-Anforderungsbeispiel: Löschen einer Rollendefinition

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

Ein Beispiel zum Erstellen einer Rollendefinition finden Sie unter RoleDefinitionCollection-Anforderungsbeispiele.

RoleDefinition-Eigenschaften

Senden Sie zum Abrufen einer Eigenschaft eine GET-Anforderung an den Eigenschaftsendpunkt wie im folgenden Beispiel.

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

Eigenschaft	Typ	R/W	Mit Ressource zurückgegeben	Beschreibung
BasePermissions	SP.BasePermissions	RW	Ja	Dient zum Abrufen oder Festlegen eines Werts, der die Basisberechtigungen für die Rollendefinition angibt.
Description	String	RW	Ja	Dient zum Abrufen oder Festlegen eines Werts, der eine Beschreibung der Rollendefinition angibt.
Hidden	Boolean	R	Ja	Ruft einen Wert ab, der angibt, ob die Rollendefinition angezeigt wird.
ID	Int32	R	Ja	Ruft einen Wert ab, der die ID der Rollendefinition angibt.
Name	String	RW	Ja	Dient zum Abrufen oder Festlegen eines Werts, der den Rollendefinitionsnamen angibt.
Order	Int32	RW	Ja	Dient zum Abrufen oder Festlegen eines Werts, der die Reihenfolgenposition des Objekts auf der Berechtigungsstufenseite der Websitesammlung angibt.
RoleTypeKind	Int32	R	Ja	Ruft einen Wert ab, der die Art der Rollendefinition angibt. Stellt einen SP.RoleType-Wert dar. Unter RoleType in der .NET-Clientobjekt-Modellreferenz finden Sie eine Liste der Rollentypwerte.

RoleDefinition-Methoden

DeleteObject

DeleteObject-Methode

Die empfohlene Option zum Löschen einer Rollendefinition ist das Senden einer DELETE-Anforderung an den RoleDefinition-Ressourcenendpunkt, wie in den RoleDefinition-Anforderungsbeispielen gezeigt.

OData-Darstellung

Das folgende Beispiel stellt eine RoleDefinition-Ressource im JSON-Format dar.

    {"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-Ressource

Stellt eine Sammlung von RoleDefinition-Ressourcen dar.

Endpunkt-URI  |  Methoden  |  OData-Darstellung

Endpunkt-URI

http://<Website-URL>/_api/web/roledefinitions

Unterstützte HTTP-Methoden

GET  |  POST

Anforderungsbeispiele

GET-Anforderungsbeispiel: Abrufen einer Rollendefinition

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-Anforderungsbeispiel: Erstellen einer Rollendefinition

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

Beispiele zum Ändern oder Löschen einer Rollendefinition finden Sie unter RoleDefinition-Anforderungsbeispiele.

RoleDefinitionCollection-Methoden

GetById
GetByName
GetByType

GetById-Methode

Ruft die Rollendefinition mit der angegebenen ID aus der Auflistung ab.

Endpunkt	/getbyid(<Rollendefinitions-ID>)
Parameter	Typ: Int32 Die ID der Rollendefinition.
HTTP method	GET
Antwort	Typ: SP.RoleDefinition Die angegebene Rollendefinition.

  Anforderungsbeispiel

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

Sie können die Rollendefinitions-ID auch einfach in der RoleDefinitionCollection-Ressource angeben. Beispiel: …/_api/web/roledefinitions(1073741829)

GetByName-Methode

Ruft die Rollendefinition mit dem angegebenen Namen ab.

Endpunkt	/getbyname('<Rollendefinitionsname>')
Parameter	Typ: String Der Name der Rollendefinition.
HTTP method	GET
Antwort	Typ: SP.RoleDefinition Die angegebene Rollendefinition.

  Anforderungsbeispiel

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-Methode

Ruft die Rollendefinition mit dem angegebenen Rollentyp ab.

Endpunkt	/getbytype(<Rollendefinitionstyp>)
Parameter	Typ: Int32 Der RoleTypeKind der Rollendefinition. Unter RoleType in der .NET-Clientobjekt-Modellreferenz finden Sie eine Liste der Rollentypwerte.
HTTP method	GET
Antwort	Typ: SP.RoleDefinition Die angegebene Rollendefinition.

  Anforderungsbeispiel

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-Darstellung

Das folgende Beispiel stellt eine RoleDefinitionCollection-Ressource im JSON-Format dar.

    {"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-Ressource

Definiert die an ein Rollenzuweisungsobjekt gebundenen Rollendefinitionen.

Endpunkt-URI  |  OData-Darstellung

Endpunkt-URI

http://<Website-URL>/_api/web/roleassignments(<Rollenzuweisungs-ID>)/roledefinitionbindings

Unterstützte HTTP-Methoden

GET

Anforderungsbeispiele

GET-Anforderungsbeispiel: Abrufen der Rollendefinitionsbindungen einer Rollenzuweisung

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

Verwenden Sie zum Erstellen einer Rollenzuweisung, die einen Prinzipal (Benutzer oder Gruppe) an eine Rollendefinition bindet, die AddRoleAssignment-Methode. Verwenden Sie zum Löschen einer Rollenzuweisung die RemoveRoleAssignment-Methode oder senden Sie eine DELETE-Anforderung an den RoleAssignment-Ressourcenendpunkt, wie in den RoleAssignment-Anforderungsbeispielen gezeigt.

OData-Darstellung

Das folgende Beispiel stellt eine RoleDefinitionBindingCollection-Ressource im JSON-Format dar.

    {"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-Ressource

Stellt einen Benutzer in Microsoft SharePoint Foundation dar. Ein Benutzer ist ein SP.Principal-Typ.

Endpunkt-URI  |  Eigenschaften  |  OData-Darstellung

Endpunkt-URI

http://<Website-URL>/_api/web/sitegroups(<Gruppen-ID>)/users(@v)?@v='<Anmeldename>'
http://<Website-URL>/_api/web/siteusers(@v)?@v='<Anmeldename>'

Das Format des Anmeldenamens für Benutzer hängt von Ihrer SharePoint-Umgebung ab, wie in Tabelle 1 beschrieben:

Tabelle 1. Anmeldenamenformate

SharePoint -Umgebung	Beispiel: Anmeldenamensformat	Übergeben des Anmeldenamens unter Verwendung eines Alias in der Abfragezeichenfolge
SharePoint Online oder lokales SharePoint 2013 unter Verwendung von Formularen	i:0#.f|membership|user@domain.com	…/users(@v)?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'
Lokales SharePoint 2013 unter Verwendung von Windows-Forderungen	i:0#.w|domain\user	…/users(@v)?@v='i%3A0%23.w%7Cdomain\user'
Lokales SharePoint 2013 unter Verwendung von SAML-Forderungen	i:05:t|adfs with roles|user@domain.com	…/users(@v)?@v='i%3A05%3At%7Cadfs+with+roles%7Cuser%40domain.com'

Hinweis

Das Format des Anmeldenamens im SAML-basierten (Security Assertion Markup Language) Forderungsauthentifizierungsbeispiel setzt voraus, dass die Identitätsforderung für eine E-Mail-Adress- oder des Benutzerprinzipalnamensverwendung konfiguriert ist. Die SAML-Forderungsauthentifizierung kann bei Apps, die von SharePoint gehostet sind, nicht eingesetzt werden.

Unterstützte HTTP-Methoden

GET  |  POST  |  DELETE  |  MERGE  |  PUT

Anforderungsbeispiele

GET-Anforderungsbeispiel: Abrufen eines Benutzers von einer Website mit dem Anmeldenamen

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-Anforderungsbeispiel: Abrufen eines Benutzers von einer Website mit der 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-Anforderungsbeispiel: Abrufen eines Benutzers aus einer Gruppe mit dem Anmeldenamen

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

Sie können einen Benutzer auch aus einer Gruppe nach E-Mail-Adresse oder ID abrufen. Weitere Informationen dazu finden Sie unter GetByEmail-Methode und der GetById-Methode.

MERGE-Anforderungsbeispiel: Ändern eines Benutzers

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-Anforderungsbeispiel: Ersetzen eines Benutzers

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

Unter UserCollection-Anforderungsbeispiele finden Sie ein Beispiel dazu, wie Sie einen Benutzer zu einer Gruppe hinzufügen können.

DELETE-Anforderungsbeispiel: Entfernen eines Benutzers aus einer Gruppe

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

Zum Entfernen eines Benutzers mit der DELETE-Methode in der User-Ressource müssen Sie den Benutzer aus der Benutzersammlung abrufen, indem Sie die GetById-Methode- oder GetByEmail-Methode verwenden. Sie können auch einfach die RemoveById-Methode oder RemoveByLoginName-Methode aus der UserCollection-Ressource.

Benutzereigenschaften

Senden Sie zum Abrufen einer Eigenschaft eine GET-Anforderung an den Eigenschaftsendpunkt wie im folgenden Beispiel.

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

Eigenschaft	Typ	R/W	Mit Ressource zurückgegeben	Beschreibung
Email	String	RW	Ja	Diese Eigenschaft ist in SharePoint Online nicht verfügbar. Dient zum Abrufen oder Festlegen der E-Mail-Adresse des Benutzers.
Groups	SP.GroupCollection	R	Nein	Ruft die Auflistung von Gruppen ab, deren Mitglied der Benutzer ist.
ID	Int32	R	Ja	Ruft einen Wert ab, der den Mitgliedsbezeichner für den Benutzer oder die Gruppe angibt.
IsHiddenInUI	Boolean	R	Ja	Ruft einen Wert ab, der angibt, ob dieses Element auf der Benutzeroberfläche ausgeblendet werden soll.
IsSiteAdmin	Boolean	RW	Ja	Dient zum Abrufen oder Festlegen eines booleschen Werts, der angibt, ob der Benutzer ein Websitesammlungsadministrator ist.
LoginName	String	R	Ja	Ruft den Anmeldenamen des Benutzers ab.
PrincipalType	Int32	R	Ja	Ruft einen Wert ab, der die Art des Prinzipals enthält. Stellt einen bitweisen SP.PrincipalType-Wert dar: None = 0; User = 1; DistributionList = 2; SecurityGroup = 4; SharePointGroup = 8; All = 15.
Title	String	RW	Ja	Dient zum Abrufen oder Festlegen eines Werts, der den Namen des Prinzipals angibt.
UserId	SP.UserIdInfo	R	Ja	Ruft die Informationen des Benutzers ab, der den Namensbezeichner des Benutzers und den Aussteller des Namensbezeichners des Benutzers enthält.

OData-Darstellung

Das folgende Beispiel stellt eine User-Ressource im JSON-Format dar.

    {"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-Ressource

Stellt eine Sammlung von User-Ressourcen dar.

Endpunkt-URI  |  Methoden  |  OData-Darstellung

Endpunkt-URI

http://<Website-URL>/_api/web/siteusers
http://<Website-URL>/_api/web/sitegroups(<Gruppen-ID>)/users

Unterstützte HTTP-Methoden

GET  |  POST

Anforderungsbeispiele

GET-Anforderungsbeispiel: Abrufen eines Benutzers nach Anmeldename

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-Anforderungsbeispiel: Abrufen der Benutzer in einer Gruppe

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-Anforderungsbeispiel: Hinzufügen eines Benutzers zu einer Gruppe

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-Methoden

GetByEmail
GetById
GetByLoginName
RemoveById
RemoveByLoginName

GetByEmail-Methoden

Ruft den Benutzer mit der angegebenen E-Mail-Adresse ab.

Endpunkt	/getbyemail('<E-Mail-Adresse>')
Parameter	Typ: String Die E-Mail des abzurufenden Benutzers.
HTTP method	GET
Antwort	Typ: SP.User Der angegebene Benutzer.

  Anforderungsbeispiel

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-Methode

Ruft den Benutzer mit dem angegebenen Mitgliedsbezeichner (ID) ab.

Endpunkt	/getbyid(<Benutzer-ID>)
Parameter	Typ: Int32 Die ID des abzurufenden Benutzers.
HTTP method	GET
Antwort	Typ: SP.User Der angegebene Benutzer.

  Anforderungsbeispiel

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-Methode

Ruft den Benutzer mit dem angegebenen Anmeldenamen ab.

Endpunkt	/getbyloginname(@v)?@v='<Anmeldename>'
Parameter	Typ: String Der Anmeldename des abzurufenden Benutzers, der als Alias in der Abfragezeichenfolge weitergegeben wird. Beispiel:   SharePoint Online oder dem lokalen Verwenden von Formularen: …/getbyloginname(@v)?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'   lokales Verwenden von Windows-Forderungen: …/getbyloginname(@v)?@v='i%3A0%23.w%7Cdomain\user'   lokales Verwenden von SAML-Forderungen: …/getbyloginname(@v)?@v='i%3A05%3At%7Cadfs+with+roles%7Cuser%40domain.com'
HTTP method	GET
Antwort	Typ: SP.User Der angegebene Benutzer.

  Anforderungsbeispiel

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

Sie können auch einfach den Anmeldenamen in der UserCollection-Ressource angeben. Beispiel: …/_api/web/siteusers(@v)?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'

RemoveById-Methode

Entfernt den Benutzer mit der angebenen ID.

Endpunkt	/removebyid(<Benutzer-ID>)
Parameter	Typ: Int32 Die ID des zu entfernenden Benutzers.
HTTP method	POST
Antwort	Keine

  Anforderungsbeispiel

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-Methode

Entfernt den Benutzer mit dem angegebenen Anmeldenamen.

Endpunkt	/removebyloginname(@v)?@v='<Anmeldename>'
Parameter	Typ: String Der Anmeldename des zu entfernenden Benutzers, der als Alias in der Abfragezeichenfolge weitergeben wird. Beispiel:   SharePoint Online oder lokales Verwenden von Formularen: …/removebyloginname(@v)?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'   lokales Verwenden von Windows-Forderungen: …/removebyloginname(@v)?@v='i%3A0%23.w%7Cdomain\user'   lokales Verwenden von SAML-Forderungen: …/removebyloginname(@v)?@v='i%3A05%3At%7Cadfs+with+roles%7Cuser%40domain.com'
HTTP method	POST
Antwort	Keine

  Anforderungsbeispiel

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-Darstellung

Das folgende Beispiel stellt eine UserCollection-Ressource im JSON-Format dar.

    {"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-Ressource

Steht für eine benutzerdefinierte Aktion in Verbindung mit einer SharePoint-Liste, -Website oder -Unterwebsite.

Endpunkt-URI  |  Eigenschaften  |  Methoden  |  OData-Darstellung

Endpunkt-URI

http://<Website-URL>/_api/web/usercustomactions('<benutzerdefinierte Aktions-ID des Benutzers>')

Unterstützte HTTP-Methoden

GET  |  POST  |  DELETE  |  MERGE  |  PUT

Anforderungsbeispiele

GET-Abforderungsbeispiel: Abrufen einer benutzerdefinierten Aktion

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-Anforderungsbeispiel: Ändern einer benutzerdefinierten Aktion

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-Anforderungsbeispiel: Löschen einer benutzerdefinierten Aktion

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

Ein Beispiel zum Erstellen einer benutzerdefinierten Aktion finden Sie unter UserCustomActionCollection-Anforderungsbeispiele.

UserCustomAction-Eigenschaften

Senden Sie zum Abrufen einer Eigenschaft eine GET-Anforderung an den Eigenschaftsendpunkt wie im folgenden Beispiel.

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

Eigenschaft	Typ	R/W	Mit Ressource zurückgegeben	Beschreibung
CommandUIExtension	String	RW	Ja	Dient zum Abrufen oder Festlegen eines Werts, der ein implementierungsspezifisches XML-Fragment angibt, das die Benutzeroberflächeneigenschaften der benutzerdefinierten Aktion bestimmt.
Description	String	RW	Ja	Dient zum Abrufen oder Festlegen der Beschreibung der benutzerdefinierten Aktion.
Groups	String	RW	Ja	Dient zum Abrufen oder Festlegen eines Werts, der einen implementierungsspezifischen Wert angibt, der die Position der benutzerdefinierten Aktion auf der Seite bestimmt.
ID	GUID	R	Ja	Ruft einen Wert ab, der den Bezeichner der benutzerdefinierten Aktion angibt.
ImageUrl	String	RW	Ja	Dient zum Abrufen oder Festlegen der URL des Bilds, das der benutzerdefinierten Aktion zugeordnet ist.
Location	String	RW	Ja	Dient zum Abrufen oder Festlegen des Speicherorts der benutzerdefinierten Aktion.
Name	String	RW	Ja	Dient zum Abrufen oder Festlegen des Namens der benutzerdefinierten Aktion.
RegistrationId	String	RW	Ja	Dient zum Abrufen oder Festlegen des Werts, die den Bezeichner des mit der benutzerdefinierten Aktion verknüpften Objekts angibt.
RegistrationType	Int32	RW	Ja	Dient zum Abrufen oder Festlegen des Werts, die die Art des mit der benutzerdefinierten Aktion verknüpften Objekts angibt. Stellt einen SP.UserCustomActionRegistrationType-Wert dar: None = 0; List = 1; ContentType = 2; ProgId = 3; FileType = 4.
Rights	SP.BasePermissions	RW	Ja	Dient zum Abrufen oder Festlegen des Werts, der die erforderlichen Berechtigungen für die benutzerdefinierte Aktion angibt.
Scope	Boolean	R	Ja	Ruft einen Wert ab, der den Bereich der benutzerdefinierten Aktion angibt.
ScriptBlock	String	RW	Ja	Dient zum Abrufen oder Festlegen des Werts, der das ECMAScript-Element angibt, das bei Ausführung der benutzerdefinierten Aktion ausgeführt werden soll.
ScriptSrc	String	RW	Ja	Dient zum Abrufen oder Festlegen eines Werts, der die URI einer Datei mit dem ECMA-Skript angibt, das auf der Seite ausgeführt werden soll.
Sequence	Int32	RW	Ja	Dient zum Abrufen oder Festlegen des Werts, der einen implementierungsspezifischen Wert angibt, der die Reihenfolge der auf der Seite erscheinenden benutzerdefinierten Aktion bestimmt.
Title	String	RW	Ja	Dient zum Abrufen oder Festlegen des Anzeigetitels der benutzerdefinierten Aktion.
Url	String	RW	Ja	Dient zum Abrufen oder Festlegen der URL-, URI- oder ECMAScript-Funktion (JScript, JavaScript), die der Aktion zugeordnet ist.
VersionOfUserCustomAction	String	R	Ja	Ruft einen Wert ab, der einen implementierungsspezifischen Versionsbezeichner angibt.

UserCustomAction-Methoden

DeleteObject

DeleteObject-Methode

Die empfohlene Option zum Löschen einer Datei ist das Senden einer DELETE-Anforderung an die UserCustomAction-Ressourcenendpunkt, wie unter UserCustomAction-Anforderungsbeispiele gezeigt.

OData-Darstellung

Das folgende Beispiel stellt eine UserCustomAction-Ressource im JSON-Format dar.

    {"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-Ressource

Stellt eine Sammlung von UserCustomAction-Ressourcen dar.

Endpunkt-URI  |  Methoden  |  OData-Darstellung

Endpunkt-URI

http://<Website-URL>/_api/web/usercustomactions

Unterstützte HTTP-Methoden

GET  |  POST

Anforderungsbeispiele

GET-Anforderungsbeispiel: Abrufen aller benutzerdefinierten Aktionen auf einer Website

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-Anforderungsbeispiel: Abrufen einer benutzerdefinierten Aktion

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-Anforderungsbeispiel: Erstellen einer benutzerdefinierten Aktion

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

Beispiele zum Ändern oder Löschen einer benutzerdefinierten Aktion finden Sie unter UserCustomAction-Anforderungsbeispiele.

UserCustomActionCollection-Methoden

Clear
GetById

Clear-Methode

Löscht alle benutzerdefinierten Aktionen in der Auflistung.

Endpunkt	/clear
Parameter	Keine
HTTP method	POST
Antwort	Keine

  Anforderungsbeispiel

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

GetById-Methode

Gibt die benutzerdefinierte Aktion mit dem angegebenen Bezeichner zurück.

Endpunkt	/getbyid(<benutzerdefinierte Benutzer-Aktions-ID>)
Parameter	Typ: Guid Die ID der abzurufenden benutzerdefinierten Benutzer-Aktion.
HTTP method	GET
Antwort	Typ: SP.UserCustomAction Die angegebene benutzerdefinierte Benutzer-Aktion.

  Anforderungsbeispiel

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

Sie können auch einfach die Aktions-ID in der UserCustomActionCollection-Ressource angeben. Beispiel: …/_api/web/usercustomactions('83393b01-0b73-4af5-9f0e-9ab0750a4ec4')

OData-Darstellung

Das folgende Beispiel stellt eine UserCustomActionCollection-Ressource im JSON-Format dar.

    {"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"
      }]
    }}

Zusätzliche Ressourcen

• Arbeiten mit Ordnern und Dateien mit REST

• Ausführen grundlegender Vorgänge unter Verwendung von SharePoint 2013-REST-Endpunkten

• Zugreifen auf SharePoint 2013-Daten über Add-Ins mithilfe der domänenübergreifenden Bibliothek

• OAuth-Authentifizierungs- und Autorisierungsablauf für in der Cloud gehostete Apps

• Verwenden von OData-Abfragevorgängen in SharePoint REST-Anforderungen

• REST-API-Referenz und Beispiele

• Einführung in den SharePoint 2013 REST-Dienst