Przekazywanie załączników do Google Drive za pomocą akcji REST

Facebooktwitterpinterestlinkedinmail
Dotyczy wersji 2020.1.3.x autor: Tomasz Pytlak

 

Wstęp

Jedną z podstawowych funkcjonalności WEBCON BPS jest praca z załącznikami. Niektóre procesy, jak na przykład Repozytorium Dokumentów, mogą istnieć wyłącznie w celu skatalogowania i udostępnienia plików wybranym użytkownikom. W innych, załączniki mogą mieć drugorzędne znaczenie. Niezależnie od tego pozostają one jednym z centralnych elementów każdego systemu BPS.

Warto jednak zastanowić się nad przypadkiem, gdy chcemy wspólnie z klientem pracować nad plikiem, jednocześnie nie udostępniając systemu zewnętrznym użytkownikom. Przesyłanie pliku poprzez email może doprowadzić do sytuacji, w której mamy kilka wersji tego samego dokumentu i żadnej ze scalonymi zmianami. W takim przypadku warto rozważyć integrację BPS z usługami przechowywania plików jak OneDrive, czy opisany w niniejszym artykule Google Drive.

 

Przygotowanie Google API

Przygotowanie procesu należy rozpocząć od konfiguracji po stronie Google API zgodnie z dokumentacją dostępną pod adresem https://developers.google.com/drive/api/v3/about-sdk.

Poniżej opisano najprostszy schemat postępowania, pozwalający na integrację z Google Drive.

Pierwszym krokiem jest przejście na stronę https://console.developers.google.com/, zalogowanie się za pomocą konta Google i wybranie projektu z listy lub utworzenie nowego.

Rys. 1 Wybór projektu Google

 

Następnie w zakładce „Library” należy wyszukać i aktywować „Google Drive API”. Jest to rozszerzenie pozwalające na komunikację klienta z zasobami Google Drive.

Rysunek 2 Wybór API

 

W następnej kolejności w zakładce „OAuth consent screen”  należy wybrać jaki typ użytkowników będzie miał dostęp do API.

Rys. 3 Wybór typu użytkowników

 

Potwierdzenie wyboru przyciskiem CREATE otwiera nowe okno, w którym należy nazwać aplikację.

Opcjonalnie można m.in. dodać logo, wskazać autoryzowane domeny lub ustawić maila kontaktowego dla użytkowników.

Rys. 4 Konfiguracja aplikacji

 

Na końcu należy przejść do trzeciej zakładki „Credentials” i za pomocą przycisku CREATE CREADENTIALS stworzyć nowego klienta OAuth, co umożliwi przeprowadzenie procesu autentykacji.

Rys. 5 Dodanie klienta OAuth

 

W konfiguracji wystarczy określić typ aplikacji oraz podać jej nazwę.

Rys. 6 Konfiguracja klienta OAuth

 

Po utworzeniu Klienta warto wejść do jego konfiguracji poprzez kliknięcie na nazwę i zwrócić uwagę na Client ID oraz Client secret, ponieważ będą to parametry potrzebne do uzyskania tokena.

Rys. 7 Parametry klienta OAuth

 

Utworzenie tokenów

W celu utworzenia refresh tokena należy wykonać dwa wywołania. W związku z tym, że jest to operacja jednorazowa, nie warto jej utrwalać w postaci procesu. Procedura jest opisana pod adresem https://developers.google.com/identity/protocols/oauth2/native-app#loopback-ip-address.

Pierwsze wywołanie służy uzyskaniu kodu autoryzacyjnego. Najwygodniej wykonać je w kontekście przeglądarki, ponieważ konieczne jest zalogowanie do konta Google. W poniższym wywołaniu należy podmienić {ClientID} na właściwe Client ID opisane w poprzednim rozdziale.

https://accounts.google.com/o/oauth2/v2/auth?scope=https://www.googleapis.com/auth/drive&response_type=code&state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&redirect_uri=http://127.0.0.1:80&client_id={ClientID}

