SPUG Meetup#01. SharePoint, REST, OData i JavaScript. Podsumowanie

19 kwietnia 2018 roku odbyło się pierwsze spotkanie SharePoint Power User Group. Grupa powstała dość spontanicznie i zanim przejdę do podsumowania tego spotkania, pozwól że wyjaśnię Ci skąd w ogóle pomysł na taki event.

Wstęp, czyli kto, gdzie i dlaczego…

Przez całe swoje zawodowe życie byłem i jestem związany z technologiami Microsoft. SharePoint zajmuje wśród nich swoje szczególne miejsce. Nigdy nie nazwałbym się programistą, ale posiadam pewne podstawy, które pozwalają poruszać się po technologiach związanych z developmentem. Ponieważ w obecnych czasach światy „Admin” i „Dev” zaczęły się mocno przenikać (głównie dzięki chmurom obliczeniowym), niezbędnym dla każdego administratora stała się znajomość przynajmniej podstawowych narzędzi i scenariuszy wykorzystania przeróżnych API systemów, którymi zarządzają. I tu dochodzimy do podstawowego powodu powstania tej grupy. Ma ona pomóc osobom rozpoczynającym przygodę z programowaniem w SharePoint, poznać najważniejsze funkcje i możliwości tej platformy. Jedynym skutecznym sposobem nauki jest praktyka, dlatego postanowiliśmy spotkania zorganizować w formie warsztatów. Na pierwszym pojawiło się 10 osób (z 12 zapisanych), a o tym co wspólnie robiliśmy przeczytasz w kolejnych akapitach.

Temat: REST, OData i JavaScript

Na pierwszy ogień postanowiliśmy zająć się dostępnym w SharePoint (2013, 2016, Online) REST API. Agenda wyglądała następująco:

To jedyny „slajd” jaki przygotowaliśmy na to spotkanie. Nie udało się zrealizować wszystkich punktów, ale też nie było to naszym celem.

Środowisko

Mam nadzieję, że spróbujesz przerobić wszystkie przykłady z naszego spotkania. Wystarczy Ci dostęp do dowolnej wersji SharePoint (Foundation, Standard, Enterprise, 2013, 2016, Online). Wszystkie ćwiczenia i aplikacje użyte na tym Meetupie są autorstwa Mateusza Malickiego (dzięki Mateusz!). Na spotkaniu pracowaliśmy z SharePoint Online. Zrzuty ekranu pochodzą z przeglądarki Chrome, ale możesz korzystać z dowolnej innej. Na początek proponuję ściągnąć paczkę z plikami skryptów. Ściągnij ją, rozpakuj, a zawartość umieść w dowolnej bibliotece na swojej witrynie. Za chwilę opiszę dalej z nimi zrobić.

Przeglądarka, SharePoint i REST API

Zanim zaczniesz pierwsze eksperymenty z REST API w SharePoint, warto rzucić okiem na dokumentację. Nie musisz czytać jej od deski do deski. Za chwilę przerobimy kilka prostych przykładów, które wprowadzą Cię w temat. Jednak w wielu przypadkach, będzie ona niezbędna.

Podstawową cechą REST API jest wykorzystanie HTTP. Nie potrzebujesz zatem skomplikowanych narzędzi do jego wykorzystania. Wystarczy przeglądarka. Na początek prosty przykład:

Do adresu URL swojej witryny dopisz po prostu /_api/web, a w wyniku dostaniesz wszystkie informacje o niej w formacie JSON.

Całe REST API ma hierarchiczną budowę. Przypomina ona hierarchię podstawowych obiektów w SharePoint. Jeśli chcesz zobaczyć tytuł witryny wystarczy dopisać kolejny segment w adresie URL:

Z gąszcza przeróżnych atrybutów i właściwości możesz wyłuskać dokładnie te, których potrzebujesz. Służy do tego polecenie $Select:

Przeglądarka pozwoli Ci zrobić wszystko, ale na dłuższą metę nie jest najwygodniejszym narzędziem do tworzenia tego typu request’ów. Dlatego przygotowaliśmy małe narzędzie, które pozwoli Ci je tworzyć w zdecydowanie wygodniejszej formie.

