[API][Google] Wstęp do Google API

Google udostępnia API do większości swoich usług, takich jak jak wyszukiwarka, Dysk, wykresy, Google+, YouTube, Analytics, Google Maps i wiele, wiele innych. Praca z większością z nich opiera się na podobnych zasadach, zmieniają się jedynie nazwy żądań i rodzaj otrzymywanych danych. Warto więc poznać choćby jedną z usług jakie za pomocą API oferuje Google, aby szybko nauczyć się korzystania z pozostałych. W cyklu artykułów tutaj opiszemy sobie większość najczęściej używanych usług od Google i przeanalizujemy sobie pracę z nimi w PHP na przykładach.

W tym artykule, tytułem wstępu zrobimy sobie małe wprowadzenie i zobaczymy na czym polega dostęp do API Google i jakie kroki trzeba poczynić, aby taki dostęp uzyskać. Pierwszą i najważniejszą rzeczą jest uzyskanie od Google klucza API lub tokena Client ID. Publicznego klucza API używamy w aplikacjach, które nie będą operować na prywatnych danych użytkowników, tokena ClientID używamy, gdy taki dostęp będzie miał miejsce. Token taki jest następnie używany przez protokół OAuth 2.0 do uwierzytelniania. Zarówno klucz API, jak i token ClientID wygenerujemy sobie na pomocą konsoli deweloperskiej Google, na której to będziemy musieli zarejestrować każdą ze swoich aplikacji, która korzystać będzie z danego API.

Na początek poznajmy kilka kluczowych kwestii związanych z API Google.

Konsola deweloperska Google

Google Developer Console to w rzeczywistości strona znajdująca się pod adresem: https://console.developers.google.com

Na stronie tej włączymy lub wyłączymy dostęp do każdego z udostępnianych API, zarejestrujemy aplikację oraz zmienimy uprawnienia do korzystania z danego API. Do konsoli deweloperskiej dostęp ma każdy kto posiada konto w Google.
Znajdziemy w tym miejscu ponadto informacje o swoich aplikacjach korzystających z API, takie jak statystyki użycia i tym podobne, ciekawe informacje. Aby rozpocząc pracę z API Google'a będziemy musieli zarejestrować tutaj swoją aplikację, a robimy to tworząc nowy projekt w konsoli.


Aby następnie móc skorzystać z danego API w swojej aplikacji będziemy musieli taki dostęp włączyć (co również robimy za pomocą konsoli). Wygenerować ponadto musimy klucz API lub token Client ID, w zależności od rodzaju tworzonej aplikacji, oraz przede wszystkim utworzyć i zarejestrować tutaj samą aplikację:

Uwierzytelnianie

Uwierzytelnianie w usługach oferowanych przez Google API, tam gdzie konieczna jest autoryzacja użytkownika (np. do Google Dysku, czy Google+) odbywać się będzie za pomocą protokołu OAuth 2.0. Krótkie wprowadzenie do tego protokołu znajdziesz w tym artykule.  Nie będzie tutaj konieczna żadna własna implementacja tego protokołu, gdyż Google wraz ze swoim API udostępnia pakiet bibliotek, z których będziemy korzystać podczas pracy. Biblioteki te mają wbudowaną obsługę OAuth2. Aplikacje, które nie będą korzystać z takiego uwierzytelniania, będą wymagać podania publicznego klucza API, który generujemy w konsoli deweloperskiej. Za pomocą tego indywidualnego klucza identyfikowana będzie nasza aplikacja.

Zarówno klucze API, jak i tokeny generujemy w konsoli w zakładce:
[code]APIs & auth -> Credentials[/code]

1) Client ID

Jest to indywidualny token dostępu do API, który musi zostać wygenerowany dla każdej aplikacji korzystającej z API Google, o ile ta ma operować na danych użytkownika. Token taki dołączamy do swojej aplikacji - za jego pomocą nasza aplikacja będzie dokonywała uwierzytelniania użytkowników na serwerach Google. Token ten generujemy w konsoli przy okazji określania typu naszej aplikacji.

Możemy tutaj utworzyć 3 rodzaje aplikacji, które różnią się zastosowaniami i rodzajem dostępu do API..

Web application