Ze względu na politykę bezpieczeństwa, wyświetlone zostanie ostrzeżenie o niezweryfikowanej aplikacji. Jej weryfikacja jest możliwa, ale wymaga kontaktu z Google i nie jest istotna dla treści artykułu. Wystarczy rozwinąć zakładkę „Advanced” i zaakceptować ryzyko, a następnie dwukrotnie zatwierdzić dostęp.

Rys. 8 Okno potwierdzenia dostępu

 

W odpowiedzi, w adresie URL wyświetlony zostanie parametr code, który należy zapisać i wkleić do kolejnego wywołania. Trzeba pamiętać, że posiada on określoną ważność.

Ewentualne pojawienie się błędu 404 związane jest z brakiem aplikacji hostowanej pod wskazanym jako redirect_url adresem. Parametry w adresie URL powinny być dostępne nawet w takim przypadku.

Drugie wywołanie ma na celu zamianę uzyskanego kodu na token. Ponieważ jest to wywołanie typu POST, najlepiej wykonać je przy pomocy dedykowanego oprogramowania jak np. Postman.

W tym celu należy wybrać typ POST, wskazać endpoint https://oauth2.googleapis.com/token oraz w zakładce Body uzupełnić pięć parametrów:

  • Code – wartość uzyskana z poprzedniego wywołania
  • Client_id – ID klienta analogicznie jak w poprzednim wywołaniu
  • Client_secrets – wartość dostępna jest w parametrach klienta pod Client ID.
  • Redirect_url – serwer, który otrzyma odpowiedź (w tym przypadku lokalny)
  • Grant_type – wartość “authorization_code”

Rys. 9. Wymiana kodu na token w Postman – wywołanie

 

Podczas kopiowania wartości warto zwrócić uwagę, czy na końcu parametru nie wkleił się biały znak.

W odpowiedzi Google Drive API przesyła pięć wartości, z których najważniejszą dla opisanego poniżej obiegu jest refresh_token, który pozwoli na cykliczne odświeżanie tokena dostępu.

Rys. 10. Wymiana kodu na token w Postman – odpowiedź

 

Utrzymanie access tokena

Ponieważ token dostępu ważny jest jedynie przez godzinę, a dodatkowo trzeba udostępnić go na potrzeby systemu, najlepiej stworzyć obieg techniczny.

Jego zadaniem będzie przechowywanie access tokena oraz cykliczne odnawianie go z wykorzystaniem wywołania realizowanego za pomocą standardowej akcji „Wywołaj REST Web service”

Może składać się on z trzech kroków i w założeniu posiadać tylko jedną aktywną instancję.

Rys. 11 Schemat przykładowe obiegu technicznego utrzymującego token

 

Podczas rejestracji instancji, na formularzu należy uzupełnić parametry wywołania.

Dwa pierwsze parametry ponownie można znaleźć w konfiguracji klienta, trzeci przyjmuje stałą wartość „grant_type”, a czwarty to refresh_token uzyskany w poprzednim wywołaniu.

Rys. 12. Obieg techniczny podczas rejestracji

 

Na wejście do kroku Active dodano akcję „Refresh Token” typu „Wywołaj REST Web service”.

Autentykację ustawiono jako „Niestandardową” i wskazano endpoint żądania.

Rys. 13. Refresh token – zakładka Authentication

 

W drugiej zakładce zmieniono jedynie typ wywołania na POST.

Rys. 14. Refresh token – zakładka Request data

 

Parametry wywołania zostały wpisane w trzeciej zakładce.

Rys. 15. Refresh token – zakłądka Request body

 

Natomiast w czwartej określono mapowanie uzyskanego tokenu dostępu do pola na formularzu.

Rys. 16. Refresh token – zakładka Response

 

Dodatkowo na kroku dodano Timeout, który co 50 minut wykona automatyczne wywołanie w celu odnowienia tokenu.

Rys. 17. Timeout Refresh

 

Po przejściu ścieżką rejestracji na formularzu, pobrany zostanie pierwszy access token, a system automatycznie będzie go odnawiał w zadanym interwale czasu.

