Pierwsze kroki z biblioteką klienta Google Data PHP

Ostrzeżenie: ta strona dotyczy starszych interfejsów API Google – interfejsów API danych Google – dotyczy tylko interfejsów API wymienionych w katalogu interfejsów API danych Google, z których wiele zostało zastąpionych nowszych. Informacje na temat konkretnego nowego interfejsu API można znaleźć w dokumentacji nowego interfejsu API. Informacje o autoryzowaniu żądań za pomocą nowszego interfejsu API znajdziesz w artykule Uwierzytelnianie i autoryzacja kont Google.

Film: Obejrzyj film, w którym Trevor Johns omawia instalację biblioteki klienta, architekturę biblioteki i przewodnik po kodzie.

Jochen Hartmann, Google Data API Team
Aktualizacja: październik 2008 r. (pierwotny autor: Daniel Holevoet)

• Wprowadzenie
• Przed instalacją
• Instalowanie PHP
  • W systemie Windows:
  • W systemie Mac OS X
  • W systemie Linux:
• Instalowanie biblioteki klienta Google Data PHP
• Sprawdzanie, czy masz dostęp do plików biblioteki klienta
  • Uruchamianie narzędzia PHP do sprawdzania instalacji
  • Uruchamianie przykładów
• Gdzie można znaleźć więcej informacji
• Załącznik A: edytowanie ścieżki PHP w pliku konfiguracji php.ini
• Załącznik B. Używanie języka PHP z poziomu wiersza poleceń
• Załącznik C: wskazówki i rozwiązania
• Historia zmian

Wprowadzenie

Biblioteka klienta PHP Google Data to potężna kolekcja klas, które pozwalają korzystać z interfejsów Google Data API. W przeciwieństwie do innych bibliotek klienta jest on teraz częścią pakietu platformy Zend, ale można go pobrać oddzielnie. Podobnie jak inne biblioteki klienta jest również oprogramowaniem typu open source, które zaprojektowano z myślą o prostej i efektywnej obsłudze, co pozwala na szybkie rozpoczęcie projektów.

Wstępna instalacja

Język PHP może być już zainstalowany na komputerze lub serwerze WWW dewelopera, więc najpierw należy sprawdzić, czy jest on na tyle aktualny, aby można go było użyć w bibliotece klienta. Najłatwiej to zrobić, umieszczając nowy plik w katalogu dostępnym na serwerze. Wpisz do pliku te informacje:

<?php phpinfo(); ?>

Następnie upewnij się, że jest on dostępny w przeglądarce. Aby to zrobić, ustaw odpowiednie uprawnienia i przejdź do odpowiedniej lokalizacji w przeglądarce. Jeśli na komputerze jest zainstalowany język PHP, a serwer może renderować strony w języku PHP, powinien wyglądać mniej więcej tak:

Zrzut ekranu przedstawia stronę z informacjami o języku PHP. Na tej stronie wyświetlana jest wersja zainstalowanego języka PHP (w tym przypadku jest to wersja 5.2.6) oraz włączone rozszerzenia (w sekcji „Skonfiguruj polecenie”) oraz lokalizacja wewnętrznego pliku konfiguracji PHP (w sekcji „Wczytany plik konfiguracji”). Jeśli strona nie jest wyświetlana lub jeśli Twoja wersja PHP jest starsza niż 5.1.4, musisz zainstalować lub uaktualnić swoją wersję PHP. W przeciwnym razie możesz pominąć następną sekcję i przejść do instalowania biblioteki klienta PHP.

Uwaga: jeśli masz dostęp do wiersza poleceń i planujesz używać PHP do obsługi skryptów wiersza poleceń, zapoznaj się z sekcją poświęconą wierszowi poleceń w tym artykule.

Instalowanie PHP