Jest aplikacją korzystającą z API z poziomu strony WWW. Komunikacja możę odbywać się za pomocą Javascript, lub dowolnego innego języka serwerowego, jak PHP, Ruby, Java, Python, czy .NET. W przypadku używania Javascriptu konieczne jest zdefiniowanie dozwolonych dla skryptów JS domen, które podajemy w formularzu (Authorized JavaScript Origins). Jeśli natomiast korzystać będziemy z API za pomocą któregoś z języków serwerowych to określić musimy domenę, lub domeny dla adresów zwrotnych - Authorized redirect URI's - (używane np. podczas przesyłania tokenów i przy przekierowaniach zwrotnych). Autoryzacja tutaj odbywa się zawsze za pomocą OAuth 2.0.

Service account

Innym typem aplikacji jest Service Account.
Aplikacja tego typu nie uzyskuje żadnych informacji z kont użytkownika, co za tym idzie - nie wymaga autoryzacji do kont Google. Aplikacja tego typu może operować na publicznie dostępnych danych udostępnianych przez API, jak np. Mapy Google, czy wyszukiwarka. Nie umożliwi jednak żadnego dostępu do API takich jak Google+, czy Dysk Google, które udostępniają dane wymagające autoryzacji.

Installed application

Ten typ aplikacji to aplikacja desktopowa, działająca np. na komputerze, smartfonie, czy tablecie. Zależnie od rodzaju aplikacji podajemy tutaj dodatkowe dane, takie jak np. klucz dla paczki .apk w przypadku tworzenia aplikacji na Androida, czy ID aplikacji w przypadku tworzenia aplikacji działającej pod ChromeOS. Autoryzacja tutaj odbywa się za pomocą OAuth 2.0. Konsola Google pozwala na łatwe skonfigurowanie aplikacji dla następujących systemów:

• Android
• Chrome OS
• iOS
• Playstation 4
• pozostałe

Oczywiście możemy też tworzyć pod inne systemy, te podane wyżej posiadają jedynie predefiniowane konfiguratory w konsoli. Pozostałe systemy nie wymagają podawania jakiś specjalnych, dodatkowych danych.

2) Publiczny klucz API

Drugą opcją dostępu do API jest skorzystanie z publicznego klucza. Warunek jest jeden - aplikacje tutaj nie mogą korzystać z żadnych danych wymagających uwierzytelniania. Za pomocą klucza publicznego dostaniemy się więc jedynie do usług publicznie dostępnych, takich jak wyszukiwarka, tłumacz, czy mapy Google. Klucz publiczny również musimy wygenerować i również robimy to w konsoli deweloperskiej w sekcji Credentials w swoim projekcie. Nie korzystamy tutaj z OAuth2, a jedynie z klucza API. Utworzyć możemy kilka rodzajow klucza API:

Server key

Używamy tego klucza, jeśli nasza aplikacja działa na serwerze. Klucz taki powinien być wtedy dostępny jedynie dla danego serwera i nie powinien być udostępniany na zewnątrz. Określamy tutaj ponadto dostęp do żądań jedynie dla naszego serwera - uniemożliwi to dostęp osobom z zewnątrz, np. podczas kradzieży klucza. Żądania do API będą przyjmowane jedynie z określonego w konfiguracji adresu serwera.

Browser key

Ten klucz wykorzystujemy jeśli nasza aplikacja będzie działać po stronie klienta - np. w przeglądarce za pomocą Javascriptu. Określamy tutaj wtedy pod jakimi adresami dostępna będzie nasza aplikacja - żądania z każdego innego adresu nie będą przyjmowane przez API.

Android key

Klucz ten używamy, gdy nasza aplikacja działać będzie pod systemami Android.
Wymagane jest tutaj podanie odcisku klucza certyfikatu jakim podpisana jest paczka .apk.

iOS key

Wykorzystywany podczas tworzenia aplikacji dla urządzeń działających pod iOS.
Weryfikowana jest tutaj paczka z aplikacją dla iOS.

Wytyczne co do kluczy

