wtorek, 16 czerwca 2015

[API][FB] Wstęp do FB Graph API i PHP SDK

TRUE
1475662091400928209
Facebook to ogromnie rozbudowana struktura oferująca równie rozbudowane API do swoich usług. Niezależnie od tego, czy z Facebooka się korzysta, czy nie - każdy webdeveloper powinien poznać choćby podstawy korzystania z jego API. Dzięki temu API uzyskać możemy dostęp (oczywiście za zgodą użytkownika) do praktycznie każdej informacji jaką FB przechowuje, takiej jak tablica, znajomi, komentarze, zdjęcia i wiele wiele innych elementów. Za pomocą API Facebooka, które ma swoją nazwę - Graph tworzyć można zarówno głupie gierki, jak i praktyczne aplikacje operujące na zebranych przez FB danych. W cyklu artykułów tutaj zajmiemy się tym drugim zastosowaniem, gdyż żadnych symualatorów farm tworzyć tutaj nie będziemy. Nauczymy się za to metod na pozyskiwanie z FB odpowiednich danych i pracy z nimi. Zaczynamy od wstępu do API, czyli opisu jak mniej więcej wygląda praca z facebookowym API od strony technicznej.

Podstawowe pojęcia

Aby rozpocząć zabawę z Graphem musimy nauczyć się kilku podstawowych pojęć, które wprowadza framework Facebooka i z których będziemy tutaj korzystać. Te pojęcia to odpowiednio: Facebook Graph API, FBML, FQL, Facebook JavaScript, APP ID, APP Secret oraz Facebook Canvas.


Facebook Graph API

Pod nazwą tą rozumiemy ogólne API, czyli usługę sieciową jaką oferuje FB programistom. Wymiana danych odbywać się będzie tutaj podobnie jak w API Google za pomocą żądań REST. API pozwoli nam na dostęp do danych takich jak profil użytkownika, jego tablica, znajomi, komentarze, zdjęcia i tym podobne elementy oraz udostępni szereg metod takich jak logowanie, przekierowania, czy zmiana danych.

Facebook Markup Language (FML)

Jest językiem stworzonym przez Facebooka, który wyświetla elementy na stronie FB. Jest on oparty na HTML-u, z różnicą taką, że działa on wewnętrznie tylko dla Facebooka. Jego składnia zawiera większość elementów jakie zawierają się w zwykłym HTML, takich jak formatowanie tekstu, listy, odnośniki itp. Zawiera jednak dodatkowo znaczniki stworzone typowo do pracy z Facebookiem. Ciekawą sprawą jest, że nie obsługuje on sam w sobie JavaScriptu, a jedynie specjalną jego odmianę stworzoną specjalnie na potrzeby FB.

Facebook Query Language (FQL)

Jest to również język stworzony na potrzeby Facebooka, a służy on do pobierania danych. Jego struktura jest bardzo podobna do języka SQL, odwołujemy się tutaj do zestawów danych podobnie jak do tabel w bazie danych, mamy więc tutaj zapytania SELECT i inne, a na całości operujemy tak jakbyśmy mieli do czynienia ze zwykłą tabelą. Przy okazji ma on kilka ograniczeń, które nie występują w "czystym" SQL-u.

Facebook JavaScript

Jako, iż FML nie obsługuje zwykłego JavaScriptu, stworzono specjalną wersję JS typowo do zastosowań przez Facebooka. Jest on bardzo podobny na pierwszy rzut oka do zwykłego JS, istnieją jednak tutaj znaczne różnice. Największą z nich jest fakt, że operujemy tutaj na znacznie zmienionym drzewie DOM, stworzonym za pomocą FML. Dodatkowo - zmienne i funkcje globalne dotyczyć tu będą nie całego dokumentu, lecz jedynie naszej aplikacji.

APP ID

