Podstawy REST API - Obsługa API platformy Shoper

Podstawy REST API - Obsługa API platformy Shoper

Jak szybko i w najprostszy sposób skorzystać z dobrodziejstw wystawionych przez REST? Pokażę jak niewiele linijek kodu potrzeba, aby postawić pierwszy krok w stronę automatyzacji obsługi Twojego sklepu. Python i jego świetna biblioteka Requests w akcji.

Wstęp

W tym poście postaram się, w miare zwięźle i bez zbędnych dygresji, zaprezentować jak odwoływać się do zasobów REST API platformy Shoper. Użyję do tego zadania biblioteki Requests. Z uwagi na to, że ma być zwięźle, nie będę omawiać biblioteki Requests, jak również koncepcji i zasad działania RESTowych serwisów. Jeżeli więc nie masz zielonego pojęcia o tym czym są POST, GET, Token, nic Ci nie mówi określenie REST, to może być ciężko (postaram się w niedalekiej przyszłości uzupełnić blog o wpisy wyjaśniające te zagadnienia). Teraz skupie się na totalnej praktyce i na tym jak zacząć przy minimum wiedzy i bez wysiłku (co nie oznacza, że jest to najlepszy sposób, powiem więcej, jest to sposób dla osób, które muszą coś zrobić na wczoraj albo wykonują bardzo proste skrypty dla SIEBIE).

Uzyskanie dostępu do zasobów (uwierzytelnienie klienta)

Shoper - panel administracyjny

Zacznijmy od stworzenia konta, z którego korzystać będzie nasz skrypt.

W menu wybieramy Konfiguracja > Administracja, system

Konfiguracja > Administracja, system

Wybieramy w prawym górnym rogu opcje Dodaj grupę administratorów, aby stworzyć nową grupę administratorów (np. nazywając ją admin).

Tworzenie grupy administratorów.

W momencie tworzenia grupy, musimy zdefiniować Typ dostępu. W naszym przypadku chcemy, aby konta z naszej grupy służyły do korzystania z WebAPI (REST). Wybieramy więc opcję Dostęp do WebApi i zatwierdzamy.

Tworzenie grupy administratorów.

W momencie utworzenia grupy, pojawią się po lewej stronie zakładki: Dane podstawowe, Uprawnienia oraz Administratorzy. W zakładce Uprawnienia ustalamy do jakich zasobów i w jakim zakresie admini z tej grupy będą mieli dostęp (odczyt, dodawanie, edycja itd.) - proponuję nie przesadzać, lepiej jest dodawać uprawnienia w miare potrzeb, bo jak powiadają

“WITH GREAT POWER THERE MUST ALSO COME–GREAT RESPONSIBILITY!”

Karta grupy administratorów.

Przechodzimy do zakładki Administratorzy i dodajemy nowe konto.

Formularz tworzenia administratora.

W każdym momencie możemy edytować naszą grupę administratorów, a co za tym idzie, również zmieniać ich uprawnienia (jeżeli udostępniłeś za mało - w ten sposób można je rozszerzyć). Na liście grup klikamy na nazwa grupy > Uprawnienia

Uprawnienia.

Kolejnych administratorów dodawać możemy wybierając przycisk Dodaj administratora w prawym górnym rogu listy grup, lub podczas edycji grupy, wchodząc w zakładkę Administratorzy

Tworzenie administratora.

Ok to na tyle co potrzebujemy z panelu administracyjnego, teraz czas na Python’a.

Skrypt

Importujemy bibliotekę Requests

import requests

Kolejnym krokiem będzie zainicjowanie sesji, która ułatwi nam robotę (będzie przechowywać parametry przekazywane razem z żądaniami, jak np. nagłówki, ciastka).

s = requests.Session()

Jesteśmy gotowi do uzyskania token’a (w uproszczeniu jest to kod przekazywany w nagłówku, aby serwis REST mógł nas rozpoznać i udzielić dostępu do zasobów). Token uzyskujemy odwołując się do zasobu /auth metodą POST, którą przekazujemy login i hasło do konta, stworzone wcześniej w panelu administracyjnym.

response = s.post('https://<url_naszego_sklepu>/webapi/rest/auth', auth=(<login>, <haslo>))

Jeżeli login, hasło i adres naszego sklepu są prawidłowe, powinniśmy otrzymać odpowiedź do zmiennej response. Odpowiedzi zwykle są opisane w składni JSON, ale metoda post() zwraca nam obiekt. Wypisując do konsoli response, otrzymamy jedynie status odpowiedzi.

>> print(response)
<Response [200]>

Aby dobrać się do odpowiedzi z tokenem, musimy podejrzeć co konkretnie zwrócił nam REST.

>> print(response.json())
{'access_token': 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', 'expires_in': 2592000, 'token_type': 'bearer'}

Metoda json() zwróci strukturę, z której w prosty sposób można wyłuskać access_token. Cała procedura będzie wyglądać tak:

response = s.post('https://<url_naszego_sklepu>/webapi/rest/auth', auth=(<login>, <haslo>))
result = response.json()
token = result['access_token']

Uzyskaliśmy access_token i przypisaliśmy go do zmiennej token. Wypada teraz go użyć. Jak pisałem wcześniej, access_token musimy przekazywać jako element nagłówka każdego żądania. Utworzona sesja pomoże nam się z tym uporać. Sesja będzie dla nas przechowywać nagłówki i automatycznie “doklejać” je do każdego żądania, które zostaną wywołane wewnątrz niej. Dodajmy więc token do sesji.

s.headers.update({'Authorization': 'Bearer %s' % token})

Od tej pory nasze żądania są uwierzytelnione, co oznacza, że możemy swobodnie korzystać z zasobów REST Api.

Przykładowe odwołanie się do zasobu

Do dyspozycji, mamy operacje CRUD. Wszystkie zasoby (opisane z przykładami) znajdziemy w Dokumentacja REST API Shoper. Pozostaje jedynie dobrać odpowiednie zasoby i umiejętnie je wykorzystać.

Na koniec mały przykład, jak uzyskać listę produktów w naszym sklepie:

response = s.get(URL + '/products')
print(response.json())

Warto zauważyć, że w odpowiedzi dostajemy tylko jedną ze stron, zawierającą określoną liczbę rekordów (kolekcje). Na tym zakończę ten post, ponieważ to, jak po kolei “przejść” po tych stronach (stronicowanie - czy jak coraz częściej się spotyka, paginacja), wymaga wiedzy jak dodawać do naszych żądań parametry, a o tym w następnej części o REST Api.

Paweł Chaniewski

Paweł Chaniewski
"Im mniej nużącej pracy manualnej tym lepiej, zwłaszcza kiedy musimy sami prowadzić sklep internetowy". Autor bloga cwsi.pl o tematyce automatyzacji w dziedzinie e-commerce. Entuzjasta języków skryptowych (szczególnie Python).

Google Apps Script - SOAP Client - Allegro WebAPI

Zaawansowane użycie Google Apps Script, czyli klient dla Web Service Allegro. Czytaj dalej