SharePoint 2013
Erläuterungen zur REST-Schnittstelle von SharePoint 2013 und zu ihrer Verwendung
Mit der Representational State Transfer(REST)-Schnittstelle von SharePoint 2013 wird die SharePoint 2013-Entwicklungsplattform für Standardwebtechnologien und -sprachen geöffnet. Webanwendungen können SharePoint-Funktionen über das Clientobjektmodell bereits seit Langem verwenden, aber diese APIs sind nur für .NET-Anwendungen und -Sprachen verfügbar. Mit der umfassenden REST-Schnittstelle in SharePoint 2013 können Sie mit Standardwebsprachen wie JavaScript oder PHP und jeder beliebigen Technologie oder Sprache, die REST unterstützt, auf die meisten SharePoint-Funktionen und -Entitäten zugreifen.
Da die REST-Schnittstelle keine Verweise auf Clientassemblys erfordert, können Sie den Platzbedarf der Webanwendungen begrenzen, was insbesondere bei mobilen Anwendungen eine wichtige Rolle spielt. Die Vorteile von REST für mobile Anwendungen, die für Plattformen von anderen Anbietern als Microsoft geschrieben werden (z. B. iOS- und Android-Geräte), liegen auf der Hand. Aber REST ist auch eine nützliche Ressource für Entwickler von Windows 8-Apps. Eine in HTML5 und JavaScript geschriebene Windows 8-App benötigt die REST-Schnittstelle für SharePoint-Operationen, und C#-Entwickler, für die die Größe ihrer Apps wichtig ist, sollten REST in Betracht ziehen. In diesem Artikel wird gezeigt, wie Sie die Schnittstelle nutzen können, um die Leistungsfähigkeit der SharePoint-Plattform in die Anwendungen zu integrieren und erweiterte Operationen mit SharePoint-Entitäten auszuführen.
Grundlagen
Die Remotewebanwendung oder mobile Anwendung muss zunächst über autorisierten Zugriff verfügen, bevor sie SharePoint verwenden kann. In SharePoint 2013 gibt es zwei allgemeine Ansätze, um den Zugriff auf eine SharePoint-Website zu autorisieren (unabhängig davon, ob Sie REST verwenden). Der erste Ansatz umfasst die Authentifizierung eines SharePoint-Benutzers. In diesem Fall hat die Anwendung denselben Zugriff auf die SharePoint-Daten und -Funktionen wie der Benutzer. Die verschiedenen Methoden, mit denen Sie einen Benutzer in einer mobilen Anwendung oder Webanwendung authentifizieren können, würden den Rahmen dieses Artikels sprengen. Wir möchten aber kurz auf zwei neue Optionen von SharePoint 2013 eingehen, da sich diese darauf auswirken, wie Sie die REST-Anforderungen erstellen:
- Wenn Sie SharePoint von einer remote gehosteten Anwendung aufrufen, die den clientseitigen Code (HTML und JavaScript) nicht exklusiv verwenden kann, und es keine Firewall zwischen SharePoint und der Anwendung gibt, können Sie OAuth 2.0-Token mit Microsoft Access Control Service (Zugriffssteuerungsdienst, ACS) von Microsoft als sicherem Tokenserver verwenden.
- Wenn der clientseitige Code und die Berechtigungen eines in SharePoint angemeldeten Benutzers ausreichen, stellt die domänenübergreifende JavaScript-Bibliothek (bit.ly/12kFwSP) eine gute Alternative zu OAuth dar. Auch wenn Sie Remoteaufrufe durch eine Firewall ausführen, ist die domänenübergreifende Bibliothek jederzeit eine zweckmäßige Alternative. Im MSDN-Bibliotheksartikel „Datenzugriffsoptionen für Apps in SharePoint 2013“ (bit.ly/WGvt9L) werden diese Optionen ausführlich beschrieben.
Verwenden von OAuth Im MSDN-Bibliotheksartikel „Autorisierung und Authentifizierung für Apps in SharePoint 2013“ (bit.ly/XAyv28) finden Sie ausführliche Informationen zur Funktionsweise von OAuth in SharePoint 2013 und dazu, wie Sie ein Zugriffstoken für die Anwendung erhalten. Sobald Sie über ein Token verfügen, müssen Sie es mit jeder REST-Anforderung übergeben. Dazu fügen Sie einen Authorization-Header mit vorangestelltem „Bearer“ hinzu, der das Zugriffstoken als seinen Wert übergibt:
Authorization: Bearer access_token
Beispiele dafür, wie dies in C#- und JavaScript-Code ausgeführt wird, finden Sie im Abschnitt „Lesen von Daten mit der SharePoint 2013-REST-Schnittstelle“ im MSDN-Bibliotheksartikel „Gewusst wie: Ausführen grundlegender Vorgänge unter Verwendung von SharePoint 2013-REST-Endpunkten“ (bit.ly/13fjqFn). Im folgenden Beispiel, in dem alle Listen von einer SharePoint-Website abgerufen werden, wird eine grundlegende REST-Anforderung gezeigt, die ein OAuth-Token übergibt:
HttpWebRequest endpointRequest =
(HttpWebRequest)HttpWebRequest.Create(
"http:// <http:///> <site url>/_api/web/lists");
endpointRequest.Method = "GET";
endpointRequest.Accept = "application/json;odata=verbose";
endpointRequest.Headers.Add("Authorization",
"Bearer " + accessToken);
HttpWebResponse endpointResponse =
(HttpWebResponse)endpointRequest.GetResponse();
Verwenden der domänenübergreifenden JavaScript-Bibliothek Die domänenübergreifende SharePoint-Bibliothek ist in der Datei „SP.RequestExecutor.js“ enthalten, welche auf SharePoint-Servern im Verzeichnis „virtual /_layouts/15/“ gespeichert ist. Laden Sie diese Datei auf eine Remotewebseite, um sie zu verwenden. Erstellen Sie in JavaScript ein SP.RequestExecutor-Objekt, und rufen Sie anschließend dessen executeAsync-Methode auf. Als einen Parameter dieser Methode übergeben Sie die Informationen, die sie zum Erstellen einer HTTP-Anforderung an den REST-Dienst benötigt. Die Hauptunterschiede zwischen REST-Aufrufen mit OAuth und REST-Aufrufen mit der domänenübergreifenden Bibliothek bestehen darin, dass Sie für letztere kein Zugriffstoken in der Anforderung übergeben müssen, Sie jedoch (in der RESTful-URL) die SharePoint-Website angeben müssen, die als Clientkontextwebsite dient. Im MSDN-Bibliotheksartikel „Vorgehensweise: Zugreifen auf SharePoint 2013-Daten über Remote-Apps mithilfe der domänenübergreifenden Bibliothek“ (bit.ly/12kFwSP) werden diese Details gründlicher ausgeführt, beispielsweise der Unterschied zwischen App-Webs und Hostwebs. Im folgenden Beispiel, in dem alle Listen von einer SharePoint-Website abgerufen werden, wird eine REST-Anforderung gezeigt, die die domänenübergreifende Bibliothek verwendet:
var executor = new SP.RequestExecutor(appweburl);
executor.executeAsync(
{
url:
appweburl +
"/_api/SP.AppContextSite(@target)/web/lists?@target='" +
hostweburl + "'",
method: "GET",
headers: { "Accept": "application/json; odata=verbose" },
success: successHandler,
error: errorHandler
}
);
Erstellen von RESTful-URLs Der SharePoint-REST-Dienst wird in der Datei „client.svc“ im virtuellen Ordner „/_vti_bin“ auf der SharePoint-Website implementiert, aber SharePoint 2013 unterstützt die Abkürzung „_api“ anstelle von „_vti_bin/client.svc“. Die grundlegende URL für jeden Endpunkt lautet folgendermaßen:
http://<domain>/<site url>/_api/
Die dienstbezogenen URLs von spezifischen Endpunkten werden an diese Basis angefügt. Sie können zum Beispiel die Listen von einer SharePoint-Website mit dieser URL abrufen:
http://<domain>/<site url>/_api/web/lists
Sie können einen Verweis auf eine bestimmte Liste erhalten, indem Sie deren ID angeben oder – wie im folgenden Beispiel – ihren Titel:
_api/web/lists/getByTitle('samplelist')/
„web“ ist kein Platzhalter in diesen Beispielen, sondern der Name eines Objekts der Web-Klasse im Clientobjektmodell von SharePoint. „lists“ ist der Name einer Sammlungseigenschaft und „getByTitle“ ist eine Methode dieses Sammlungsobjekts. Durch dieses Paradigma kann Microsoft die API-Referenz für die Endpunkte und das JavaScript-Objektmodell kombinieren. Beispiele dafür sind „SP.Web.lists“ und „SP.ListCollection.getByTitle“ unter bit.ly/14a38wZ bzw. bit.ly/WNtRMO. Die Syntax spiegelt außerdem ungefähr die Struktur eines SharePoint-Mandanten wieder. Informationen über eine Websitesammlung erhalten Sie unter „_api/site“, Informationen über eine SharePoint-Website unter „_api/web“ und Informationen über alle Listen einer Website unter „_api/web/lists“. Die letzte URL liefert eine Listensammlung, die aus allen Listen auf der SharePoint-Website besteht. Sie können sehen, wie diese Objekte in XML dargestellt werden, indem Sie in Ihrer Entwicklungswebsitesammlung zu diesen URLs navigieren.
Jede wichtige Klasse des SharePoint-Inhaltsobjektmodells ist verfügbar, einschließlich Websitesammlung, Websites, Listen, Ordner, Felder und Listenelemente. Über die Klassen „SP.User“ (bit.ly/15M4fzo), „SP.UserCollection“ (bit.ly/16TQTnW), „SP.Group“ (bit.ly/X55Pga) und „SP.GroupCollection“ (bit.ly/ZnFHbG) können Sie Informationen über Benutzer erhalten. Die Tabelle in Abbildung 1 zeigt Beispiele verschiedener Endpunkte für Lesevorgänge.
Abbildung 1: Endpunkte für Lesevorgänge
| URL | Gibt zurück |
| _api/web/title | Den Titel der aktuellen Website |
| _api/web/lists(guid'<list id>') | Eine Liste |
| _api/web/lists/getByTitle('Announcements')/fields | Die Spalten in der Liste „Announcements“ |
| _api/web/lists/getByTitle('Task')/items | Die Elemente in der Liste „Task“ |
| _api/web/siteusers | Die Benutzer auf der Website |
| _api/web/sitegroups | Die Benutzergruppen auf der Website |
| _api/web/sitegroups(3)/users | Die Benutzer in Gruppe 3 |
| _api/web/GetFolderByServerRelativeUrl('/Shared Documents') | Den Stammordner in der Bibliothek freigegebener Dokumente |
| _api/web/GetFolderByServerRelativeUrl('/Plans')/Files('a.txt')/$value | Die Datei „a.txt“ aus der Plans-Bibliothek |
Standardmäßig werden die Daten als XML im AtomPub-Format, erweitert durch das OData-Format, zurückgegeben. Sie können die Daten aber im JSON-Format abrufen, indem Sie den folgenden accept-Header zur HTTP-Anforderung hinzufügen:
accept: application/json;odata=verbose
Ob Sie JSON oder Atom (XML) verwenden, ist von Ihren Fähigkeiten und der verwendeten Programmierplattform abhängig, und es spielt ebenfalls eine Rolle, ob die Netzwerklatenz ein Problem für die App sein wird. JSON verwendet viel weniger Zeichen und ist daher für geringere Nutzlasten über das Netzwerk sinnvoll. Andererseits haben die meisten wichtigen Plattformen einschließlich Microsoft .NET Framework umfassende, XML-verarbeitende Bibliotheken.
Wir gehen später darauf ein, wie Sie OData-Abfrageoperatoren verwenden, um die Daten auszuwählen, zu filtern und zu sortieren.
Schreiben für SharePoint Alle der bisherigen Abfragen verwenden das HTTP-Verb GET. Wenn Sie für SharePoint schreiben, verwenden die Abfragen das POST-Verb, obwohl Sie in einigen Fällen dieses Verb außer Kraft setzen, indem Sie der Abfrage einen X-HTTP-Method-Header hinzufügen und den Wert PUT, MERGE oder DELETE angeben. Im Allgemeinen wird POST verwendet, wenn Sie ein Objekt wie eine Website, eine Liste oder ein Listenelement erstellen. MERGE wird verwendet, wenn Sie bestimmte Eigenschaften eines Objekts aktualisieren und die anderen Eigenschaften ihre derzeitigen Werte beibehalten sollen. PUT wird verwendet, wenn Sie ein Element ersetzen möchten. Dabei werden Eigenschaften, die nicht speziell in der Anforderung erwähnt werden, auf ihre Standardwerte zurückgesetzt. DELETE wird verwendet, wenn Sie ein Element entfernen möchten.
Jede Anforderung, die für SharePoint geschrieben wird, muss einen Formulardigest enthalten. Ihr Code erhält den Digest als Teil eines Informationssatzes, der vom folgenden Endpunkt zurückgegeben wird:
_api/contextinfo
In dieser Anforderung (mit leerem Text) müssen Sie das POST-Verb verwenden und den Authorization-Header wie oben beschrieben hinzufügen. In einigen Frameworks müssen Sie angeben, dass die Länge der POST-Anforderung 0 ist. In der zurückgegebenen Struktur ist eine FormDigestValue-Eigenschaft enthalten, die den Formulardigest enthält. In allen folgenden POST-Anforderungen fügen Sie einen X-RequestDigest-Header mit dem Digest als Wert hinzu.
Wenn Sie mit einer SharePoint-gehosteten App und einer Seite arbeiten, die die Standardmasterseite für SharePoint verwendet, ist der Digest bereits auf der Seite in einem Element mit der ID „__REQUESTDIGEST“ (mit zwei Unterstrichen) enthalten. Anstatt den contextinfo-Endpunkt aufzurufen, können Sie also einfach den Wert mit einem Skript wie dem folgenden jQuery-Code lesen:
var formDigestValue = $("__REQUESTDIGEST").val()
Natürlich müssen Sie dem Textkörper der Anforderung die Daten hinzufügen, die Sie schreiben möchten, oder die Daten identifizieren, die Sie löschen möchten. Sie können entweder das AtomPub/OData- oder das JSON-Format verwenden. Wenn Sie sich für Letzteres entscheiden, müssen Sie der Anforderung einen content-type-Header wie den Folgenden hinzufügen:
content-type: application/json;odata=verbose
Einen vollständigen Satz konkreter Beispiele für CRUD-Vorgänge (Create, Read, Update und Delete – Erstellen, Lesen, Aktualisieren und Löschen) für SharePoint-Objekte finden Sie unter „Gewusst wie: Ausführen grundlegender Vorgänge unter Verwendung von SharePoint 2013-REST-Endpunkten“ unter bit.ly/13fjqFn.
Erweiterte Vorgänge
Die SharePoint 2013-REST-Schnittstelle bringt einen bestimmten Grad an Komplexität mit sich. Die Schnittstelle unterstützt Vorgänge zum Sortieren, Filtern und Ordnen der Daten, die sie zurückgibt. Sie unterstützt auch eine große Anzahl von SharePoint-spezifischen Vorgängen. Durch diese zusätzlichen Funktionen erhalten Sie Features und Vorteile, die in einer Standard-REST-Implementierung nicht immer zu finden sind. In den nächsten Abschnitten werden einige der wichtigsten Faktoren erläutert, die Ihnen bei der Arbeit mit REST und SharePoint begegnen werden.
Filtern, Auswählen und Sortieren Sie können die OData-Systemabfrageoptionen verwenden, um zu steuern, welche Daten zurückgegeben werden und wie diese Daten sortiert werden. Abbildung 2 zeigt die unterstützten Optionen.
Abbildung 2: Optionen zum Filtern und Sortieren von Daten
| Option | Zweck |
| $select | Gibt an, welche Felder in den zurückgegebenen Daten enthalten sind. |
| $filter | Gibt an, welche Member einer Sammlung, z. B. Elemente in einer Liste, zurückgegeben werden. |
| $expand | Gibt an, welche übertragenen Felder von einer zugeordneten Liste zurückgegeben werden. |
| $top | Gibt nur die ersten n Elemente einer Sammlung oder Liste zurück. |
| $skip | Überspringt die ersten n Elemente einer Sammlung oder Liste und gibt die Übrigen zurück. |
| $orderby | Gibt das Feld an, das zum Sortieren der Daten vor der Rückgabe verwendet wird. |
Wenn Sie zum Beispiel den Autor, den Titel und die ISDN-Nummer aus einer Liste namens Books zurückgeben möchten, verwenden Sie folgenden Code:
_api/web/lists/getByTitle('Books')/items?$select=Author,Title,ISBN
Wird die $select-Option nicht verwendet, werden alle Felder zurückgegeben. Eine Ausnahme dabei sind Felder, die zu ressourcenintensiv wären, um vom Server zurückgegeben zu werden. Wenn Sie diese Felder benötigen, müssen Sie die $select-Option verwenden und die Felder namentlich angeben. Um alle Felder abzurufen, verwenden Sie: $select=‘*’
Um alle Bücher von Mark Twain abzurufen, verwenden Sie:
_api/web/lists/getByTitle('Books')/items?$filter=Author eq 'Mark Twain'
Eine Liste aller Operatoren, die für die $filter-Option unterstützt werden, finden Sie unter „Programmieren mit dem SharePoint 2013-REST-Dienst“ unter bit.ly/Zlqf3e.
Mit folgendem Code sortieren Sie die Bücher nach Titel in aufsteigender Reihenfolge:
_api/web/lists/getByTitle('Books')/items?$orderby=Title asc
Ersetzen Sie „asc“ durch „desc“, wenn Sie eine absteigende Reihenfolge festlegen möchten. Um nach mehreren Feldern zu sortieren, legen Sie eine kommagetrennte Liste von Feldern fest.
Mit dem &-Operator können Sie mehrere Optionen verbinden. Mit dem folgenden Code erhalten Sie nur die Titel der ersten beiden Bücher von Mark Twain:
_api/web/lists/getByTitle(
'Books')/items?$select=Title&$filter=Author eq 'Mark Twain'&$top=2
Der Dienst löst jede Option vollständig auf, bevor er die nächste anwendet. Daher wird jede Option nur auf den Datensatz angewendet, der durch die Optionen links von ihr in der URL erstellt wird. Es kommt also auf die Reihenfolge an, in der Sie die Optionen anwenden. Die folgende URL gibt beispielsweise die Elemente 3-10 zurück:
_api/web/lists/getByTitle('Books')/items?$top=10&$skip=2
Durch die zwei Optionen in umgekehrter Reihenfolge erhalten Sie aber die Elemente 3-12:
_api/web/lists/getByTitle('Books')/items?$skip=2&$top=10
Sie können die unteren n Elemente mithilfe einer absteigenden $orderby- und einer $top-Option (in dieser Reihenfolge) erhalten. Mit der folgenden URL werden die untersten zwei Elemente abgerufen:
_api/web/lists/getByTitle('Books')/items?$orderby=ID desc&$top=2
Wenn eine SharePoint-Liste ein Nachschlagefeld für eine andere Liste hat, funktioniert dies effektiv als Verbindung der zwei Listen. Mit der $expand-Option können Sie die übertragenen Felder aus der verbundenen Liste zurückgeben. Wenn die Books-Liste beispielsweise ein PublishedBy-Feld hat, das das Name-Feld in einer Publisher-Liste nachschlägt, können Sie diese Namen mit dieser URL zurückgeben:
_api/web/lists/getByTitle(
'Books')/items?$select=Title,PublishedBy/Name&$expand=PublishedBy
Sie referenzieren die Spalte in der foreign-Liste mit der Syntax „lookup_column_display_name/foreign_column_name“, nicht mit „foreign_list_name/foreign_column_name“. Ebenfalls wichtig: Sie können kein Nachschlagefeld „name“ auswählen, ohne es zu erweitern.
Arbeiten mit Dateien und Ordnern Eine Dokumentbibliothek können Sie am besten erreichen, indem Sie die GetFolderByServerRelativeUrl-Methode nutzen, die unter „/_api/web“ verfügbar ist. Wenn Sie einer Dokumentbibliothek eine Datei hinzufügen, senden Sie den Inhalt der Datei im Anforderungstext, und Sie übergeben den Namen der Datei in der URL:
http://<site url>/_api/web/GetFolderByServerRelativeUrl(
'/Shared Documents')/Files/add(url='a.txt',overwrite=true)
Beim Aktualisieren von Dateien müssen Sie beachten, dass Sie nur die PUT HTTP-Methode verwenden können. Sie können daher nicht den Inhalt einer Datei mit einer Datei zusammenfügen, die bereits in einer Dokumentbibliothek gespeichert ist. Stattdessen ersetzen Sie eine Dateiversion durch eine andere. Sie müssen auch sicherstellen, dass Sie den $value-Operator in der URL verwenden, damit Sie Zugriff auf den Inhalt der Datei selbst erhalten, anstatt auf die mit der Datei verknüpften Metadaten:
http://<site url>/_api/web/GetFileByServerRelativeUrl(
'/Shared Documents/a.txt')/$value
In SharePoint ist es eine bewährte Methode, Dateien auszuchecken, bevor Sie sie ändern. Checken Sie also eine Datei aus, bevor Sie sie aktualisieren, und checken Sie sie anschließend wieder ein, wenn Sie die Änderung abgeschlossen haben. Für die folgenden Operationen müssen Sie POST-Anforderungen mit leerem Anforderungstext an diese URLs ausführen:
http://<site url>/_api/web/GetFileByServerRelativeUrl(
'/Shared Documents/a.txt')/CheckOut()
http://<site url>/_api/web/GetFileByServerRelativeUrl(
'/Shared Documents/a.txt')/CheckIn(comment='Comment', checkintype=0)
Die CheckIn-Methode erfordert zwei Parameter. Mit dem comment-Parameter können Sie dem Einchecken einen Kommentar hinzufügen, und der checkintype-Parameter gibt an, ob es sich beim Einchecktyp um eine Neben- (0) oder eine Hauptversion (1) handelt.
Eine letzte Überlegung besteht darin, dass REST Ihre einzige Option ist, wenn Sie mit Code arbeiten, der im Clientbrowser ausgeführt wird (wie JavaScript), und Sie eine Datei mit mehr als 1,5 MB hochladen möchten. Diese Art der Operation mit umfangreichen Dateien (größer als 1,5 MB) ist nur für Internet Explorer 10 (und höher) und andere moderne Browser der gleichen Generation verfügbar. Das Beispiel in Abbildung 3 zeigt, wie Sie eine Binärdatei mithilfe der domänenübergreifenden Bibliothek hochladen können.
Abbildung 3: Hochladen einer Binärdatei mithilfe der domänenübergreifenden Bibliothek
function uploadFileBinary() {
var executor = new SP.RequestExecutor(appweburl);
var body = "";
for (var i = 0; i < 1000; i++) {
var ch = i % 256;
body = body + String.fromCharCode(ch);
}
var info = {
url: "_api/web/lists/getByTitle('Shared Documents')/RootFolder/Files/Add(url='a.dat', overwrite=true)",
method: "POST",
binaryStringRequestBody: true,
body: body,
success: success,
error: fail,
state: "Update"};
executor.executeAsync(info);
}
Änderungsabfragen Bisher haben wir die Funktionsweise von REST mit SharePoint-Entitäten beschrieben, die Sie mit URLs erreichen, welche die Struktur einer SharePoint-Website nachahmen. Einige SharePoint-Typen können auf diese Weise allerdings nicht erreicht oder dargestellt werden. Im REST-Kontext zählen dabei zu den drei wichtigsten Typen „ChangeQuery“, „ChangeLogItemQuery“ und „ChangeToken“.
Mit ChangeQuery-Objekten können Sie das SharePoint-Änderungsprotokoll auf alle Aktualisierungen prüfen, die für eine SharePoint-Websitesammlung, Website oder Liste ausgeführt wurden. Die REST-Schnittstelle macht eine getchanges-Methode an jedem der folgenden drei Speicherorte verfügbar:
- „/_api/site“ (für Websitesammlungen)
- „/_api/web“ (für Websites)
- „/_api/web/lists/list(guid'<list id>')“ oder „/_api/web/lists/getByTitle('list title')“ (für Listen)
Sie übergeben eine Abfrage an einen dieser Speicherorte, indem Sie dem entsprechenden URL-Pfad „/getchanges“ hinzufügen, und dann ein ChangeQuery-Objekt über den POST-Text der Anforderung senden. Ein einfache Änderungsabfrage nach allen Elementen, die einer Liste hinzugefügt wurden, würde in JSON folgendermaßen lauten:
{
'query': {
'__metadata': {
'type': 'SP.ChangeQuery'
},
'Add': 'true',
'Item': 'true'
}
}
Die getchanges-Methode erwartet einen Anforderungstext, der eine Darstellung des ChangeQuery-Objekts innerhalb des Abfrageparameters enthält. Um sich auf eine bestimmte Liste zu beziehen, senden Sie diese Anforderung an die URL:
/_api/web/lists/list(guid'<list id>')/getchanges
oder
/_api/web/lists/getByTitle('<list title>')/getchanges
In der Antwort wird ein Ergebnis zurückgegeben, das eine Sammlung der Änderungen enthält, die der Anforderung entsprechen. Wenn die Liste nur über ein Element verfügt, sähe der Antworttext folgendermaßen aus:
{"d":
{"results":[{
"__metadata":{
"id":"https://<site url>/_api/SP.ChangeItema7e7c6e9-2c41-47c3-aae9-2b4a63b7a087",
"uri":"https://site url/_api/SP.ChangeItem",
"type":"SP.ChangeItem"},
"ChangeToken":{"__metadata":{"type":"SP.ChangeToken"},
"StringValue":"1;3;482e418a-0900-414b-8902-02248c2e44e8;634955266749500000;5749111"},
"ChangeType":1,
"SiteId":"ce11bfbb-cf9d-4b2b-a642-8673bd48cceb",
"Time":"2013-02-03T22:17:54Z",
"ItemId":1,
"ListId":"482e418a-0900-414b-8902-02248c2e44e8",
"WebId":"a975b994-fc67-4203-a519-b160175ca967"}]
}
}
Sie können der Antwort entnehmen, dass zu einer Zeit, die in dem Änderungsprotokoll vom „ChangeToken“ dargestellt wird, ein einziges Listenelement (mit dem ItemID-Wert 1) hinzugefügt wurde. Sie können den Zeichenfolgenwert dieses Objekts nutzen, um die Abfragen zu präzisieren. Geben Sie beispielsweise Werte für die ChangeTokenStart- und ChangeTokenEnd-Eigenschaften des ChangeQuery-Objekts an, um sicherzustellen, dass Sie Änderungen erhalten, die vor oder nach einem bestimmten Zeitpunkt oder zwischen zwei Zeitpunkten ausgeführt wurden.
Sie können auch den Wert des ChangeToken-Objekts nutzen, wenn Sie die getListItemChangesSinceToken-Methode verwenden:
/_api/web/lists/list(guid'<list id>')/getListChangesSinceToken
Diese Methode gibt es nur in der REST-Schnittstelle. Wenn Sie alle Änderungen an Elementen in dieser Liste seit dem Hinzufügen des ersten Elements erfahren möchten, erstellen Sie ein ChangeLogItemQuery-Objekt, dass das Änderungstoken enthält:
{
'query': {
'__metadata': {
'type': 'SP.ChangeLogItemQuery'
},
'ChangeToken':'1;3;482e418a-0900-414b-8902-02248c2e44e8;634955266749500000;5749111'
}
}
SharePoint Server 2013-Featurebereiche Alle in diesem Artikel besprochenen Operationen beziehen sich auf SharePoint Foundation 2013 und SharePoint Server 2013, da sie Kernfunktionen von SharePoint betreffen. Die SharePoint-REST-Schnittstelle macht zudem viele der Funktionen der SharePoint Server 2013-Featurebereiche verfügbar. Diese Featurebereiche würden über den Rahmen dieses Artikels hinausgehen. Weitere Informationen darüber, wie Sie REST mit ihnen verwenden können, finden Sie aber in den folgenden Ressourcen im SDK:
- „SharePoint 2013: Verwenden des REST-Suchdiensts in einer App für SharePoint“ (bit.ly/Mt4szN)
- „Erste Schritte beim Entwickeln von Features für das soziale Netzwerk in SharePoint 2013“ (bit.ly/102qIGM)
- „BCS-REST-API-Referenz für SharePoint 2013“ (bit.ly/10FFMMu)
Debuggen
Die wichtigste Information, die Sie zum Ausführen einer REST-Operation benötigen, ist offensichtlich die korrekte URL. Wir haben viele der wichtigsten URLs beschrieben, und Sie können viele weitere im SDK für SharePoint finden. Informationen zu REST-Endpunkt-URLs können Sie in der Modellreferenz zum JavaScript-Objektmodell erhalten, da die REST-Schnittstelle nach dem Clientobjektmodell modelliert wurde. Wenn Sie zum Beispiel wissen möchten, welche URLs für die Arbeit mit Listensammlungen verfügbar sind, finden Sie diese Information in der Referenzdokumentation für das SP.ListCollection-Objekt unter bit.ly/108hI1e.
Sie können auch als angemeldeter Benutzer eine REST-URL aufrufen und die XML-Ausgabe beliebiger GET-Anforderungen anzeigen, um zu sehen, welche Daten an dem entsprechenden Endpunkt verfügbar sind, und wie diese Daten strukturiert sind. Bei POST-Anforderungen hilft Ihnen das nicht weiter, aber Sie können sich mit den verschiedenen SharePoint-Entitäten und den verfügbaren Informationen an den jeweiligen Endpunkten vertraut machen.
Wichtig ist, dass die HTTP-Anforderungen, die Sie in Ihrem Code senden, korrekt codierte URLs enthalten. Wenn Sie in SharePoint eine App für SharePoint starten, können Sie eine codierte URL aus dem SPHostUrl-Abfragezeichenfolgen-Argument abrufen, aber in anderen Kontexten müssen Sie die URL möglicherweise selbst codieren.
Wenn Sie komplexere Operationen ausführen – insbesondere solche, die das POST HTTP-Verb erfordern – müssen Sie ein HTTP-Ablaufverfolgungsdienstprogramm verwenden, um die HTTP-Anforderungen zu debuggen. Bei ungültigen Anforderungen gibt SharePoint Fehlermeldungen zurück, und diese enthalten viele Informationen darüber, warum die Anforderungen scheitern. Es kann zum Beispiel so sein, dass die Anwendung oder der Benutzer einfach nicht dazu autorisiert ist, bestimmte Arten von Informationen von SharePoint zu erhalten. In anderen Fällen haben Sie möglicherweise ein ungültiges JSON-Objekt erstellt, oder Sie haben vielleicht einer Eigenschaft einen ungültigen Wert zugeordnet.
Einige Frameworks bieten Ihnen HTTP-Ablaufverfolgungsdienstprogramme. Wenn Sie mit ASP.NET-Anwendungen arbeiten, können Sie „trace.axd“ verwenden (bit.ly/8bnst4). Wenn Sie die Anforderungen direkt aus dem Browser senden, wie bei JavaScript, können Sie Fiddler verwenden (fiddler2.com/fiddler2). Wir haben die HTTP-Beispielantworten in diesem Artikel mit Fiddler generiert.
Verwenden von REST für die Kommunikation mit SharePoint in einer PHP-Anwendung
Wie einleitend erwähnt, können Sie mithilfe der REST-Schnittstelle in jeder der Standardsprachen und -frameworks, die Webentwickler normalerweise verwenden, mit SharePoint interagieren. Um dies zu zeigen, haben wir eine PHP-Beispielanwendung veröffentlicht, die zeigt, wie Sie in einer in PHP geschriebenen Remotewebanwendung mit einer SharePoint-Website interagieren können. Diese spezielle Anwendung ist eine App für SharePoint, die von einer Office 365 SharePoint-Website gestartet und von einer Windows Azure-Website ausgeführt wird. Diese Architektur vereinfacht einige Schritte, wie das Veröffentlichen der Website, aber der PHP-Code im Beispiel kann in jeder Architektur ausgeführt werden, die PHP unterstützt.
Sie können das Beispiel aus der Codegalerie unter bit.ly/ZQsmvP herunterladen. Im Beispiel wird u. a. gezeigt, wie Sie mit REST mit Dateien und Ordnern arbeiten, wie Sie ein gültiges OAuth-Zugriffstoken aus einer PHP-Anwendung erhalten und wie Sie die domänenübergreifende JavaScript-Bibliothek verwenden. Und was in diesem Kontext am wichtigsten ist, es wird gezeigt, wie Dateien mithilfe von REST und PHP aus einer SharePoint-Bibliothek abgerufen bzw. in diese hochgeladen werden.
Da die Anwendung Daten in eine SharePoint-Website schreibt, gehört es zu ihren ersten Aufgaben (nach dem Abrufen eines Zugriffstokens), den Formulardigest von „_api/contextinfo“ anzufordern. Die Anforderung übergibt in den Headern das Zugriffstoken und richtet eine POST-Anforderung an eine SSL-URL ein. Der in Abbildung 4 gezeigte Code wird jedem bekannt sein, der mit PHP-Client-URL-Objekten gearbeitet hat.
Abbildung 4: Anfordern des Formulardigests
$opts = array (
'Authorization: Bearer ' .
$accToken);
$ch = curl_init();
$url = $appweburl . '/_api/contextinfo';
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, $opts);
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, '');
curl_setopt ($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt ($ch, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($ch);
Nach dem Ausführen der Anforderung verarbeitet die Anwendung den XML-Code und speichert den Wert für den Formulardigest:
$root = new SimpleXmlElement($result);
$ns = $root->getNameSpaces(TRUE);
$childrenNodes = $root->children($ns['d']);
$formValue = $childrenNodes->FormDigestValue;
Sie speichert in einem Cookie auch das Zugriffstoken. Wenn der Benutzer eine Datei hochlädt, übergibt die Anwendung diese Werte an eine HTML-Datei, die die HTTP-Anforderung zum Hochladen von Dateien in eine Dokumentbibliothek erstellt. Vor dem Einrichten der Anforderung werden die Daten aus der lokal gespeicherten Datei in ein Zeichenfolgenobjekt gelesen, dass als Text der POST-Anforderung übergeben wird:
$accToken = $_COOKIE["moss_access_token"];
$url = $_REQUEST["target"] .
$furl = $_FILES["file"]["tmp_name"];
$file = fopen($furl,"r");
$post_data = fread($file,filesize($furl));
fclose($file);
In den Codezeilen in Abbildung 5 werden die Formulardigest- und Zugriffstokenwerte abgerufen, und die HTTP-Anforderung, die die Datei hochlädt, wird eingerichtet und ausgeführt.
Abbildung 5: Ausführen der Anforderung, die die Datei hochlädt
"/_api/web/GetFolderByServerRelativeUrl('Lists/SharedDoc')/Files/
add(url='" . $_FILES["file"]["name"] . "',overwrite=true)";
$opts = array (
'X-RequestDigest:' . $_REQUEST["digest"],
'Authorization: Bearer ' . $accToken);
// Initialize cURL
$ch = curl_init();
curl_setopt($ch, CURLOPT_HTTPHEADER, $opts);
// Set URL on which you want to post the Form and/or data
curl_setopt($ch, CURLOPT_URL, $url);
// Data+Files to be posted
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
// Pass TRUE or 1 if you want to wait for and catch the
// response against the request made
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
// For Debug mode; shows up any error encountered during the operation
curl_setopt($ch, CURLOPT_VERBOSE, 1);
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt ($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt ($ch, CURLOPT_SSL_VERIFYPEER, 0);
// Execute the request
$response = curl_exec($ch);
Wie geht es weiter?
Die SharePoint 2013-REST-Schnittstelle ist dem Clientobjektmodell zwar nicht vollständig ebenbürtig, aber sie ist umfassend und leistungsfähig genug, um die meisten Wünsche von Webentwicklern und Entwicklern mobiler Apps umzusetzen, insbesondere wenn diese mit anderen Frameworks als .NET arbeiten. Wir sind auf viele der wichtigsten Methoden eingegangen, mit denen Sie SharePoint mithilfe der REST-Schnittstelle in Ihre Anwendungen integrieren können. Es gibt jedoch noch viele weitere Möglichkeiten.
Das SharePoint 2013 SDK enthält eine Sammlung von Ressourcen für die REST-Entwicklung. Sie finden alle entsprechenden Links auf der MSDN-Bibliotheksseite „SharePoint 2013 – REST-API, Endpunkte und Beispiele“ (bit.ly/137q9yk). Diese Sammlung wird weiter ergänzt und wird insbesondere eine große Bandbreite an Beispielen umfassen, denn wie das PHP-Beispiel zeigt, erweitert die REST-Schnittstelle die Welt der SharePoint-Entwicklung erheblich.
Jim Crowleyarbeitet als leitender Redakteur im Bereich Programmierung in der Office Division. Er verfasst Entwicklerdokumentation für SharePoint 2013, und er hat auch die SharePoint Developer Documentation RSS Reader-App (bit.ly/YIVbvY) für Windows Phone 7 geschrieben.
Ricky Kirkhamarbeitet als leitender Redakteur im Bereich Programmierung in der Office Division und ist Microsoft Certified Professional Developer (SharePoint 2010). Kirkham gehört dem Microsoft-Entwicklerdokumentationsteam für SharePoint seit 2006 an.
Unser Dank gilt dem folgenden technischen Experten für die Durchsicht dieses Artikels: Jyoti Jacob (Microsoft)