Numer ten jest wymagany dla każdej aplikacji działającej z wykorzystaniem API Facebooka. Jest on unikalny dla każdej z aplikacji. APP ID otrzymać można od FB w momencie rejestracji swojej aplikacji na stronie.

APP Secret

Jest to wygenerowany dla aplikacji unikalny klucz. APP Secret otrzymać można od FB w momencie rejestracji swojej aplikacji na stronie.

Facebook Canvas

Jest to przestrzeń (canvas) na stronie Facebooka pod którą może działać nasza aplikacja. Jest to wewnętrzne "okno" Facebooka udstępniające obszar roboczy dla aplikacji.

Rejestracja aplikacji

Pierwsze co musimy zrobić, to zarejestrować się jako developer oraz zarejestrować swoją aplikację na stronie Facebooka. Rejestracja jako developer wymaga niestety podania numeru telefonu, na który przychodzi kod aktywacyjny.
Podczas rejestracji aplikacji otrzymamy APP ID, którym nasza aplikacja będzie się identyfikować oraz APP Secret, czyli unikalny klucz dla aplikacji. Aplikację rejestrujemy na stronie: http://www.facebook.com/developers


Rodzaje aplikacji

Facebook oferuje możliwość stworzenia kilku typów aplikacji:

  • Facebook Canvas - aplikacja działająca "w okienku" Facebooka
  • Website - aplikacja zewnętrzna działająca na serwerze
  • iOS - aplikacja dla systemów iOS
  • Android - aplikacja dla systemów Android
  • Windows App - aplikacja desktopowa dla systemów Windows
  • Page Tab - aplikacja działająca bezpośrednio na stronie Facebooka
  • Xbox - aplikacja dla Xboxów
  • PlayStation - aplikacja dla PlayStation


Na początek dla testu stworzymy sobie prostą, przykładową aplikację typu Strona internetowa.
Wybieramy ją z listy, która się nam otworzy:


Podajemy następnie nazwę dla naszej aplikacji, np.:
[code]MyTestApp[/code]
Klikamy następnie na Create New Facebook App ID, pozwoli to nam wygenerować numer APP ID dla naszej aplikacji.



Na pytanie, czy będzie to testowa wersja innej naszej aplikacji odpowiadamy NIE i wybieramy kategorię, np.:
[code]Aplikacje dla stron[/code]



Po kliknięciu na Create APP ID zostaniemy przekierowani do prostego konfiguratora naszej aplikacji, w którym podajmy adres do naszej aplikacji:
[code]http://localhost/fb/app.php[/code]



Następnie zamykamy konfigurator opcją Skip Quick Start na górze:



Pozwoli to nam od razu dostać się do opcji zaawansowanych, w których ustawimy teraz kilka opcji.
Zostanie nam udostępniony APP ID naszej aplikacji oraz wygenerowny APP Secret - dane te będą nam potrzebne za chwilę do połaczenia z API Facebooka.



Zauważmy przy okazji, że nasza aplikacja ustawiona jest domyślnie w trybie developerskim. Oznacza to, iż póki co jedynie my mamy do niej dostęp. Aby dodać dostęp w wersji developerskiej dla kont innych niż nasze, musimy je dodać w zakładce Roles.



Możemy tutaj np. dodać kilka kont o charakterze tester, które pozwolą na przetestowanie danych funkcjonalności.
Wróćmy jednak do konfiguracji. W zakładce:
[code]Settings -> Basic[/code]
Adres URI naszej aplikacji musi zgadzać się ze stanem faktycznym, więc upewnijmy się, że podajemy tutaj faktyczny adres do naszej appki.



Przejdziemy teraz do ustawień zaawansowanych, wejdźmy w zakładkę:
[code]Settings -> Advanced[/code]
Będziemy musieli tutaj ustawić adres zwrotny dla żądań. Do adresu tego będą kierowały przede wszystkim przekierowania po zalogowaniu się do aplikacji na stronie Facebooka za pomocą OAuth. Musimy podać tutaj prawidłowy adres, inaczej nie będziemy w stanie zalogować się do aplikacji.