Instalacja może być nieco różna w zależności od platformy, dlatego podczas instalacji należy przestrzegać instrukcji dotyczących konkretnej platformy. Zanim zagłębimy się w nową funkcję, warto wspomnieć, że w tym czasie popularne stały się pakiety wstępnie zainstalowane, które zawierają również serwer WWW Apache, bazę danych MySQL oraz język PHP. W systemach Windows, macOS X i Linux dostępny jest projekt XAMPP. Użytkownicy Mac OS X mogą wybrać projekt AMP. Oba te pakiety obsługują protokół OpenSSL w języku PHP (jest to wymagane do interakcji z uwierzytelnionymi plikami danych).

Jeśli instalujesz PHP w sposób opisany poniżej, upewnij się, że masz też włączoną i włączoną obsługę OpenSSL. Więcej informacji na ten temat znajdziesz w sekcji dotyczącej SSL w witrynie PHP. W kolejnych sekcjach dowiesz się, jak samodzielnie zainstalować język PHP.

W systemie Windows:

Najprostszym sposobem instalacji lub uaktualnienia języka PHP w systemie Windows jest instalator PHP dostępny na stronie pobierania języka PHP.

1. Wybierz opcję instalatora PHP (w sekcji plików binarnych systemu Windows) odpowiadającą najnowszej wersji języka PHP i pozwól jej pobrać.
2. Otwórz instalator i postępuj zgodnie z instrukcjami kreatora instalacji.
3. Gdy pojawi się prośba, wybierz serwer WWW zainstalowany w systemie, dzięki czemu będzie on mógł współpracować z kodem PHP.
4. Sprawdź instalację, wykonując czynności opisane w sekcji powyżej.

W systemie Mac OS X

Język PHP jest zainstalowany w systemie OS X, ale zanim go użyjesz, uaktualnij go do najnowszej wersji. Aby przeprowadzić uaktualnienie, możesz zainstalować dowolny z bezpłatnych pakietów binarnych lub skompilować go samodzielnie. Szczegółowe informacje znajdziesz na stronie dokumentacji PHP dotyczącej instalowania w systemie Mac OS X.

Po zainstalowaniu lub skonfigurowaniu systemu OS X sprawdź instalację, wykonując czynności opisane w tej sekcji dotyczącej tego dokumentu.

W Linuksie:

W zależności od dystrybucji Linuksa może istnieć wbudowana lub łatwa w użyciu opcja konfiguracji dla języka PHP. Na przykład w systemie Ubuntu możesz używać menedżera pakietów lub po prostu wpisać w terminalu:

sudo apt-get install php5

Jeśli w dystrybucji Linuksa nie jest dostępna instalacja w pakiecie, musisz zainstalować ją z kodu źródłowego. Znajdziesz tu szczegółowe instrukcje dotyczące kompilacji kodu PHP dla Apache 1.3 i kompilacji kodu PHP dla Apache 2. Na stronie PHP.net znajdują się też instrukcje dotyczące innych serwerów.

Instalowanie biblioteki klienta PHP Google Data

Gdy masz już działającą wersję PHP, możesz zainstalować bibliotekę klienta. Biblioteka klienta jest częścią oprogramowania open source Zend Framework, ale można ją również pobrać jako samodzielną wersję. Jeśli masz już zainstalowaną platformę Zend Framework (1.6 lub nowszą), możesz pominąć instalację, ponieważ dołączona jest biblioteka klienta Google Data. Jeśli jednak używasz najnowszej wersji platformy, masz pewność, że zawsze masz dostęp do najnowszych funkcji i poprawek, więc zwykle zalecamy tę opcję.

Pobranie pełnej platformy da Ci dostęp nie tylko do Biblioteki klienta danych Google, ale również do pozostałej części platformy Sama biblioteka klienta korzysta z kilku innych klas wchodzących w skład platformy Zend, ale nie ma potrzeby pobierania jej w całości, ponieważ powiązaliśmy je z pojedynczym pobieraniem.

