Dans mon précédent article (Créer une application facebook offline en utilisant l’api graph et le php-sdk), je vous montrais comment initier une connexion via oauth à Facebook et utiliser très brièvement l’API Graph en utilisant le php-sdk.
Je vais maintenant revenir sur l’API pour y faire des appels plus complexes (lecture/écriture, appels aux anciennes fonctions de l’API REST, et finalement une introduction au langage de requête FQL.
Repartons de notre script fetch.php. Si vous avez tout suivi, nous avions récupéré à la fin du premier article un access_token offline pour notre compte nous permettant de faire n’importe quel appel à facebook sans avoir à utiliser de navigateur web. Nous allons le réutiliser maintenant. Cependant, cela est totalement optionnel et nous pourrions également utiliser le token fournit par la session facebook (qui est fournit à la connexion et dont nous faisons l’utilisation dans le script online index.php).
Appels en lecture à l’API Graph
Comme nous l’avons vu à la fin du premier article, il nous était possible de faire des requêtes simples. La plus simple qui soit est un appel à /me:
$facebook = new Facebook(array(
'appId' => $app_id,
'secret' => $secret_key
));
$params = array(
'access_token' => $access_token
);
$res = $facebook->api( '/me', 'GET', $params );
print_r($res);
De la même façon, on pourra récupérer ses contacts en faisant un appel à ‘/me/friends’:
$res = $facebook->api( '/me/friends', 'GET', $params );
Imaginons maintenant qu’on veuille récupérer le status d’un de ses amis. Il suffit remplacer ‘me’ par l’id du contact en question, et au lieu d’appeler ‘friends’, le ‘status:
$res = $facebook->api( '/.. id du contact ../status', 'GET', $params );
Cependant, les permissions demandées précédemment (« offline_access » et « read_stream ») ne suffisent pas pour faire cet appel. Il existe un certain nombre de permissions étendues devant être demandées à l’utilisateur avant que l’application puisse avoir accès aux données. Ces permissions sont détaillées sur la page Extended Permissions de l’API. On notera qu’il faut des permissions différentes pour obtenir des informations personnelles relative à soit que des informations relative aux contacts. Ici, nous avons besoin de « friends_statuses » afin d’obtenir les status de ses amis. Pour rajouter une permission, il faudra modifier le script index.php qu’on a utilisé pour générer un access_token, pour générer un nouveau lien pour faire la demande sur Facebook.
On notera qu’il est possible de faire des appels à l’API pour la récupération de données publiques, et ce sans access_token valide (par exemple, l’appel à ‘/patrick.marie’ est possible par n’importe qui sans access_token valide).
Appels en écriture à l’API Graph
L’api graph facebook permet également de publier des données sur Facebook (status, commentaires, images, liens, évènements…). Les appels possibles sont décrits dans le paragraphe Publishing to Facebook de la référence de l’API. Les appels ne sont que très peu différents de l’appel en lecture seule.
Voici un exemple simple pour changer son status:
$params['message'] = 'Coucou';
$res = $facebook->api( '/me/feed', 'POST', $params );
On notera que pour cet appel il faudra obtenir la permission ‘publish_stream’. A partir de là, on pourra faire une recherche pour trouver des éléments à « liker »:
Selon la doc à propos des requètes de recherche (http://developers.facebook.com/docs/api#search), il faut juste faire une requète sur https://graph.facebook.com/search?q=QUERY&type=OBJECT_TYPE avec comme type possible ‘post’, ‘user’, ‘page’, ‘event’, ‘group’ ou ‘checkin’.
Faisons un rapide test. Je cherche une page sur les gauffres en forme de Texas:
$params = array('access_token' => $access_token, 'type' => 'page', 'q' => 'texas waffles' );
$res = $facebook->api( '/search', 'GET', $params );
foreach($res['data'] as $page)
{
print $page['id'] . ' -> ' . $page['name'] . "\n";
}
Maintenant, je vais chercher le ‘Coucou’ que j’ai posté précédemment pour le ‘liker’. Pour faire une recherche sur son feed, un appel à /me/home avec le paramètre ‘q’ suffit. Ensuite, un appel à /POST_ID/likes permettra de le liker:
$params = array('access_token' => $access_token, 'type' => 'post', 'q' => 'Coucou mon api' );
$res = $facebook->api( '/me/home', 'GET', $params );
foreach($res['data'] as $post)
{
if($post['from']['id'] == $me['id'])
{
print $post['message'] . "\n";
$params = array('access_token' => $access_token);
// like ...
$rep = $facebook->api( '/' . $post['id'] . '/likes', POST, $params );
}
}
Il est finalement possible d’effacer le like posé ou encore le post en question, grâce à la méthode DELETE ( http://developers.facebook.com/docs/api#deleting ):
// Effacer le like:
$rep = $facebook->api('/' . $postid . '/likes', DELETE, $params );
// Effacer le post:
$rep = $facebook->api('/' . $postid, DELETE, $params);
On notera qu’il n’est pas encore possible de poster ou de ‘liker’ n’importe quoi ou n’importe où. J’en ai fais les frais quand je voulais liker automatiquement la page des gauffres ;-(
Utilisation des fonctions de l’API REST
Avant l’apparition en Mai de l’API Graph, il existait une autre API basée sur REST qui est encore maintenue aujourd’hui. Cette API est encore décrite sur le site de facebook. (http://developers.facebook.com/docs/reference/rest/). Il est intéressant de parler de cette API car même si elle semble être désuète par rapport à l’API Graph, je la trouve toujours indispensable grâce à tous les appels non encore supporté par la nouvelle API, comme par exemple les requêtes FQL que nous verrons dans le paragraphe final.
On fait appel à ces fonctions toujours grâce à la fonction api() de l’api, mais de façon légèrement différente:
$request = array(
'method' => 'friends.get',
'access_token' => $access_token
);
$res = $facebook->api($request);
// ...
// ou encore, en utilisant users.getInfo (http://developers.facebook.com/docs/reference/rest/users.getInfo):
$request = array(
'method' => 'users.getInfo',
'uids' => '4',
'fields' => 'first_name, last_name',
'access_token' => $access_token
);
$res = $facebook->api($request);
var_dump($res);
/*
array(1) {
[0]=>
array(3) {
["first_name"]=>
string(4) "Mark"
["last_name"]=>
string(10) "Zuckerberg"
["uid"]=>
string(1) "4"
}
}
*/
Merci Mark pour cette rapide participation à la démo !
Mais la principale utilisation que je vois de cette ancienne API est encore l’utilisation de la méthode fql.query.
Utilisation de l’API FQL
Un mécanisme puissant de facebook est l’utilisation du Facebook Query Language. En quelques mots, les tables FQL permettent d’accéder aux données facebook auxquelles on a accès comme si l’on tappait dans une base de données en langage SQL.
Il y a dans Facebook un grand nombre de tables accessibles: les utilisateurs, les groupes, pages, amis, etc…
Lançons quelques requêtes prises au hasard dans l’API:
$query = 'SELECT uid, name FROM user WHERE uid = me()';
$request = array(
'method' => 'fql.query',
'query' => $query,
'access_token' => $access_token);
$res = $facebook->api( $request );
if(count($res))
{
$uid = $res[0]['uid'];
$name = $res[0]['name'];
echo "My name is " . $name . " (#" . $uid . ")\n";
}
// Retourne:
// My name is Patrick Marie (#615214609)
On pourra se balader dans les exemples proposés. Un autre sera de récupérer les derniers status de ses contacts, ou encore les derniers posts de sa page:
$ts = time() - (7 * 24 * 60 * 60);
$r = fql($access_token, 'SELECT uid,status_id,message FROM status WHERE uid IN (SELECT uid2 FROM friend WHERE uid1=' . $uid . ') AND time > ' . $ts . ';');
/* ... */
$r = fql($access_token, 'SELECT message FROM stream WHERE source_id = ' . $uid);
/* ... */
Voilà, c’est la fin de cette courte présentation de l’API, sachant que même si la documentation semble exhaustive maintenant, ce ne fut pas toujours le cas et qu’elle m’a donné quelques fois pas mal de travail pour comprendre le pourquoi du comment.