Po podaniu adresu zwrotnego zapisujemy zmiany i nasza aplikacja jest już w tym momencie wstępnie przygotowana do pracy. To oczywiście jedynie wstępna konfiguracja, ale wystarczy nam na początek do przetestowania działania API.

SDK

Facebook udostępnia SDK dla następujących platform:

  • iOS
  • Android
  • JavaScript
  • PHP
  • Unity (silnik 3D).

Opiszemy sobie pracę z SDK dla PHP, pobrać więc musimy biblioteki przygotowane dla języka PHP. Obecnie dostępna (na chwilę pisania tego artykułu) jest wersja 4.x bibliotek. Zawsze najnowszą wersję znajdziemy pod adresem: https://developers.facebook.com/docs/php/gettingstarted.

Jej użycie trochę się różni od użycia poprzedniej wersji, czyli 3.x. W artykule tym jak i kolejnych opierać się będziemy na SDK z gałęzi 4.x. Biblioteki pobierzemy za pomocą Composera. Stwórzmy sobie katalog na naszą aplikację, np.
[code]/www/fb[/code]
tak, aby dostęp do niego wyglądał następująco:
[code]http://localhost/fb/[/code]

W katalogu /www/fb przygotowujemy plik composer.json o treści:
[code]{
  "require" : {
    "facebook/php-sdk-v4" : "4.0.*"
  }
}[/code]
Następnie pobieramy całość za pomocą Composera:
[code]$ cd /www/fb
$ composer install[/code]

Biblioteki zostaną pobrane do katalogu /vendor i załaczymy je za pomocą wygenerowanego przez Composer autoloadera dla klas. Utwórzmy plik z naszą aplikacją, np.:
[code]/www/fb/app.php[/code]
Tak, aby mieć do niego dostęp z poziomu:
[code]http://localhost/fb/app.php[/code]

W pliku tym na początek załączmy wymagany autoloader:
[code]<?php
// app.php

// dołączamy autoloader
require './vendor/autoload.php';[/code]

Następnie musimy skonfigurować kilka rzeczy identyfikujących naszą aplikację.
[code]<?php
// app.php

// dołączamy autoloader
require './vendor/autoload.php';

// startujemy sesję
session_start();