Aplikacja do obsługi request’ów

Pliki, które przegrałeś wcześniej na swoją witrynę, to kompletna aplikacja. Nie jest duża i skomplikowana. Jeśli znasz podstawy składni JavaScript, to bez trudu przeanalizujesz jej kod. Oczywiście nie musisz tego robić. Wystarczy, że skopiujesz zawartość pliku requestScriptEditor.txt wcześniej zmieniając ścieżki do plików:

<script type=”application/javascript” src=”/sites/meetup/UserXY/YOURLIBRARY/app.js„></script>

<script type=”application/javascript” src=”/sites/meetup/UserXY/YOURLIBRARY/request.js„></script>

<link rel=”stylesheet” href=”/sites/meetup/UserXY/YOURLIBRARY/app.css„>

<div id=”request”></div>

<script type=”application/javascript”>

window.addEventListener(„load”, function(event) {

var app = new window.infowave_todo.requestApp(’#request’);

app.start();

});

</script>

Tak skopiowany kod wklej do webparta Edytor skryptów / Script Editor. Możesz go umieścić na dowolnej stronie. Nie ma to większego znaczenia.

SharePoint i REST API. Reszta przykładów

Po uruchomieniu aplikacji możesz zacząć właściwe testy. Aplikacja pozwoli Ci w prosty sposób napisać i sparametryzować request oraz przeanalizować odpowiedź serwera. Zacznijmy od przykładu, który już przerabialiśmy:

Zwróć uwagę polecenie GET (pozwala na wygenerowanie prośby o dane) oraz zdecydowanie przystępniej przedstawione wyniki. Status 200 OK oznacza prawidłową odpowiedź. To ciągle ten sam przykład, od którego zaczęliśmy, ale możemy go teraz rozłożyć na części pierwsze. Idziemy dalej. Dodajmy parametry i wyciągnijmy określone właściwości witryny:

Spróbujmy z listami (…/lists):

Mając prosty interfejs do dodawania parametrów, spróbujmy z innymi. Tym razem $filter, który posłuży nam do znalezienia wszystkich ukrytych list. Zwróć uwagę na składnię filtra.

Często przydaje się pobieranie danych paczkami (paginacja). Parametry $top oraz $skip pozwalają dokładnie na to. W przykładnie poniżej pobieramy tytuły pięciu kolejnych list, ignorując trzy pierwsze. Inaczej mówiąc pobieramy pozycje od 4 do 9. Pamiętaj, że w przypadku elementów na listach, paginacja działa inaczej, ale o tym za chwilę.

Jeśli zależy Ci na odpowiednim posortowaniu wyników, możesz to zrobić wykorzystując parametr $orderby. Standardowy wyniki są zwracane w kolejności rosnącej. Jeśli chcesz odwrotną kolejność, wystarczy dodać słowo kluczowe desc po nazwie właściwości (w przykładzie są to tytuły list):

Dane zwracane przez SharePoint są formatowane do uproszczonego formatu JSON. Jeśli chcesz zobaczyć pełną odpowiedź serwera można to zrobić dodając odpowiednią wartość w nagłówku HTTP (Accept application/json;odata=verbose):

Z pomocą REST API możemy pobrać także dane o aktualnym użytkowniku oraz inne parametry jego kontekstu pracy:

Niezmiernie często pracujemy z listami. Właściwości konkretnej pozwoli podejrzeć następujące polecenie (…/lists/getbytitle(„tytuł listy”)):

W listach najważniejsze jest ich zawartość. Wiedząc już jak dostać się do konkretnej listy, wystarczy dopisać kolejny segment do adresu (/Items), aby uzyskać listę jej elementów:

Listy mogą zawierać wiele elementów. Na pobranie konkretnej paczki danych pozwala używany już przez nas parametr $top:

W przypadku elementów listy nie możemy skorzystać z parametru $skip. Zamiast niego SharePoint zwraca nam specjalny skiptoken. SharePoint wygeneruje nawet gotowy request pozwalający na pobranie kolejnej paczki danych (odata.nextLink):

Skipitem możemy podać jako kolejny parametr. To przydatna funkcja jeśli zamierzasz pracować z zawartością list.

Pobieranie danych to tylko jeden ze scenariuszy. REST API w SharePoint pozwoli Ci także na tworzenie, modyfikowanie i kasowanie obiektów. Zacznijmy od utworzenia nowej listy. Tym razem musimy przekazać kilka parametrów listy. Podajemy je polu Body. W przykładzie tworzymy nową listę na podstawie szablonu Lista niestandardowa / Custom list i nazywamy ją „Meetup todo”. Szablon listy podajemy korzystając z trzycyfrowych kodów. 100 oznacza listę niestandardową. Uwaga na rozmiar liter oraz nowe polecenie POST zamiast GET:

Po utworzeniu warto sprawdzić kolumny naszej listy.

Kolejnym krokiem będzie utworzenie nowych kolumn. Lista ma przechowywać zadania do wykonania. Dodajemy na początek kolumnę z datą. Nazwiemy ją Due Date. Zwróć uwagę na pole FieldTypeKind. Tutaj znowu pojawia się „magiczny” liczbowy parametr. Tym razem inna wartość oznacza inny rodzaj pola. Wartość 4 to pole typu data godzina. Zwróć uwagę na wewnętrzną nazwę pola. Za chwilę będziemy jej potrzebować:

Wartość 8 to pole typu flaga (checkbox):

Sprawdź czy Twoja lista działa i wygląda poprawnie. Powinno to wyglądać mniej więcej tak:

Mając gotowy schemat list, aż prosi się, aby dodać do niej nowy element. Tutaj przyda się znajomość wewnętrznych nazw kolumn. To nimi musimy się posługiwać generując kolejny request. Datę musimy podawać dokładnie w takim formacie jak na zrzucie.

Mamy już listę, kolumny i nowy element. Spróbujmy zmienić jeden z elementów. W tym celu użyć musimy innego polecenia (PATCH). Ponieważ edytujemy konkretny elementy listy, musimy jego identyfikator podać w request (…/items(2)). W polu Body wpisujemy nową wartość konkretnego pola/pól. Wydawałoby się, że to wystarczy, ale okazuje się, że SharePoint nie przyjmie takiego polecenia:

Powodem jest tzw. mechanizm concurency control, który w przypadku SharePoint wymusza na nas podanie dodatkowego parametru etag. Samo zabezpieczenie zapewnia, że zmieniamy dokładnie ten element i dokładnie w takim kształcie, jaki zamierzaliśmy. Co ciekawe serwer dokładnie podaje nam jaką wartość powinniśmy przekazać (w tym przypadku 1). Tę podajemy w parametrze if-match:

Wynik edycji możesz sprawdzić bezpośrednio na liście. Pozostało nam jeszcze skasowanie elementu. Zanim to zrobimy warto sprawdzić ile elementów nasza lista posiada:

Samo skasowanie odbywa się na podobnych zasadach jak edycja. Musimy podać identyfikator elementu, który chcemy usunąć oraz odpowiednią wartość etag:

Podsumowanie

W ten sposób dotarliśmy do ostatniego przykładu. Mam nadzieję, że wiesz już jakie możliwości daje REST API w SharePoint. Oczywiście prześlizgnęliśmy się tylko po powierzchni tego tematu, ale powinieneś już umieć wykonać przy jego użyciu kilka podstawowych operacji. Następnym razem zamiast Powershell możesz użyć REST do automatyzacji pewnych zadań. Będzie to wymagało „ubrania” requestów w najprostszy nawet interfejs (np. przycisk na stronie), ale tym zajmiemy się na kolejnym meetupie. Wstępnie planujemy go na drugą połowę maja 2018. Zachęcam Cię do śledzenia kalendarza wydarzeń na stronie i rezerwację miejsc. Tak jak poprzednio, ich liczba będzie ograniczona.

Jeśli masz jakiekolwiek pytania, to zostaw je w komentarzach. Z chęcią na nie odpowiemy. Tymczasem pozdrawiam i do zobaczenia na kolejnym meetupie!