1. Pobierz pliki bibliotek klienta danych Google. (Wyszukaj na tej stronie wyrażenie „Interfejsy API danych Google”).
2. Zdekompresuj pobrane pliki. Należy utworzyć 4 podkatalogi:
   • demos – przykładowe aplikacje
   • documentation – dokumentacja plików biblioteki klienta
   • library – rzeczywiste pliki źródłowe biblioteki klienta.
   • tests – pliki jednostkowe przeznaczone do automatycznego testowania.
3. Dodaj lokalizację folderu library do ścieżki PHP (patrz następna sekcja).

Sprawdzam, czy masz dostęp do plików biblioteki klienta

Na koniec upewnij się, że możesz odwoływać się do plików biblioteki klienckiej PHP i dołączyć je z katalogu, w którym tworzysz projekt. W tym celu trzeba ustawić zmienną include_path w pliku konfiguracyjnym PHP (php.ini). Zmienna include_path zawiera lokalizację katalogu, którą PHP sprawdza po wydaniu instrukcji require lub include, która pobiera zewnętrzne klasy, biblioteki lub pliki do bieżącego skryptu, podobnie jak instrukcja import w Javie. Musisz dołączyć lokalizację plików biblioteki klienta do ustawień określonych w pliku include_path. Można to zrobić na 2 sposoby (szczegóły poniżej):

• Ustaw na stałe dyrektywę include_path w pliku konfiguracji php.ini z poziomu wiersza poleceń. Dostęp wymaga powłoki i zapisu.
• Ustaw zmienną ścieżki include_path na poziomie „na katalog” – wymaga serwera WWW Apache i możliwości tworzenia plików .htaccess.
• Użyj funkcji set_include_path(), by dynamicznie ustawiać ścieżkę uwzględniania w skryptach – możesz to zrobić dynamicznie w każdym pliku .php.

Jeśli masz uprawnienia do powłoki lub zapisu w pliku php.ini (lub piszesz kod na komputerze lokalnym), postępuj zgodnie z instrukcjami w załączniku A. Jeśli używasz serwera WWW Apache i masz możliwość tworzenia plików .htaccess, możesz ustawić zmienną include_path na poziomie „katalogu”, co oznacza, że wszystkie pliki w katalogu, w którym pracujesz, mogą automatycznie odwoływać się do katalogu biblioteki klienta.

Opcje konfiguracji języka PHP możesz określić w poniższym fragmencie:

# This works for PHP5 in both Apache versions 1 and 2
<IfModule mod_php5.c>
  php_value include_path        ".:/usr/local/lib/php:/path/to/ZendGdata/library"
</IfModule>

Uwaga: więcej informacji o zmianie ustawień znajdziesz w Instrukcji obsługi PHP.

Jeśli nie masz dostępu do powłoki i nie możesz modyfikować ani tworzyć plików .htaccess, zawsze możesz użyć funkcji set_include_path. Być może masz już ustawioną wartość parametru include_path, więc dobrze jest stosować się do poniższego modelu, aby dołączać nowe wartości, zamiast zastępować całą ścieżkę.

$clientLibraryPath = '/path/to/ZendGdata/library';
$oldPath = set_include_path(get_include_path() . PATH_SEPARATOR . $clientLibraryPath);

Uwaga: więcej informacji o funkcji set_include_path znajdziesz na stronach ręcznego przetwarzania danych.

Uruchamianie narzędzia PHP do sprawdzania instalacji

Aby sprawdzić, czy ścieżka uwzględniania jest ustawiona prawidłowo, możesz uruchomić skrypt instalacji sprawdzania w języku PHP. Wystarczy skopiować zawartość pliku i wkleić go do nowego pliku w katalogu dostępnym na serwerze, a następnie otworzyć go w przeglądarce. Jeśli pojawią się dane wyjściowe podobne do poniższych, oznacza to, że wszystko zostało skonfigurowane prawidłowo i możesz zacząć korzystać z biblioteki klienta PHP:

