sharepoint
Usługi REST
Szukaj…
Uwagi
Adresy URL punktów końcowych usługi REST
Interfejs API dostępu klienta REST został po raz pierwszy wprowadzony w programie SharePoint 2010, ale został znacznie rozszerzony w programie SharePoint 2013. Interfejs API REST w programie SharePoint 2010 jest dostępny za pośrednictwem usługi sieci Web ListData pod /_vti_bin/ListData.svc
URL /_vti_bin/ListData.svc
. Program SharePoint 2013 wprowadził adresy URL punktów końcowych /_api/lists/
i /_api/web
, które zachowują się nieco inaczej.
Powyższe adresy URL punktów końcowych powinny być poprzedzone http://server/site
gdzie server
reprezentuje nazwę serwera, a site
reprezentuje nazwę lub ścieżkę do określonej witryny.
Przykładowy adres URL dla ... | SharePoint 2010 | SharePoint 2013 |
---|---|---|
Pobieranie listy: | /_vti_bin/ListData.svc/ListName | /_api/lists('ListGuid') |
Pobieranie przedmiotu: | /_vti_bin/ListData.svc/ListName(1) | /_api/lists('ListGuid')/items(1) |
Pobieranie Internetu: | (brak odpowiednika) | /_api/web |
Pomimo różnic w dostępie do list i elementów listy, praca z tymi wynikami jest bardzo podobna w obu wersjach.
Należy pamiętać, że usługa ListData.svc
jest nadal dostępna w programie SharePoint 2013 w celu zapewnienia zgodności z poprzednimi wersjami.
Wysyłanie żądań REST
Żądanie REST można przesłać za pomocą natywnego kodu JavaScript XMLHttpRequest lub za pomocą konstruktora opakowania AJAX jQuery.
Składnia XMLHttpRequest
var xhr = new XMLHttpRequest();
xhr.open(verb, url, true);
xhr.setRequestHeader("Content-Type","application/json");
xhr.send(data);
jQuery AJAX Składnia
$.ajax({
method: verb,
url: url,
headers: { "Content-Type":"application/json" },
data: data
});
Aby uzyskać więcej informacji na temat wysyłania żądań za pośrednictwem AJAX, zobacz dokumentację JavaScript AJAX .
Praca z listami
Pobieranie elementów listy
Ten przykład pokazuje, jak pobrać wszystkie elementy listy i iterować je. Za pomocą top
parametru można zażądać określonej liczby wyników. Możesz także użyć parametru select
, aby wybrać określone pola ( $select=id, Title, uri
).
JavaScript
function GetListItems(){
$.ajax({
url: "../_api/web/lists/getbytitle('List Title')/items?$top=50"
contentType: "application/json;odata=verbose",
method: "GET",
headers: { "accept": "application/json;odata=verbose" },
success: function (data) {
$.each(data.d.results, function(index,item){
//use item to access the individual list item
console.log(item.Id);
});
},
error: function(error){
console.log(error);
}
});
}
Uzyskiwanie pojedynczego elementu listy
JavaScript
function GetListItem(){
$.ajax({
url: "../_api/web/lists/getbytitle('List Title')/items(1)",
contentType: "application/json;odata=verbose",
method: "GET",
headers: { "accept": "application/json;odata=verbose" },
success: function (data) {
console.log(data.d.Id);
},
error: function(error){
console.log(error);
}
});
}
Uzyskaj elementy listy z kolumnami odnośników
Czasami możesz mieć strukturę listy, która wygląda następująco:
Tabela zwierząt
Nazwa | Rodzaj | Opis |
---|---|---|
Tytuł | Ciąg (tekst) | Imię zwierzęcia |
Wiek | Numer | Ile lat ma zwierzę |
Wartość | Waluta | Wartość zwierzęcia |
Rodzaj | Wyszukiwanie (tabela rodzajów zwierząt) | Pole odnośników (daje listę opcji do wyboru z tabeli rodzajów zwierząt) |
Tabela rodzajów zwierząt
Nazwa | Rodzaj | Opis |
---|---|---|
Tytuł | Ciąg (tekst) | Nazwa gatunku / rodzaju zwierzęcia (np. Świnia) |
NumLegs | Numer | Liczba nóg zwierzęcia |
Prawdopodobnie nie jest to najpoważniejszy przykład, ale problem jest nadal aktualny. Gdy używasz zwykłego żądania w celu pobrania wartości z listy SharePoint, dla Type
zwierzęcia otrzymasz tylko odpowiedź o nazwie TypeId
w odpowiedzi JSON. Aby rozwinąć te elementy w jednym wywołaniu AJAX, wymagane są dodatkowe znaczniki w parametrach adresu URL.
Ten przykład dotyczy nie tylko kolumn odnośników. Gdy korzystasz z kolumn People/Groups
, są one w zasadzie tylko wyszukiwaniem, więc możesz łatwo wyciągać takie elementy, jak Title
, EMail
i inne.
Przykładowy kod
Ważna uwaga : Kiedy definiujesz pola, które chcesz odzyskać z kolumn odnośników, musisz poprzedzić nazwę pola nazwą pola odnośników w oryginalnej tabeli. Na przykład jeśli chcesz NumLegs
atrybut NumLegs
z kolumny odnośnika, musisz wpisać Type/NumLegs
.
JavaScript
// webUrl: The url of the site (ex. https://www.contoso.com/sites/animals)
// listTitle: The name of the list you want to query
// selectFields: the specific fields you want to get back
// expandFields: the name of the fields that need to be pulled from lookup tables
// callback: the name of the callback function on success
function getItems(webUrl,listTitle,selectFields, expandFields, callback){
var endpointUrl = webUrl + "/_api/web/lists/getbytitle('" + listTitle + "')/items";
endpointUrl+= '?$select=' + selectFields.join(",");
endpointUrl+= '&$expand=' + expandFields.join(",");
return executeRequest(endpointUrl,'GET', callback);
}
function executeRequest(url,method,callback,headers,payload)
{
if (typeof headers == 'undefined'){
headers = {};
}
headers["Accept"] = "application/json;odata=verbose";
if(method == "POST") {
headers["X-RequestDigest"] = $("#__REQUESTDIGEST").val();
}
var ajaxOptions =
{
url: url,
type: method,
contentType: "application/json;odata=verbose",
headers: headers,
success: function (data) { callback(data) }
};
if(method == "POST") {
ajaxOptions.data = JSON.stringify(payload);
}
return $.ajax(ajaxOptions);
}
// Setup the ajax request by setting all of the arguments to the getItems function
function getAnimals() {
var url = "https://www.contoso.com/sites/animals";
var listTitle = "AnimalListing";
var selectFields = [
"Title",
"Age",
"Value",
"Type/Title",
"Type/NumLegs"
];
var expandFields = [
"Type/Title",
"Type/NumLegs"
];
getItems(url, listTitle, selectFields, expandFields, processAnimals);
}
// Callback function
// data: returns the data given by SharePoint
function processAnimals(data) {
console.log(data);
// Process data here
}
// Start the entire process
getAnimals();
Dodawanie selekcji do pola wyszukiwania wielowartościowego
W tym przykładzie założono, że kolumna wyszukiwania ma nazwę MultiLookupColumnName
i że chcesz ustawić pole wyszukiwania wielokrotnego na wyszukiwanie elementów o identyfikatorach 1 i 2.
Korzystanie z jQuery AJAX
var listName = "YourListName";
var lookupList = "LookupListName";
var idOfItemToUpdate = 1;
var url = "/server/site/_vti_bin/ListData.svc/"+listName+"("+idOfItemToUpdate+")";
var data = JSON.stringify({
MultiLookupColumnName:[
{__metadata:{uri:"http://yoursiteurl/_vti_bin/ListData.svc/"+lookupList+"(1)"}},
{__metadata:{uri:"http://yoursiteurl/_vti_bin/ListData.svc/"+lookupList+"(2)"}}
]
});
$.ajax({
method: 'POST',
url: url,
contentType: 'application/json',
headers: {
"X-HTTP-Method" : "MERGE",
"If-Match" : "*"
},
data: data
});
var listGuid = "id-of-list-to-update"; // use list GUID here
var lookupGuid = "id-of-lookup-list"; // use lookup list GUID here
var idOfItemToUpdate = 1;
var url = "/server/site/_api/lists('"+ listGuid + "')/items("+ idOfItemToUpdate + ")";
var data = JSON.stringify({
MultiLookupColumnName:[
{__metadata:{uri:"http://yoursiteurl/_api/lists('" + lookupGuid + "')/items(1)"}},
{__metadata:{uri:"http://yoursiteurl/_api/lists('" + lookupGuid + "')/items(2)"}}
]
});
$.ajax({
method: 'POST',
url: url,
contentType: 'application/json',
headers: {
"X-HTTP-Method" : "MERGE",
"If-Match" : "*"
},
data: data
});
Korzystanie z XMLHttpRequest
var listName = "YourListName";
var lookupList = "LookupListName";
var idOfItemToUpdate = 1;
var url = "/server/site/_vti_bin/ListData.svc/YourListName("+idOfItemToUpdate+")";
var data = JSON.stringify({
MultiLookupColumnName:[
{__metadata:{uri:"http://yoursiteurl/_vti_bin/ListData.svc/"+lookupList+"(1)"}},
{__metadata:{uri:"http://yoursiteurl/_vti_bin/ListData.svc/"+lookupList+"(2)"}}
]
});
var xhr = new XMLHttpRequest();
xhr.open("POST",url,true);
xhr.setRequestHeader("X-HTTP-Method", "MERGE");
xhr.setRequestHeader("If-Match", "*");
xhr.setRequestHeader("Content-Type","application/json");
xhr.send(data);
var listGuid = "id-of-list-to-update";
var lookupGuid = "id-of-lookup-list";
var idOfItemToUpdate = 1;
var url = "/server/site/_api/lists('"+ listGuid + "')/items("+ idOfItemToUpdate + ")";
var data = JSON.stringify({
MultiLookupColumnName:[
{__metadata:{uri:"http://yoursiteurl/_api/lists('" + lookupGuid + "')/items(1)"}},
{__metadata:{uri:"http://yoursiteurl/_api/lists('" + lookupGuid + "')/items(2)"}}
]
});
var xhr = new XMLHttpRequest();
xhr.open("POST",url,true);
xhr.setRequestHeader("X-HTTP-Method", "MERGE");
xhr.setRequestHeader("If-Match", "*");
xhr.setRequestHeader("Content-Type","application/json");
xhr.send(data);
Elementy listy stronicowania zwrócone z zapytania
Aby symulować stronicowanie przy użyciu usługi REST, możesz wykonać następujące czynności:
Użyj parametru
$skip=n
, aby pominąć pierwszen
wpisów zgodnie z parametrem$orderby
Użyj parametru
$top=n
, aby zwrócić pierwszen
wpisów zgodnie z parametrami$orderby
i$skip
.
var endpointUrl = "/_api/lists('guid')/items"; // SP2010: "/_vti_bin/ListData.svc/ListName";
$.getJSON(
endpointUrl + "?$orderby=Id&$top=1000",
function(data){
processData(data); // you can do something with the results here
var count = data.d.results.length;
getNextBatch(count, processData, onComplete); // fetch next page
}
);
function getNextBatch(totalSoFar, processResults, onCompleteCallback){
$.getJSON(
endpointUrl + "?$orderby=Id&$skip="+totalSoFar+"&$top=1000",
function(data){
var count = data.d.results.length;
if(count > 0){
processResults(data); // do something with results
getNextBatch(totalSoFar+count, callback); // fetch next page
}else{
onCompleteCallback();
}
}
);
}
Pobierz identyfikator nowo utworzonego elementu z listy SharePoint
W tym przykładzie pokazano, jak pobrać identyfikator nowo utworzonego elementu za pomocą interfejsu API REST programu SharePoint.
Uwaga :
listName - ta zmienna zawiera nazwę twojej listy.
newItemBody - To będzie treść żądania dodania nowego elementu na liście.
np. var newItemBody = {__metadata: {'type': 'SP.Data.MyListNameItem'}, tytuł: „Some value title”};
function CreateListItemWithDetails(listName, newItemBody) {
var item = newItemBody;
return $.ajax({
url: _spPageContextInfo.siteAbsoluteUrl + "/_api/web/lists/getbytitle('" + listName + "')/items",
type: "POST",
contentType: "application/json;odata=verbose",
data: JSON.stringify(item),
headers: {
"Accept": "application/json;odata=verbose",
"X-RequestDigest": $("#__REQUESTDIGEST").val(),
"content-Type": "application/json;odata=verbose"
}
});
}
CreateListItemWithDetails(listName, newItemBody)
.then(function(data){
//success callback
var NewlyCreatedItemId = data.d.ID;
}, function(data){
//failure callback
});
Jak wykonywać operacje CRUD przy użyciu interfejsu REST programu SharePoint 2010
Stwórz
Aby wykonać operację Utwórz przez REST, musisz wykonać następujące czynności:
Utwórz żądanie HTTP za pomocą czasownika POST
. Użyj adresu URL usługi z listy, do której chcesz dodać encję jako cel dla testu POST. Ustaw typ zawartości na application/json
. Serializuj obiekty JSON reprezentujące nowe elementy listy jako ciąg i dodaj tę wartość do przykładu kodu JavaScript treści żądania:
function createListItem(webUrl,listName, itemProperties, success, failure) {
$.ajax({
url: webUrl + "/_vti_bin/listdata.svc/" + listName,
type: "POST",
processData: false,
contentType: "application/json;odata=verbose",
data: JSON.stringify(itemProperties),
headers: {
"Accept": "application/json;odata=verbose"
},
success: function (data) {
success(data.d);
},
error: function (data) {
failure(data.responseJSON.error);
}
});
}
Stosowanie
var taskProperties = {
'TaskName': 'Order Approval',
'AssignedToId': 12
};
createListItem('https://contoso.sharepoint.com/project/','Tasks',taskProperties,function(task){
console.log('Task' + task.TaskName + ' has been created');
},
function(error){
console.log(JSON.stringify(error));
}
);
Czytać
Aby wykonać operację odczytu przez REST, musisz wykonać następujące czynności:
Utwórz żądanie HTTP za pomocą czasownika GET
. Użyj adresu URL usługi elementu listy, do którego chcesz dodać encję jako obiekt docelowy GET. Ustaw typ zawartości na application/json
. Przykład JavaScript:
function getListItemById(webUrl,listName, itemId, success, failure) {
var url = webUrl + "/_vti_bin/listdata.svc/" + listName + "(" + itemId + ")";
$.ajax({
url: url,
method: "GET",
headers: { "Accept": "application/json; odata=verbose" },
success: function (data) {
success(data.d);
},
error: function (data) {
failure(data.responseJSON.error);
}
});
}
Stosowanie
getListItemById('https://contoso.sharepoint.com/project/','Tasks',2,function(taskItem){
console.log(taskItem.TaskName);
},
function(error){
console.log(JSON.stringify(error));
}
);
Aktualizacja
Aby zaktualizować istniejącą jednostkę, musisz wykonać następujące czynności:
Utwórz żądanie HTTP za pomocą czasownika POST
. Dodaj nagłówek X-HTTP-Method
o wartości MERGE
. Użyj adresu URL usługi elementu listy, który chcesz zaktualizować, jako celu dla testu POST. Dodaj nagłówek If-Match
o wartości oryginalnego ETag encji lub *. Przykład JavaScript:
function updateListItem(webUrl,listName,itemId,itemProperties,success, failure)
{
getListItemById(webUrl,listName,itemId,function(item){
$.ajax({
type: 'POST',
url: item.__metadata.uri,
contentType: 'application/json',
processData: false,
headers: {
"Accept": "application/json;odata=verbose",
"X-HTTP-Method": "MERGE",
"If-Match": item.__metadata.etag
},
data: Sys.Serialization.JavaScriptSerializer.serialize(itemProperties),
success: function (data) {
success(data);
},
error: function (data) {
failure(data);
}
});
},
function(error){
failure(error);
});
}
Stosowanie
var taskProperties = {
'TaskName': 'Approval',
'AssignedToId': 12
};
updateListItem('https://contoso.sharepoint.com/project/','Tasks',2,taskProperties,function(item){
console.log('Task has been updated');
},
function(error){
console.log(JSON.stringify(error));
}
);
Usunąć
Aby usunąć encję, musisz wykonać następujące czynności:
Utwórz żądanie HTTP za pomocą czasownika POST
. Dodaj nagłówek X-HTTP-Method
o wartości DELETE
. Użyj adresu URL usługi elementu listy, który chcesz zaktualizować, jako celu dla testu POST. Dodaj nagłówek If-Match
z wartością oryginalnego znacznika ET encji. Przykład JavaScript:
function deleteListItem(webUrl, listName, itemId, success, failure) {
getListItemById(webUrl,listName,itemId,function(item){
$.ajax({
url: item.__metadata.uri,
type: "POST",
headers: {
"Accept": "application/json;odata=verbose",
"X-Http-Method": "DELETE",
"If-Match": item.__metadata.etag
},
success: function (data) {
success();
},
error: function (data) {
failure(data.responseJSON.error);
}
});
},
function (error) {
failure(error);
});
}
Stosowanie
deleteListItem('https://contoso.sharepoint.com/project/','Tasks',3,function(){
console.log('Task has been deleted');
},
function(error){
console.log(JSON.stringify(error));
}
);