Niezależnie od rodzaju klucza i typu aplikacji klucz API nie powinien być udostępniany publicznie. Nie należy trzymać kluczy zapisanych w plikach dostępnych razem z kodem źródłowym naszej aplikacji. Jeśli aplikacja działa po stronie serwera, to nie zapisujemy klucza "na sztywno" w kodzie aplikacji, ale korzystamy np. ze zmiennych serwera, w których przechowujemy klucz. Ogólnie rzecz biorąc - klucz nigdy nie powinien pojawić się w kodzie jawnym tekstem. Uprawnienia dla danego klucza przydzielamy tylko dla niezbędnych adresów, z jakich korzysta nasza aplikacja. Wszelkie zezwolenia dla danego klucza powinny być jak najbardziej restrykcyjne - nie aktywujemy nigdy opcji, z których nie będzie korzystać nasza aplikacja. Co jeszcze warto wiedzieć - aktywność danego klucza i działania za jego pomocą możemy śledzić w konsoli Google (trzeba włączyć opcję Billing w ustawieniach klucza).

Biblioteki API

Google udostępnia pakiet bibliotek służących do automatyzacji połączenia ze swoim API. Biblioteki takie dostępne są dla większości popularnych języków, takich jak PHP, .NET, Java, Javascript, Python, czy Ruby. Zawierają one szereg klas i metod służących do uzyskiwania połączenia, autoryzacji za pomocą OAuth2 oraz automatyzują pobieranie i wysyłanie danych poprzez API.

Biblioteki klienta od Google przeznaczone dla PHP znajdziemy w serwisie GitHUB - https://github.com/google/google-api-php-client
Dokumentację biblioteki znajdziemy tutaj: https://developers.google.com/api-client-library/php/?hl=pl

Biblioteka taka składa się z klasy:
[code]Google_Client[/code]
która umożliwia dostęp i autoryzację do usług Google oraz z klas odpowiadających danym usługom (services). Jej użycie opiszemy sobie dokładnie w kolejnych artykułach.

Authorized redirect URI's

Jest to jedna z kluczowych opcji w ustawieniach naszej aplikacji korzystającej z API Google. Określa ona do jakich adresów zezwolone są przekierowana zwrotne. Przekierowania takie są wykonywane np. przy odsyłaniu z powrotem do naszej aplikacji po zalogowaniu się użytkownia na konto w Google, są także wykorzystywane do przesyłania tokenów (o tokenach w OAuth pisałej tutaj).

Włączanie i wyłączanie API

Aby móc skorzystać z danego API, musimy je najpierw aktywować dla naszej aplikacji. Listę dostępnych API's znajdziemy w konsoli deweloperskiej, w zakładce:
[code]APIs & auth[/code]

Po wejściu w dane API możemy je włączyć przyciskiem Enable.
Po aktywowaniu danego API, np. dla Google Drive uzyskamy dostęp do wielu opcji, takich jak możliwość ustawienia wyświetlanej użytkownikowi informacji podczas korzystania z danego API za pomocą naszej aplikacji, możliwość ustawienia własnego logo, nazwy itp. rzeczy. Uzyskamy także tutaj dostęp do statystyk związanych z użyciem danego API:

Lista włączonych API's dostępna jest w zakładce Enabled API's znajdującej się na górze.

Przykład użycia

Za chwilę przetestujemy sobie prosty przykład użycia Google API za pomocą udostępnionych przez Google dla PHP bibliotek oraz bez ich pomocy. Połączymy się z publicznie dostępną usługą Google Books i pobierzemy sobie listę książek o zadanym tytule. Przygotujmy więc sobie na lokalnym serwerze jakiś folder, np.
[code]/www/google[/code]
Pobierzmy teraz biblioteki od Google z serwisu GitHUB: https://github.com/google/google-api-php-client.
Z paczki interesować będzie nas jedynie katalog:
[code]/google-api-php-client-master/src/Google[/code]
To w nim znajdują się potrzebne nam biblioteki, reszta folderów to przykłady użycia.
Skopiujmy katalog:
[code]/src/Google[/code]
na serwer, do katalogu który utworzyliśmy do testów, czyli /www/google.

W katalogu /www/google utwórzmy plik:
[code]index.php[/code]
i załączmy do niego autoloader bibliotek od Google:
[code]
<?php
  require_once './Google/autoload.php';
  $client = new Google_Client();
?>[/code]

Skorzystamy teraz z API dla Google Books, które nie wymaga podawania klucza.
Z API połączyć możemy się na dwa sposoby:

• z użyciem bibliotek Google
• bezpośrednio, np. za pomocą cURL-a