Jeśli zauważysz błędy (jak na zrzucie ekranu poniżej), postępuj zgodnie z instrukcjami. Być może brakuje rozszerzeń lub ścieżka nie została prawidłowo skonfigurowana. Pamiętaj, że aby zmiany zaczęły obowiązywać, może być konieczne ponowne uruchomienie serwera. Ma to zastosowanie tylko wtedy, gdy faktycznie modyfikujesz plik php.ini. Zrzut ekranu poniżej pokazuje, że include_path jest ustawiony na /path/to/nowhere:

Uwaga: narzędzie do sprawdzania PHP sprawdza, czy: Jeśli określony test się nie powiedzie, pozostałe testy nie zostaną wykonane.

Po zainstalowaniu biblioteki klienta czas uruchomić przykłady.

Uruchamianie przykładów

W katalogu głównym katalogu Zend/Gdata znajdziesz folder demonstracji – przykłady, które pomogą Ci rozpocząć. Niektóre z nich możesz uruchamiać za pomocą wiersza poleceń, na przykład demos/Zend/Gdata/Blogger.php czy demos/Zend/Gdata/Spreadsheet-ClientLogin.php. Możesz je uruchamiać za pomocą polecenia php /path/to/example. Pozostałe przykłady można uruchomić zarówno w wierszu poleceń, jak i w przeglądarce. Jeśli chcesz wyświetlić je w przeglądarce, umieść je w każdym katalogu, którego używasz do wyświetlania stron internetowych. Te przykłady powinny stanowić podstawowy poradnik na temat tego, jak pisać i uruchamiać aplikację do obsługi danych Google. Jeśli jednak potrzebujesz więcej, możesz skorzystać z innych zasobów.

Uwaga: jeśli chcesz zobaczyć internetowe pokazy demonstracyjne aplikacji, wejdź na stronę googlecodesamples.com i poszukaj aplikacji w języku PHP.

Gdzie można znaleźć więcej informacji

Najlepsze informacje o klasach, które są częścią biblioteki klienta, znajdziesz w przewodniku po interfejsie API w witrynie Zend Framework. Pamiętaj, aby wybrać pakiet Zend_Gdata z menu.

Od tego momentu wszystko powinno być gotowe do kodowania. Więc dalej pisz świetne aplikacje. Nie możemy się doczekać Twoich wyników!

Znajdziesz tutaj przewodniki dla programistów dotyczące następujących usług w języku PHP:

• Blogger
• Kalendarz Google
• Lista dokumentów Google
• YouTube Data API,

Ponieważ biblioteka klienta PHP jest projektem typu open source, stale dodajemy obsługę kolejnych interfejsów API. Każda usługa ma własną grupę pomocy. Więcej informacji o dostępnych grupach pomocy znajdziesz w artykule z najczęstszymi pytaniami.

Jeśli potrzebujesz pomocy w rozwiązaniu problemów z wywołaniami interfejsu API, skorzystaj z artykułów na temat debugowania żądań do interfejsu API korzystających z narzędzi do przechwytywania ruchu sieciowego oraz na temat korzystania z serwerów proxy z interfejsami Google Data API. Dostępnych jest też kilka zewnętrznych artykułów o instalowaniu XAMPP w Linuksie i instalowaniu XAMPP w systemie Windows. Oprócz tych artykułów przeczytaj też posty o Bibliotece klienta PHP na blogu Google Data API.

Załącznik A: edytowanie ścieżki PHP w pliku konfiguracji php.ini