Rys. 17 Obieg techniczny po uzyskaniu access tokena

 

Należy zwrócić szczególną uwagę, na to, kto posiada dostęp do obiegu, ponieważ przechowuje on dane pozwalające na autentykację do Google Drive również spoza systemu BPS.

 

Publikacja pliku

Można wyobrazić sobie różne scenariusze, w których chcemy umieścić plik na Google Drive. W niniejszym przykładzie, rejestracja Umowy oznacza przesłanie ostatniego dodanego do formularza załącznika na dysk Google. W tym celu na ścieżce przejścia „Register” umieszczono akcję typu „Wywołaj REST Web service”, którą nazwano „Send file”.

W pierwszej zakładce konfiguracji po raz kolejny skorzystano z autentykacji anonimowej i wskazano odpowiedni endpoint – https://www.googleapis.com/upload/drive/v3/files.

Rys. 19. Send file – Zakładka Authentication

 

W drugiej zakładce zmieniono typ metody na POST oraz podano dwa parametry:

Authorization – token dostępu pobierany za pomocą reguły biznesowej z obiegu technicznego

uploadType – multipart, będący jednym z 3 dostępnych typów transferu obok „ media” oraz „resumable”. Metoda ta jest zalecana dla plików do 5MB wielkości. Więcej informacji na ich temat można znaleźć pod adresem  https://developers.google.com/drive/api/v3/manage-uploads.

Rys.20. Send file – Zakładka Request data

 

Reguła biznesowa „Att: Authorization” zapisana jest w postaci SQL COMMAND i składa się ze stałej części ‘Bearer’ oraz tokena dostępu.

Rys. 21. Reguła Att: Authorization

 

Trzecia zakładka zawiera w tym przypadku w większości dane dotyczące samego pliku:

  • Body type – dla tego przypadku ponownie Multipart, co umożliwia przesłanie zarówno metadanych jak i danych binarnych w obrębie jednego requesta
  • JSON part headers – stały nagłówek “Content-Type:application/json”
  • JSON part value – metadane zawierające w parametrze „name” nazwę pliku
  • Binary part header – zawiera parametr „Content-Type” z informacją o rodzaju pliku
  • Binary part value – zawiera dane binarne do wysłania. Pole wspiera trzy tryby:
    • przekazanie ID załącznika znajdującego się w bazie WEBCON BPS
    • przekazanie danych w formacie Data URL, który umożliwia przesłanie np. zawartości atrybutu typu obrazek
    • dowolna zawartość tekstowa inna niż w powyższych punktach

W poniższym przypadku skorzystano z pierwszej metody.

Rys. 22 Request data – Zakładka Request body

 

Na powyższym zrzucie można zauważyć trzy reguły biznesowe. Reguła „Att: ID” stanowi podstawę dla pozostałych. Zawiera w sobie zapytanie SQL wyszukujące ID ostatniego załącznika dodanego do bieżącej instancji.

Rys. 23 Reguła Att: ID

 

Reguły „Att: Name” oraz „Att: Content type” bazują na “Att: ID” i nowych, predefiniowanych funkcjach zwracając odpowiednio nazwę załącznika i jego typ.

Rys. 24. Reguła Att: Name

 

Rys. 25. Reguła Att: Content type

 

W celu przetestowania tak skonfigurowanego obiegu wystarczy dodać załącznik i przejść ścieżką rejestracji.

Rys. 26. Załącznik na formularzu

 

Plik zostanie umieszczony na Google Drive.

Rys. 27 Załącznik dodany do Google Drive

Podsumowanie

Standardowa akcja dostępna w WEBCON BPS dostarcza możliwości integracji z wieloma zewnętrznymi dostawcami oprogramowania. W przypadku Google Drive można z niej skorzystać do przesyłania plików ale również wykonywania innych operacji jak utrzymywanie aktywnego tokena dostępu.

Dodaj komentarz

Twój adres email nie zostanie opublikowany. Pola, których wypełnienie jest wymagane, są oznaczone symbolem *