sharepoint
Services REST
Recherche…
Remarques
URL du noeud final du service REST
L'API d'accès au client REST a été introduite pour la première fois dans SharePoint 2010, mais elle a été considérablement étendue dans SharePoint 2013. L'API REST dans SharePoint 2010 est accessible via le service Web ListData à l'URL /_vti_bin/ListData.svc
. SharePoint 2013 a introduit les URL de point de terminaison /_api/lists/
et /_api/web
, qui se comportent légèrement différemment.
Les URL de noeud final ci-dessus doivent être précédées de http://server/site
où server
représente le nom du serveur et site
représente le nom ou le chemin d'accès du site spécifique.
Exemple d'URL pour ... | SharePoint 2010 | SharePoint 2013 |
---|---|---|
Récupérer une liste: | /_vti_bin/ListData.svc/ListName | /_api/lists('ListGuid') |
Récupérer un article: | /_vti_bin/ListData.svc/ListName(1) | /_api/lists('ListGuid')/items(1) |
Récupérer un site Web: | (pas d'équivalent) | /_api/web |
Malgré les différences d'accès aux listes et aux éléments de liste, l'utilisation de ces résultats est très similaire dans les deux versions.
Notez que le service ListData.svc
est toujours disponible dans SharePoint 2013 pour la compatibilité ascendante.
Envoi de demandes REST
Une demande REST peut être soumise via un XMLHttpRequest JavaScript natif ou via la construction d'encapsulation jQuery AJAX.
Syntaxe XMLHttpRequest
var xhr = new XMLHttpRequest();
xhr.open(verb, url, true);
xhr.setRequestHeader("Content-Type","application/json");
xhr.send(data);
jQuery AJAX Syntaxe
$.ajax({
method: verb,
url: url,
headers: { "Content-Type":"application/json" },
data: data
});
Pour plus de détails sur l'envoi de requêtes via AJAX, consultez la documentation JavaScript AJAX .
Travailler avec des listes
Obtention d'éléments de la liste
Cet exemple montre comment récupérer tous les éléments de la liste et les parcourir. Vous pouvez utiliser le paramètre top
pour demander un certain nombre de résultats. Vous pouvez également utiliser le paramètre select
pour sélectionner certains champs ( $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);
}
});
}
Obtenir un élément de liste individuel
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);
}
});
}
Obtention d'éléments de liste avec des colonnes de recherche
Parfois, vous pouvez avoir une structure de liste qui ressemble à ceci:
Tableau de liste d'animaux
prénom | Type | La description |
---|---|---|
Titre | Chaîne (texte) | Nom de l'animal |
Âge | Nombre | Quel âge a l'animal |
Valeur | Devise | Valeur de l'animal |
Type | Recherche (tableau des types d'animaux) | Champ de recherche (Donne la liste déroulante des choix de la Table des types d'animaux) |
Tableau des types d'animaux
prénom | Type | La description |
---|---|---|
Titre | Chaîne (texte) | Nom de l'espèce / du type d'animal (ex. Porc) |
NumLegs | Nombre | Nombre de pattes sur l'animal |
Probablement pas l'exemple le plus grave mais le problème est toujours valable. Lorsque vous utilisez la requête habituelle pour extraire des valeurs de la liste SharePoint, pour le Type
de l'animal, vous ne récupérez qu'un champ appelé TypeId
dans la réponse JSON. Afin d'élargir ces éléments en un seul appel AJAX, un balisage supplémentaire est requis dans les paramètres de l'URL.
Cet exemple s'applique à plus que des colonnes de recherche. Lorsque vous utilisez des colonnes de People/Groups
, ce ne sont que des recherches, vous pouvez donc facilement extraire des éléments tels que Title
, EMail
et autres.
Exemple de code
Remarque importante : Lorsque vous définissez les champs que vous souhaitez récupérer à partir des colonnes de recherche, vous devez préfixer le nom du champ avec le nom du champ de recherche dans la table d'origine. Par exemple, si vous souhaitez récupérer l'attribut NumLegs
dans la colonne de recherche, vous devez taper 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();
Ajout de sélections à un champ de recherche à valeurs multiples
Cet exemple suppose que votre colonne de recherche s'appelle MultiLookupColumnName
et que vous souhaitez définir votre champ de recherche multiple pour rechercher les éléments dont les ID 1 et 2.
Utiliser 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
});
Utiliser 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);
Éléments de liste de pagination renvoyés par une requête
Pour simuler la pagination à l'aide de REST, vous pouvez effectuer les opérations suivantes:
Utilisez le paramètre
$skip=n
pour ignorer lesn
premières entrées en fonction du paramètre$orderby
Utilisez le paramètre
$top=n
pour renvoyer lesn
premières entrées en fonction des$orderby
et$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();
}
}
);
}
Récupérer un identifiant d'élément nouvellement créé dans la liste SharePoint
Cet exemple montre comment extraire un ID d'un élément nouvellement créé à l'aide de l'API REST SharePoint.
Remarque :
listName - Cette variable contient le nom de votre liste.
newItemBody - Ce sera votre corps de requête pour ajouter un nouvel élément dans la liste.
par exemple var newItemBody = {__metadata: {'type': 'SP.Data.MyListNameItem'}, Titre: 'Some title value'};
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
});
Comment effectuer des opérations CRUD à l'aide de l'interface REST SharePoint 2010
Créer
Pour effectuer une opération de création via REST, vous devez effectuer les actions suivantes:
Créez une requête HTTP en utilisant le verbe POST
. Utilisez l'URL de service de la liste à laquelle vous souhaitez ajouter une entité en tant que cible pour le POST. Définissez le type de contenu sur application/json
. Sérialisez les objets JSON qui représentent vos nouveaux éléments de liste en tant que chaîne et ajoutez cette valeur à l'exemple JavaScript du corps de la requête:
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);
}
});
}
Usage
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));
}
);
Lis
Pour effectuer une opération de lecture via REST, vous devez effectuer les actions suivantes:
Créez une requête HTTP en utilisant le verbe GET
. Utilisez l'URL de service de l'élément de liste auquel vous souhaitez ajouter une entité en tant que cible pour le GET. Définissez le type de contenu sur application/json
. Exemple 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);
}
});
}
Usage
getListItemById('https://contoso.sharepoint.com/project/','Tasks',2,function(taskItem){
console.log(taskItem.TaskName);
},
function(error){
console.log(JSON.stringify(error));
}
);
Mettre à jour
Pour mettre à jour une entité existante, vous devez effectuer les actions suivantes:
Créez une requête HTTP en utilisant le verbe POST
. Ajoutez un X-HTTP-Method
tête X-HTTP-Method
avec une valeur de MERGE
. Utilisez l'URL de service de l'élément de liste que vous souhaitez mettre à jour en tant que cible pour le POST Ajoutez un en If-Match
tête If-Match
avec une valeur de l'ETag d'origine de l'entité, ou *. Exemple 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);
});
}
Usage
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));
}
);
Effacer
Pour supprimer une entité, vous devez effectuer les actions suivantes:
Créez une requête HTTP en utilisant le verbe POST
. Ajoutez un X-HTTP-Method
tête X-HTTP-Method
avec une valeur DELETE
. Utilisez l'URL de service de l'élément de liste que vous souhaitez mettre à jour en tant que cible pour le POST Ajoutez un en If-Match
tête If-Match
avec une valeur de l'ETag d'origine de l'entité. Exemple 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);
});
}
Usage
deleteListItem('https://contoso.sharepoint.com/project/','Tasks',3,function(){
console.log('Task has been deleted');
},
function(error){
console.log(JSON.stringify(error));
}
);