Ścieżka PHP zawiera zmienną lokalizacji, która podczas wyszukiwania szuka dodatkowych bibliotek. Aby język PHP mógł wczytywać pliki bibliotek klienta Google Data PHP na Twoim komputerze lub serwerze, musi znajdować się w lokalizacji, którą zna PHP. Możesz też dodać lokalizację plików do ścieżki PHP. Pamiętaj, że zmiany w pliku php.ini wymagają zwykle ponownego uruchomienia serwera. Aktualną wartość zmiennej include_path możesz sprawdzić w każdej chwili na stronie z informacjami o PHP przedstawionej wcześniej. Wyszukaj w pierwszej tabeli komórkę Wczytany plik konfiguracji i odszukaj ścieżkę w kolumnie po prawej stronie.

Uwaga: jeśli okaże się, że używasz php z poziomu wiersza poleceń, może być konieczne zmodyfikowanie dodatkowej zmiennej ścieżki. Zapoznaj się z artykułem Dodatek B: używanie języka PHP z poziomu wiersza poleceń.

Gdy znajdziesz plik php.ini, wykonaj te czynności, aby go dołączyć do ścieżki.

1. Otwórz plik php.ini w dowolnym edytorze tekstu.
2. Znajdź wiersz odwołujący się do ścieżki PHP, która powinna zaczynać się od include_path.
3. Dołącz ścieżkę zapisaną przez Zend do listy istniejących lokalizacji, wyprzedzając nową ścieżkę za pomocą wyznaczonego separatora w systemie operacyjnym (: w systemach podobnych do Unix, ; w systemie Windows). Prawidłowa ścieżka w systemie typu Unix będzie wyglądała mniej więcej tak:

   /path1:/path2:/usr/local/lib/php/library

   W systemie Windows wyglądałaby mniej więcej tak:

   \path1;\path2;\php\library

4. Zapisz i zamknij plik.

Uwaga: w systemie Mac OS X Finder nie zezwala na dostęp do plików w lokalizacjach systemowych, takich jak katalog /etc. Dlatego najłatwiej jest je edytować za pomocą edytora wiersza poleceń, takiego jak vi lub pico. Aby to zrobić, użyj polecenia takiego jak pico /path/to/php.ini.

Załącznik B: używanie PHP z poziomu wiersza poleceń

Od wersji PHP 5 jest dostępne narzędzie wiersza poleceń znane jako CLI dla „tłumacza wiersza poleceń”. Użycie tego narzędzia umożliwia uruchamianie skryptów php z poziomu wiersza poleceń. Może się to okazać przydatne w sytuacji, gdy na komputerze korzystasz z języka PHP i szukasz sposobów na szybkie przetestowanie niektórych skryptów. Oczywiście będzie to wymagało dostępu do powłoki na Twoim serwerze. Warto pamiętać, że język PHP zwykle używa 2 osobnych plików php.ini – jeden zawiera opcje konfiguracji PHP uruchomione na serwerze, a drugie – konfiguracje używane przez PHP podczas wykonywania z poziomu wiersza poleceń. Jeśli chcesz uruchomić aplikacje demonstracyjne wiersza poleceń z biblioteki klienta, musisz też zmodyfikować plik php.ini wiersza poleceń.

Aby ją znaleźć, wpisz te polecenia w systemach typu Unix (Mac OS X, Linux i inne):

php -i | grep php.ini

To polecenie powinno wyświetlić w terminalu te informacje:

Configuration File (php.ini) Path => /etc/php5/cli
Loaded Configuration File => /etc/php5/cli/php.ini

Uwaga: rzeczywiste ścieżki (/etc/php...) mogą się różnić w zależności od systemu.

Załącznik C: wskazówki i rozwiązania

Ta sekcja zawiera krótki opis niektórych problemów wykrytych przez programistów podczas pracy z kodem PHP oraz odpowiednich rozwiązań.

Problem z rozszerzeniem dom-xml w XAMPP