Używając bibliotek od Google (są oddzielne dla każdego z API) praca jest trochę łatwiejsza, gdyż automatyzują wiele rzeczy. Tak naprawdę jednak łączą się one tak samo jak przy sposobie numer 2, otrzymane dane jednak przekazują w bardziej przyjazny sposób. Sposobem drugim otrzymujemy surowe dane w formacie JSON, które przetworzyć musimy sami. Przyjrzyjmy się obu sposobom.

1) Klasa Google_Client() i Google_Service_()

Sposób pierwszy z użyciem gotowej biblioteki od Google:
[code]
<?php
// dołączamy biblioteki Google
require_once './Google/autoload.php';

// Tworzymy obiekt klienta
$client = new Google_Client();

// Tworzymy obiekt serwisu (API)
$service = new Google_Service_Books($client);

// Pobieramy listę książek
$q = 'harry+potter';
$results = $service->volumes->listVolumes($q);

// Wyświetlamy wynik:
foreach ($results as $item) {
  echo $item['volumeInfo']['title'], "<br /> \n";
}
?>[/code]
Wynikiem jest lista książek zawierająca w tytule slowo 'Harry Potter':

2) Biblioteka cURL i dane w formacie JSON

Sposób drugi, czyli bezpośrednie połączenie przez cURL i otrzymanie surowych danych:
[code]
<?php
$q = 'harry+potter';
$url = 'https://www.googleapis.com/books/v1/volumes?q=' . $q;

// Połączenie przez cURL
$handle = curl_init($url);
curl_setopt($handle, CURLOPT_RETURNTRANSFER, true);
curl_setopt($handle, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($handle, CURLOPT_SSL_VERIFYHOST, false);
$response = curl_exec($handle);
curl_close($handle);

// Wynik w formacie JSON
echo '<pre>'.$response.'</pre>';
?>[/code]
Wynik:

Jak widzimy, w drugim przypadku otrzymaliśmy pełen pakiet danych w formacie JSON, którym następnie musimy zająć się już sami.

Jeśli chcielibyśmy przetworzyć dane JSON otrzymane sposobem drugim, aby otrzymać samą listę tutułów jak w pierwszym przypadku, zrobimy to tak:
[code]
<?php
    $q = 'harry+potter';
    $url = 'https://www.googleapis.com/books/v1/volumes?q=' . $q;

    $handle = curl_init($url);
    curl_setopt($handle, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($handle, CURLOPT_SSL_VERIFYPEER, false);
    curl_setopt($handle, CURLOPT_SSL_VERIFYHOST, false);
    $response = curl_exec($handle);            
    $json = json_decode($response, true);
    curl_close($handle);

    // Wyświetlamy dane odebrane z JSON-a
    foreach($json as $item)
    {
      echo $item['volumeInfo']['title'], "<br /> \n";    
    }
?>[/code]
Wynik będzie taki sam jak w pierwszym przypadku:

API

Jak zapewne widzimy w drugim przypadku, tak naprawdę połączyliśmy się metodą GET z adresem:
[code]https://www.googleapis.com/books/v1/volumes?q=harry+potter[/code]
Otóż w dokładnie taki sam sposób dostaniemy w Google dostęp do innych danych, pochodzących z innych API. Cała sprawa polega na przygotowaniu odpowiedniego adresu, który jest jednocześnie żądaniem - a następnie na odpowiedzi serwera na to żądanie. Odpowiedź taka przychodzi w formacie JSON co widzieliśmy na przykładzie powyżęj.
Poniżej np. przykład połączenia z API Google Translate, któremu w parametrach podajemy tekst do przetłumaczenia i klucz API:
[code]https://www.googleapis.com/language/translate/v2?key=KLUCZ_API&q=hello%20world&source=en&target=pl[/code]
Cała zasada pracy z API polega na przygotowywaniu odpowiednich żadań, które zwracać nam będą odpowiednie, wymagane przez nas dane.
Tak to właśnie działa w praktyce.

W następnych artykułach przyjrzymy się poszczególnym API za pomocą praktycznych przykładów.
Na chwilę obecną wiemy jak działają Google APIs i znamy podstawy ich użycia.
Jako wprowadzenie do tematu myślę, że powinno to nam wystarczyć.