Allegro.pl REST API w Pythonie - wprowadzenie (OAuth)
Wpis o tym jak zacząć korzystać z REST API serwisu Allegro.pl w skryptach pisanych w Pythonie. Postaram się wyjaśnić niezbędne minimum, do tego by zacząć od razu korzystać z API.
Jeżeli czytałeś poprzedni wpis Podstawy REST API - Obsługa API platformy Shoper to prawdopodobnie kilka razy będziesz miał wrażenie deja vu, ale nic dziwnego, skoro znowu omawiamy serwis o architekturze REST. Standardowo, nie będę tłumaczył zasad działania tego typu serwisu, ani nie będę wnikał w poszczególne metody HTTP do jego obsługi. Zainteresowanych teorią odsyłam do Oficjalnej Dokumentacji, gdzie jest to całkiem nieźle wyjaśnione.
Wstęp
Na początek, musimy wykonać pewne czynności aby uzyskać dostęp do REST API, czyli zarejestrować naszą aplikację (lub skrypt jak kto woli), uzyskując przy tym dane dostępowe do REST API potrzebne do uzyskania token.
Istotna uwaga:
Na chwilę obecną nie możemy “odwiązać” aplikacji, inaczej mówiąc, raz podwiązana aplikacja do konta - zawsze będzie miała dostęp do API. Tak samo z wygenerowanymi danymi dostępowymi - nie można ich zdjąć czy odwołać dostępu za ich pomocą - dlatego lepiej jest nie umieszczać ich w kodzie źródłowym programu czy chwalić się nimi.
Pełna instrukcja jak działa rejestracja aplikacji oraz cała procedura opisana została w Oficjalnej Dokumentacji - Rejestracja Aplikacji.
Dla osób z tekstowstrętem, cały proces w obrazkach.
Uzyskanie tokena (uwierzytelnienie aplikacji)
Będziemy brali udział w zabawie zwanej OAuth 2.0 - polega ona na wykonaniu kilku czynności, aby udzielić naszej aplikacji uprawnień do wykonywania operacji w imieniu naszego konta na allegro. Po kolei:
- Rejestrujemy naszą aplikację (to już za nami) i uzyskanie danych dostępowych
- Wysyłamy żądanie do odpowiedniego endpointa przekazując dane dostępowe oraz tzw. redirect uri (o nim za chwilę)
- W tym momencie w graficznym interfejsie (zwykle dzięki otwarciu się przeglądarki) zostaniemy przekierowani do formularza logowania do naszego konta na Allegro.pl
- Wyrażamy zgodę na powiązanie aplikacji z naszym kontem na Allegro.pl
- Teraz, na adres podany w redirect_uri zostanie wysłany kod autoryzacyjny (jest on jednorazowy i ważny 10 sekund!)
- Wysyłamy kolejne żądanie na odpowiedni adres, w którego ciele przekazujemy odpowiednią zawartość, w tym wcześniej uzyskany kod autoryzacyjny.
- Zwrócona odpowiedź (w formie JSON) powinna zawierać nasz token - czyli ciąg znaków używany do uwierzytelniania naszych poczynań przez REST API.
Jest trochę tego, więc od razu zaczynamy implementację - kod omówiony w komentarzach.
W czasie działania tej funkcji, powinna otworzyć się nam przeglądarka z formularzem logowania do serwisu Allegro.pl, logujemy się, następnie wyświetli się komunikat z zapytaniem, czy wyrażamy zgodę na powiązanie aplikacji która o to prosi - zgadzamy się. (pkt. 3-4)
Wynikiem tej operacji powinno być uzyskanie kodu autoryzacyjnego (pkt. 5)
>> access_code = get_access_code('<client_id>', '<api_key>')
server_address: ('localhost', 8000)
Waiting for response with access_code from Allegro.pl (user authorization in progress)...
127.0.0.1 - - [30/Mar/2018 12:42:06] "GET /?code=xxxxxxxxxxxxxxxxxxxxx HTTP/1.1" 200 -
Got an authorize code: xxxxxxxxxxxxxxxxxxxxx
W ciągu 10 sekund musimy przekazać access_code
w żądaniu typu POST na adres HTTP https://allegro.pl/auth/oauth/token
z odpowiednim nagłówkiem zawierającym client_id
oraz client_secret
(oba otrzymaliśmy przy rejestracji naszej aplikacji) w formie zakodowanej Base64. (pkt. 6)
I na koniec otrzymujemy odpowiedź w formie JSON, który zawiera access_token
oraz refresh_token
. Możemy zapisać oba (byle w bezpieczny sposób!) w pliku, bazie, na kartce nie polecam - i korzystać już bezpośrednio z nich nie powtarzając całego procesu.
Czas ważności access_token
określony jest w expires_in
(w sekundach - będzie to 12 godzin), po tym czasie należy wykorzystać refresh_token
aby uzyskać nowy zestaw zawierający nowy access_token
(oraz nowy refresh_token
), który to znowu ważny jest następne 12 godzin. Można tak przedłużać przez następne 365 dni, po tym czasie będziemy musieli znowu zalogować się do allegro przez formularz (czyli powtórzyć cały proces opisany wyżej).
>> print(sign_in('<client_id>', '<client_secret>', access_code, '<api_key>'))
{'access_token': 'xxxxxx',
'token_type': 'bearer',
'refresh_token': 'xxxxxxxxxx',
'expires_in': 43199,
'scope': 'allegro_api',
'jti': 'xxxx-xxxx-xxxx-xxxx-xxx'}
Przedłużanie ważności tokena
Kiedy minie 12 godzin od uzyskania access_token
, staje się on nieważny i nie możemy z jego pomocą uwierzytelnić naszej aplikacji. Należy skorzystać z refresh_token
do jego odświeżenia.
Przykładowe wywołanie
>> print(refresh_token('<client_id>', '<client_secret>', '<refresh_token>', '<api_key>'))
{'access_token': 'xxxxxx',
'token_type': 'bearer',
'refresh_token': 'xxxxxxxxxx',
'expires_in': 43199,
'scope': 'allegro_api',
'jti': 'xxxx-xxxx-xxxx-xxxx-xxx'}
I tak w koło przez kolejne 365 dni.
Korzystanie z zasobów REST API
Nie chcę dodawać zbyt wiele do i tak już obszernego wpisu, dlatego pokażę jedynie działający koncept jak można wykorzystać uzyskany access_token
do uwierzytelnienia żądań wysyłanych do API. Chcę poświęcić zagadnieniu żądań HTTP (POST, GET, PUT itd.) osobny wpis. W przedstawionym przykładzie uzyskujemy ID karty gwarancji, zdefiniowanej w ustawieniach sprzedaży (jest to element wymagany do wystawienia aukcji z nowym opisem). Odwołując się do zasobu /after-sales-service-conditions/warranties
musimy przekazać metodą GET również parametr sellerId
.
Wyjaśnię tylko czym jest sellerId
- jest to identyfikator naszego konta, można go uzyskać przez WebAPI, ale łatwiej jest po prostu wejść w Moja karta użytkownika, odnośnik do niej (URL) zawiera właśnie nasze sellerId
https://allegro.pl/uzytkownik/<seller_Id>/oceny