Biblioteka klienta PHP wykorzystuje klasy DOMDocument do przekształcania żądań XML i odpowiedzi w obiekty PHP. Rozszerzenie dom-xml może powodować problemy z obsługą plików XML i może powodować nieprawidłowe przekształcenia. Niektórzy z naszych programistów stwierdzili, że podczas korzystania z XAMPP konstruktor DOMDocument jest zastąpiony starszym wywołaniem funkcji, jak wyjaśniono na stronie PHP. Aby rozwiązać ten problem, upewnij się, że obsługa pliku XML nie została zastąpiona w pliku php.ini. Pamiętaj, aby usunąć odniesienia do php_domxml.dll w pliku konfiguracji.

Upłynął limit czasu podczas korzystania z biblioteki klienta

Jeśli korzystasz z biblioteki klienta do wykonywania dość dużych żądań, np. przesyłania filmów do YouTube Data API, może być konieczna zmiana parametru timeout w klasie Zend_Http_Client. Możesz to łatwo zrobić, przekazując podczas tworzenia instancji parametr $config, który ustawia wartość timeout na inną niż domyślna 10-sekundowa:

// assuming your Zend_Http_Client already exists as $httpClient
// and that you want to change the timeout from the 10 second default to 30 seconds

$config = array('timeout' => 30);
$httpClient->setConfig($config);

Niektórzy dostawcy usług hostingowych nie zezwalają na nawiązywanie połączeń https ze swoich serwerów

Z naszych danych wynika, że niektórzy dostawcy usług hostingowych nie zezwalają na nawiązywanie połączeń https z serwerów domyślnych. Jeśli zobaczysz komunikat o błędzie podobny do poniższego, konieczne może być połączenie https przez bezpieczny serwer proxy:

Unable to Connect to sslv2://www.google.com:443. Error #110: Connection timed out

Dostawca usług hostingowych powinien podać informacje na temat rzeczywistego adresu serwera proxy, który ma być używany. Fragment kodu poniżej pokazuje, jak można zastosować niestandardową konfigurację serwera proxy z biblioteką klienta PHP:

// Load the proxy adapter class in addition to the other required classes
Zend_Loader::loadClass('Zend_Http_Client_Adapter_Proxy');

// Configure the proxy connection with your hostname and portnumber
$config = array(
    'adapter'    => 'Zend_Http_Client_Adapter_Proxy',
    'proxy_host' => 'your.proxy.server.net',
    'proxy_port' => 3128
);

// A simple https request would be an attempt to authenticate via ClientLogin
$proxiedHttpClient = new Zend_Http_Client('http://www.google.com:443', $config);

$username = '[e-mail]';
$password = 'barbaz';

// The service name would depend on what API you are interacting with, here
// we are using the Google DocumentsList Data API
$service = Zend_Gdata_Docs::AUTH_SERVICE_NAME;

// Try to perform the ClientLogin authentication using our proxy client.
// If there is an error, we exit since it doesn't make sense to go on.
try {

  // Note that we are creating another Zend_Http_Client
  // by passing our proxied client into the constructor.

  $httpClient = Zend_Gdata_ClientLogin::getHttpClient(
      $username, $password, $service, $proxiedHttpClient);

} catch (Zend_Gdata_App_HttpException $httpException) {

  // You may want to handle this differently in your application
  exit("An error occurred trying to connect to the proxy server\n" .
      $httpException->getMessage() . "\n");

}

Historia zmian

1 października 2008

Autor zmiany: Jochen Hartmann. Ta aktualizacja zawiera następujące zmiany:

• Uprościliśmy konfigurację PHP na serwerach WWW, przenosząc sekcje odwołujące się do języka PHP wiersza poleceń do dodatku.
• Dodano notatkę dotyczącą wielu plików konfiguracji php.ini.
• Dodaliśmy sekcje, które pozwalają dynamicznie ustawiać wartość include_path.
• Dodano sekcję do skryptu sprawdzania instalacji.
• Dodano link do przykładów online.
• Dodaliśmy linki do stron XAMPP i AMP.
• Dodaliśmy załącznik „Wskazówki i rozwiązania”.