define('FB_APP_ID', '1234567891234567'); // APP ID
define('FB_APP_SECRET', 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'); // APP SECRET
define('FB_APP_REDIRECT_URI', 'http://localhost/fb/app.php');  // REDIRECT

// deklarujemy używane przestrzenie nazw
use Facebook\Facebook;
use Facebook\FacebookSession;
use Facebook\FacebookRequest;
use Facebook\GraphUser;
use Facebook\FacebookRequestException;
use Facebook\FacebookRedirectLoginHelper;

// ustawiamy ID aplikacji i client secret
FacebookSession::setDefaultApplication(FB_APP_ID, FB_APP_SECRET);
[/code]
Deklarujemy na początek 3 stałe, które zawierać będę następujące dane:

  • APP ID naszej aplikacji
  • APP SECRET
  • oraz adres zwrotny do naszej aplikacji


Po skonfigurowaniu tych danych określamy przestrzenie nazw z jakich będziemy korzystać i następnie za pomocą metody:
[code]FacebookSession::setDefaultApplication(APP_ID, APP_SECRET);[/code]
identyfikujemy naszą aplikację.

SDK udostępnia nam do wykorzystania kilka helperów, czyli metod pomocnych w pracy z danymi funkcjonalnościami. Za pomocą jednego z takich helperów będziemy musieli teraz pobrać od Facebooka token sesji, który zautoryzuje nam naszą aplikację. Token taki zostanie nam odesłany po zalogowaniu się użytkownika na adres jaki podaliśmy w stałej FB_APP_REDIRECT_URI (oraz na stronie aplikacji na Facebooku):
[code]// tworzymy helpera do zalogowania się
$helper = new FacebookRedirectLoginHelper(FB_APP_REDIRECT_URI);

Następnie za pomocą takiego helpera spróbujemy utworzyć obiekt sesji.
// Pobieramy token sesji
try {
  $session = $helper->getSessionFromRedirect();
  // Logowanie...
} catch(FacebookRequestException $ex) {
  // jeśli błąd Facebooka
} catch(\Exception $ex) {
  // jeśli ogólnie błąd
}[/code]
W kodzie powyżej pobieramy sesję z przekierowania zwrotnego, które zrobi do nas Facebook po zalogowaniu się użytkownika. Przekierowanie takie stworzymy za chwilę, na razie przeanalizujmy to co się tutaj dzieje. Do obiektu $session zwracane są informacje o sesji. Obiekt ten zostaje utworzony jedynie w momencie poprawnego zalogowania - fakt ten za chwilę pozwoli nam sprawdzić, czy użytkownik jest zalogowany do aplikacji, czy nie.
Całość kodu wyglądać więc będzie tak:
[code]<?php
// app.php

// dołączamy autoloader
require './vendor/autoload.php';

// startujemy sesję
session_start();

define('FB_APP_ID', '1234567891234567');
define('FB_APP_SECRET', 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx');
define('FB_APP_REDIRECT_URI', 'http://localhost/fb/app.php');

// deklarujemy używane przestrzenie nazw
use Facebook\Facebook;
use Facebook\FacebookSession;
use Facebook\FacebookRequest;
use Facebook\GraphUser;
use Facebook\FacebookRequestException;
use Facebook\FacebookRedirectLoginHelper;

// ustawiamy ID aplikacji i client secret
FacebookSession::setDefaultApplication(FB_APP_ID, FB_APP_SECRET);

// tworzymy helpera do zalogowania się
$helper = new FacebookRedirectLoginHelper(FB_APP_REDIRECT_URI);

// Pobieramy token sesji
try {
  $session = $helper->getSessionFromRedirect();
  // Logowanie...
} catch(FacebookRequestException $ex) {
  // jeśli błąd Facebooka
} catch(\Exception $ex) {
  // jeśli ogólnie błąd
}

if ($session) {
 
    // zalogowany
 
} else {

  // Link do logowania
  echo '<a href="'.$helper->getLoginUrl(array( 'email', 'user_friends' )).'">Login</a>';
}

?>[/code]
Jak widzimy na końcu, sprawdzamy, czy obiekt $session istnieje, jeśli tak, możemy działać dalej. Jeśli nie istnieje, to wyświetlamy link do logowania za pomocą:
[code]$helper->getLoginUrl(array( 'email', 'user_friends' ))[/code]
Metoda ta generuje nam link, który przekierowuje użytkownika na stronę Facebooka w celu zalogowania się do aplikacji.
Po zalogowaniu użytkownik jest z powrotem odsyłany tutaj, do naszej aplikacji. Jako argument podawana jest tutaj tablica z listą tzw. scope'a, czyli zasięgu danych do jakich dostęp chcemy uzyskać w naszej aplikacji. Przykładowo podaliśmy tutaj adres email i listę znajomych.

Wykorzystajmy teraz jakoś naszą aplikację, pobierając i wyświetlając dane zalogowanego użytkownika.
Aby otrzymać jakiekolwiek dane, utworzyć będziemy musieli obiekt Graph API, a robimy to następująco:
[code]
$request = new FacebookRequest($session, 'GET', '/me'); // tworzymy obiekt żądania do API
$response = $request->execute(); // pobieramy odpowiedź na żądanie do obiektu $response
$graphObject = $response->getGraphObject(); // pobieramy obiekt API z obiektu odpowiedzi[/code]
W wersji skróconej można to zrobić np. tak:
[code]
$user_profile = (new FacebookRequest(
  $session, 'GET', '/me'
))->execute()->getGraphObject(GraphUser::className());[/code]
Wyjaśnienie należy się obiektowi żądania:
[code]FacebookRequest($session, 'GET', '/me');[/code]
W przypadku tym, identyfikując się obiektem sesji, generujemy metodą GET żądanie o treści:
[code]/me[/code]
które zwraca w odpowiedzi informacje o zalogowanym użytkowniku. Możliwych żądań jest oczywiśie cała masa i omówimy sobie je w następnych artykułach. Wszystkie je będziemy preparować na podobnej zasadzie, otrzymując za ich pomocą wymagane przez nas dane. Na chwilę obecną zadowolimy się prostymi informacjami o użytkowniku. Wyświetlimy je sobie za pomocą var_dump():
[code]
// pobieramy profil zalogowanego użytkownika
$user_profile = (new FacebookRequest(
  $session, 'GET', '/me'
))->execute()->getGraphObject(GraphUser::className());  

// obiekt z danymi zalogowanego użytkownika:
var_dump($user_profile);[/code]

Całość naszego kodu, wyświetlająca te dane wyglądać będzie tak:
[code]
<?php
// app.php

// dołączamy autoloader
require './vendor/autoload.php';

// startujemy sesję
session_start();

define('FB_APP_ID', '1234567891234567');
define('FB_APP_SECRET', 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx');
define('FB_APP_REDIRECT_URI', 'http://localhost/fb/app.php');

// deklarujemy używane przestrzenie nazw
use Facebook\Facebook;
use Facebook\FacebookSession;
use Facebook\FacebookRequest;
use Facebook\GraphUser;
use Facebook\FacebookRequestException;
use Facebook\FacebookRedirectLoginHelper;

// ustawiamy ID aplikacji i client secret
FacebookSession::setDefaultApplication(FB_APP_ID, FB_APP_SECRET);

// tworzymy helpera do zalogowania się
$helper = new FacebookRedirectLoginHelper(FB_APP_REDIRECT_URI);

// Pobieramy token sesji
try {
  $session = $helper->getSessionFromRedirect();
  // Logowanie...
} catch(FacebookRequestException $ex) {
  // jeśli błąd Facebooka
} catch(\Exception $ex) {
  // jeśli ogólnie błąd
}

if ($session) {
 
  // Zalogowany
  echo 'Logged';

 // pobieramy profil zalogowanego użytkownika
 $user_profile = (new FacebookRequest(
    $session, 'GET', '/me'
  ))->execute()->getGraphObject(GraphUser::className());  

  // obiekt z danymi zalogowanego użytkownika:
  var_dump($user_profile);
 
} else {

  // Link do logowania
  echo '<a href="'.$helper->getLoginUrl(array( 'email', 'user_friends' )).'">Login</a>';
}
?>[/code]

Wynik:


Podsumowanie

Jak widzimy, udało nam się połączyć z API Facebooka, zalogować i pobrać podstawowe informacje o użytkowniku za pomocą SDK dla PHP. To oczywiście jedynie wstęp i wprowadzenie, ale pokazuje nam na jakiej mniej więcej zasadzie będzie wyglądać nasza praca z API Facebooka. W następnych artykułach omówimy sobie następne aspekty Graph API.

2 komentarze:

  1. Witam,
    Po wykonaniu skryptu otrzymuję w odpowiedzi jedynie tablicę dwu elementową, name oraz id.
    Gdzie może być błąd?

    Pozdrawiam

    OdpowiedzUsuń
  2. Robiłem na https://mbautodetailing.pl według tego poradnika. Działa, dzięki!

    OdpowiedzUsuń

Masz sugestię? Znalazłeś błąd? Napisz komentarz! :)

webmaester.pl - profesjonalne projektowanie WWW i webaplikacji
webmaester.pl - profesjonalne projektowanie WWW i webaplikacji