Flickr avec .NET
Paru le 20 juillet 2006
Par Sam Judson, BT
Consultez cet article en anglais .gif "Bb736725.us(fr-fr,MSDN.10).gif")
Sur cette page
Démarrage
Concepts de l'API Flickr
En avant Flickr
Authentification
Téléchargement de photos
Conclusion
Tout un chacun semble aujourd'hui se pencher sur Flickr, l'une des nouvelles modes des applications « Web 2.0 ». Avec son style désormais beaucoup imité, sa disposition orientée réseau et son utilisation des technologies AJAX les plus récentes pour offrir à l'utilisateur un environnement réellement interactif, Flickr définit la norme pour les futures applications sur Internet. L'une des principales références d'une application « Web 2.0 » (promis, c'est la dernière fois que j'utiliserai ce terme) est en outre l'API publique fournie et qui peut être utilisée par chacun pour proposer des moyens nouveaux et intéressants d'afficher et de manipuler des photos.
Démarrage
Précisons tout d'abord que cet article concerne .NET 2.0, mais la bibliothèque API Flickr.Net fonctionne aussi bien dans .NET 1.1, donc cela ne doit pas vous arrêter. Je suppose également que vous savez comment écrire des applications dans .NET, en utilisant Visual Studio 2005 ou l'une des versions gratuites de Visual Studio 2005 Express. Je vais me concentrer essentiellement sur les applications Windows Forms, mais une fois de plus, la bibliothèque API Flickr.Net peut être utilisée aussi bien pour les applications Web, y compris celles hébergées dans un environnement Medium Trust (voir mon site Web pour plus d'informations sur Medium Trust).
Je suppose également que vous êtes familiarisé avec l'utilisation de Flickr et que vous possédez un compte. Si ce n'est pas le cas, créez-en un !
Obtenir une clé API
Pour commencer, vous aurez besoin d'une clé API à utiliser avec Flickr. Vous pouvez obtenir de nouvelles clés et gérer vos clés via la section Your Keys du site Web Flickr Services à l'adresse http://www.flickr.com/services/api/keys. La demande d'une nouvelle clé doit être quasi instantanée. Une fois la clé API obtenue, vous pouvez revenir à la même page et cliquer sur le lien Edit Configuration. Cela vous permet de modifier la description de l'utilisation de votre clé API et de voir votre secret partagé (Shared Secret), dont vous aurez besoin si vous souhaitez adresser des demandes authentifiées à Flickr.
Lors de l'exécution des exemples ci-dessous, vous devrez remplacer l'exemple de clé API par votre propre clé.
Obtenir la bibliothèque API Flickr.Net
La bibliothèque API Flickr.Net peut être téléchargée sur le site Web Flickr.Net. Il existe également un forum pour la publication de vos questions concernant Flickr.Net (si elles sont liées à l'API Flickr en général, il est préférable de les publier sur la liste de distribution Flickr API).
Le téléchargement contient le code source de la bibliothèque, ainsi que des DLL de débogage et de publication compilées. Pour les besoins de cet article, nous allons utiliser la DLL publiée, mais vous pouvez parfaitement ajouter le projet de code source directement à votre solution.
Concepts de l'API Flickr
L'API Flickr présente un certain nombre de concepts et de conventions d'appellation qu'il est utile de rappeler.
Utilisateurs
Un utilisateur est identifié de manière unique par son ID utilisateur. Cet ID ressemble à « 40123132@N01 ». S'agissant du Nom d'utilisateur, il est identique à votre Nom d'affichage, c'est-à-dire le nom qui s'affiche sur votre page d'accueil et que vous pouvez changer à tout moment. Il ne doit jamais être mis en cache par votre application, car il peut être modifié à tout moment.
Le dernier terme est votre alias, ou la partie de votre URL Flickr qui vous identifie. Lorsque vous créez un compte, l'alias est identique à votre ID utilisateur (cette URL fonctionnera toujours) ; vous ne pouvez spécifier un format plus convivial pour cette URL qu'une seule fois.
Authentification
Lorsque vous authentifiez un utilisateur, Flickr vous donne un jeton. Ce jeton est unique pour votre clé API, pour l'utilisateur que vous avez authentifié et pour les autorisations qui vous sont données (par exemple, lecture seule ou accès en écriture). Ce jeton reste valide tant que l'utilisateur n'a pas révoqué votre authentification et vous devez idéalement le mettre en cache dans votre application.
Une fois authentifiés, les appels de Flickr répondent comme s'ils étaient envoyés par cet utilisateur et affichent les photos que cet utilisateur peut voir et que les autres ne peuvent pas voir, par exemple les photos privées ou les photos des amis et de la famille, marquées comme visibles par eux uniquement. Vous pourrez également modifier leurs photos et télécharger de nouvelles photos vers leur compte.
Sans authentification, vous pouvez quand même faire un certain nombre de choses, par exemple afficher toutes les photos publiques, rechercher des photos par utilisateur ou par balise et parcourir les groupes publics.
Listes de photos
Lorsque vous effectuez une recherche sur Flickr, il est fréquent que toutes les photos ne soient pas renvoyées en une fois, mais sur plusieurs pages. Par exemple, si une recherche doit renvoyer 1000 photos, elle renverra les détails des 100 premières photos, puis les 100 suivantes et ainsi de suite sur 10 pages. Vous pouvez souvent spécifier la taille de la page (c'est-à-dire le nombre de photos à renvoyer sur chaque page) et le nombre de pages à renvoyer ; par exemple, si vous définissez la taille de la page (propriété PerPage) sur 500, seules 2 pages seront renvoyées. Dans la plupart des cas, 500 est le maximum, mais vous pouvez examiner la documentation de l'API Flickr afin de voir les valeurs prises en charge par une méthode donnée.
En avant Flickr
Créer une instance de Flickr
Créons d'abord un objet Flickr simple, en transmettant la clé API obtenue ci-dessus.
Visual C#
string apikey = "1234abcd1234abcd";
Flickr flickr = new Flickr(apikey);
Visual Basic
Dim apikey As String = "1234abcd1234abcd"
Dim f As Flickr = New Flickr(apikey)
À partir de cette instance de l'objet Flickr, vous pouvez effectuer des recherches, parcourir des groupes, trouver des utilisateurs et effectuer les opérations nécessaires pour authentifier un utilisateur (sous réserve que vous fournissiez également le secret partagé).
Rechercher des photos
La ligne de code suivante recherche toutes les photos Flickr avec la balise « microsoft » :
Visual C#
PhotoSearchOptions searchOptions = new PhotoSearchOptions();
searchOptions.Tags = "microsoft";
Photos microsoftPhotos = flickr.PhotosSearch(searchOptions);
Visual Basic
Dim searchOptions As PhotoSearchOptions = New PhotoSearchOptions()
searchOptions.Tags = "microsoft"
Dim microsoftPhotos As Photos = f.PhotosSearch(searchOptions)
La classe PhotoSearchOptions est le moyen le plus facile et le plus souple de rechercher des photos. Nombre de ses propriétés sont facultatives, mais elle couvre toutes les options disponibles pour la fonction de recherche complexe, notamment UserId, Tags et SortOrder.
La classe Photos contient une sélection de propriétés, dont certaines ne sont pas forcément immédiatement évidentes. Comme nous l'avons vu précédemment, lorsque vous effectuez une recherche sur Flickr, le résultat est divisé en pages. Par défaut, une page contient 100 photos et la recherche ci-dessus renvoie les 100 premières photos (ou moins s'il y en a moins) pour la recherche spécifiée. Photos.TotalPhotos donne le nombre total de photos disponibles pour la recherche en cours, tandis que Photos.TotalPages indique le nombre de pages que vous devez renvoyer pour obtenir toutes les photos disponibles. En modifiant la propriété Page de la classe PhotoSearchOptions, vous pouvez renvoyer plus de pages à partir de Flickr.
Le code suivant renvoie les deuxième et troisième pages de résultats de Flickr pour la recherche ci-dessus :
Visual C#
searchOptions.Page = 2;
Photos microsoftPhotos2 = flickr.PhotosSearch(searchOptions);
searchOptions.Page = 3;
Photos microsoftPhotos3 = flickr.PhotosSearch(searchOptions);
Visual Basic
searchOptions.Page = 2
Dim microsoftPhotos2 As Photos = f.PhotosSearch(searchOptions)
searchOptions.Page = 3
Dim microsoftPhotos3 As Photos = f.PhotosSearch(searchOptions)
La classe Photos contient également une propriété PhotoCollection, où se trouvent les photos proprement dites. Vous pouvez ajouter des objets PhotoCollection afin de collecter une ou plusieurs pages de résultats. Vous pouvez également utiliser l'instruction foreach afin de boucler dans toutes les photos de la collection.
Visual C#
PhotoCollection allPhotos = microsoftPhotos.PhotoCollection;
allPhotos.AddRange(microsoftPhotos2.PhotoCollection);
allPhotos.AddRange(microsoftPhotos3.PhotoCollection);
foreach (Photo photo in allPhotos)
{
Console.Write("Photos title is " + photo.Title);
}
Visual Basic
Dim allPhotos As PhotoCollection = microsoftPhotos.PhotoCollection
allPhotos.AddRange(microsoftPhotos2.PhotoCollection)
allPhotos.AddRange(microsoftPhotos3.PhotoCollection)
For Each p As Photo In allPhotos
Console.Write("Photos title is " & p.Title)
Next For
Rechercher un utilisateur et ses photos
Pour trouver un utilisateur, vous devez rechercher son nom d'affichage ou l'URL de sa page d'accueil (ou utiliser l'authentification, comme nous le verrons plus loin). Si vous avez le nom d'affichage d'un utilisateur (par exemple « Sam Judson »), le code suivant vous permet d'obtenir son ID utilisateur
Visual C#
string screenName = "Sam Judson";
FoundUser user = flickr.PeopleFindByUsername(screenName);
string userId = user.UserId;
Visual Basic
Dim screenName As String = "Sam Judson"
Dim user As FoundUser = f.PeopleFindByUsername(screenName)
Dim userId As String = user.UserId
Cet ID utilisateur peut ensuite être utilisé pour rechercher les photos, favoris, groupes, contacts, etc. de cet utilisateur.
Visual C#
// First page of the users photos
// Sorted by interestingness
PhotoSearchOptions userSearch = new PhotoSearchOptions ();
userSearch.UserId = userId;
userSearch.Sort = SortOrder.InterestingnessAsc;
Photos usersPhotos = flickr.PhotosSearch(userSearch);
// Get users contacts
Contacts contacts = flickr.ContactsGetPublicList(userId);
// Get first page of a users favorites
Photos usersFavoritePhotos = flickr.FavoritesGetPublicList(userId);
// Get a list of the users groups
PublicGroupInfo[] usersGroups = flickr.PeopleGetPublicGroups(userId);
Visual Basic
' First page of the users photos
' Sorted by interestingness
Dim userSearch As PhotoSearchOptions = New PhotoSearchOptions()
userSearch.UserId = userId
userSearch.Sort = SortOrder.InterestingnessAsc
Dim usersPhotos As Photos = flickr.PhotosSearch(userSearch)
' Get users contacts
Dim contacts As Contacts = flickr.ContactsGetPublicList(userId)
' Get first page of a users favorites
Dim usersFavoritePhotos As Photos = flickr.FavoritesGetPublicList(userId)
' Get a list of the users groups
Dim usersGroups As PublicGroupInfo() = flickr.PeopleGetPublicGroups(userId)
Je pourrais passer la journée à répertorier toutes les méthodes de l'API, mais pour l'essentiel, ce que contient l'API Flickr se trouve également dans la bibliothèque .Net, et le nom de la méthode est le même que celui de la méthode Flickr, sans les points et sans le mot flickr au début. Par exemple, « flickr.people.getPublicGroups » est équivalent à « PeopleGetPublicGroups » dans la bibliothèque d'API Flickr.Net.
Authentification
Il s'agit probablement de la partie la plus complexe de toute application (du moins en termes d'interaction avec Flickr) ; nous allons donc procéder étape par étape. L'exemple d'application proposé à la fin comporte une implémentation complète de l'authentification de poste de travail. L'authentification Web est légèrement différente et est traitée à la fin.
Obtenir le Frob
Frob ? Qu'est-ce donc ? Je ne suis pas certain de la signification du mot Frob, mais il s'agit essentiellement d'une clé temporaire que vous pouvez transmettre à Flickr et qui demande ensuite à l'utilisateur d'authentifier votre application. Une fois authentifié, vous pouvez utiliser ce même Frob pour obtenir le jeton d'authentification, ainsi que l'ID de l'utilisateur authentifié (je vous avais dit que j'y reviendrais).
Indiquer à l'utilisateur où aller
Une fois que vous avez le Frob, vous devez le transmettre à Flickr avec la clé API et les autorisations dont vous avez besoin, dans une URL signée. Heureusement, la bibliothèque possède une méthode qui effectue la signature pour vous et qui renvoie l'URL vers laquelle rediriger l'utilisateur. Vous devrez cependant connaître votre secret partagé (voir « Obtenir une clé API » ci-dessus si vous n'avez pas encore votre secret partagé) pour calculer cette URL.
Exemple de code
Imaginez que vous ayez deux boutons sur un formulaire. Le premier indique Authenticate Me et le deuxième Complete Authentication. Le code suivant illustre le code du formulaire pour les deux boutons permettant l'authentification d'un utilisateur pour les autorisations lecture/écriture.
Visual C#
using FlickrNet;
// Store the Frob in a private variable
private string tempFrob;
private string ApiKey = "1234abcd1234abcd1234";
private string SharedSecret = "abcd1234abcd";
protected void AuthMeButton_Click(object sender, EventArgs e)
{
// Create Flickr instance
Flickr flickr = new Flickr(ApiKey, SharedSecret);
// Get Frob
tempFrob = flickr.AuthGetFrob();
// Calculate the URL at Flickr to redirect the user to
string flickrUrl = flckr.AuthCalcUrl(tempFrob, AuthLevel.Write);
// The following line will load the URL in the users default browser.
System.Diagnostics.Process.Start(flickrUrl);
}
protected void CompleteAuthButton_Click(object sender, EventArgs e)
{
// Create Flickr instance
Flickr flickr = new Flickr(ApiKey, SharedSecret);
try
{
// use the temporary Frob to get the authentication
Auth auth = flickr.AuthGetToken(tempFrob);
// Store this Token for later usage,
// or set your Flickr instance to use it.
Console.WriteLine("User authenticated successfully");
Console.WriteLine("Authentication token is " + auth.Token);
flickr.ApiToken = auth.Token;
Console.WriteLine("User id is " + auth.UserId);
}
catch(FlickrException ex)
{
// If user did not authenticat your application
// then a FlickrException will be thrown.
Console.WriteLine("User did not authenticate you");
Console.WriteLine(ex.ToString());
}
}
Visual Basic
Imports FlickrNet
' Store the Frob in a private variable
Private tempFrob As String
Private ApiKey As String = "1234abcd1234abcd1234"
Private SharedSecret As String = "abcd1234abcd"
Private Sub AuthMeButton_Click(ByVal sender As Object, ByVal e As EventArgs)
' Create Flickr instance
Dim f As Flickr = New Flickr(ApiKey, SharedSecret)
' Get Frob
tempFrob = f.AuthGetFrob()
' Calculate the URL at Flickr to redirect the user to
Dim flickrUrl As String = f.AuthCalcUrl(tempFrob, AuthLevel.Write)
' The following line will load the URL in the users default browser.
System.Diagnostics.Process.Start(flickrUrl)
End Sub
Private Sub CompleteAuthButton_Click(ByVal sender As Object, ByVal e As EventArgs)
' Create Flickr instance
Dim f As Flickr = New Flickr(ApiKey, SharedSecret)
Try
' use the temporary Frob to get the authentication
Auth a = f.AuthGetToken(tempFrob)
' Store this Token for later usage,
' or set your Flickr instance to use it.
Console.WriteLine("User authenticated successfully")
Console.WriteLine("Authentication token is " & a.Token)
f.ApiToken = a.Token
Console.WriteLine("User id is " & a.UserId)
Catch ex As FlickrException
' If user did not authenticat your application
' then a FlickrException will be thrown.
Console.WriteLine("User did not authenticate you")
Console.WriteLine(ex.ToString())
End Try
End Sub
Comme vous pouvez le voir, si l'utilisateur ne vous authentifie pas, la méthode AuthGetToken génère une exception, laquelle peut être interceptée pour gérer cette situation.
Indiquer à l'utilisateur où aller
Une fois que vous êtes authentifié et que vous avez le jeton de l'utilisateur, deux choses peuvent se produire. Tout d'abord, vous pouvez à présent appeler de nouvelles méthodes qui ne sont disponibles qu'après l'authentification, par exemple Flickr.PhotosSetTags(), qui définit les balises d'une photo donnée de l'utilisateur authentifié. Vous pouvez également télécharger des photos vers le compte de cet utilisateur.
Ensuite, certaines méthodes s'exécutent maintenant un peu différemment. Par exemple, la recherche ci-dessus des photos avec la balise « microsoft » renvoie à présent les photos privées de cet utilisateur avec cette balise, ainsi que ses photos publiques et les photos publiques des autres utilisateurs avec la balise.
La définition du jeton peut également être effectuée au niveau du constructeur, ou ultérieurement.
Visual C#
Flickr flickr = new Flickr(ApiKey, SharedSecret, AuthToken);
// or
flickr.ApiToken = newToken;
Visual Basic
Dim f As Flickr = New Flickr(ApiKey, SharedSecret, AuthToken)
' or
f.ApiToken = newToken
Authentification Web ? Différente en quoi ?
Pour l'authentification Web, vous devez spécifier dans la page Edit Configuration de votre clé API la page vers laquelle rediriger les utilisateurs après leur authentification auprès de votre application. Cette page est appelée URL de rappel Vous n'avez pas non plus besoin de créer un Frob lors de l'utilisation de l'authentification Web.
Vous pouvez utiliser la méthode Flickr.AuthCalcWebUrl pour générer une URL vers laquelle rediriger l'utilisateur.
Visual C#
string url = flickr.AuthCalcWebUrl(AuthLevel.Write);
Response.Redirect(url);
Visual Basic
Dim url As String = f.AuthCalcWebUrl(AuthLevel.Write)
Response.Redirect(url)
Dans la page spécifiée par l'URL de rappel ci-dessus, le Frob est transmis dans la chaîne de requête ; par exemple, si votre URL de rappel est http://example.com/flickr.aspx, l'utilisateur est redirigé vers http://example.com/flickr.aspx?frob=1234abcd1234abcd.
Vous pouvez ensuite utiliser le Frob pour obtenir le jeton d'authentification, comme dans l'exemple ci-dessus :
*
Visual C#
protected void Page_OnLoad(object sender, EventArgs e)
{
string frob = Request.QueryString["frob"];
Flickr flickr = new Flickr(ApiKey, SharedSecret);
Auth auth = flickr.AuthGetToken(frob);
// Store the token somewhere for later calls
}
Visual Basic
Protected Sub Page_Load(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Load
Dim frob As String = Request.QueryString("frob")
Dim f As Flickr = New Flickr(ApiKey, SharedSecret)
Dim a As Auth = f.AuthGetToken(frob)
' Store the token somewhere for later calls
End Sub
Téléchargement de photos
Une fois que vous avez authentifié un utilisateur, vous pouvez télécharger une photo vers son compte.
Cette opération est simple. Elle peut être effectuée soit directement à partir d'un fichier du disque dur, soit via un objet Stream
Visual C#
string file = "test.jpg";
string title = "Test Photo";
string descripton = "This is the description of the photo";
string tags = "tag1,tag2,tag3";
string photoId = flickr.UploadPicture(file, title, dscription, tags);
Visual Basic
Dim file As String = "test.jpg"
Dim title As String = "Test Photo"
Dim descripton As String = "This is the description of the photo"
Dim tags As String = "tag1,tag2,tag3"
Dim photoId As String = f.UploadPicture(file, title, dscription, tags)
La méthode comporte des paramètres permettant de définir le titre, la description et les balises de la photo, ainsi que si la photo est publique ou privée (trois paramètres booléens facultatifs non illustrés ci-dessus).
Mettre à jour des photos
Une fois que vous avez téléchargé une photo, vous pouvez l'ajouter à un ensemble, l'ajouter à un ou deux groupes, ou encore mettre à jour la description, le titre ou ajouter des balises.
Le code suivant met à jour le titre et la description de la photo précédemment mise à jour, puis l'ajoute au premier ensemble dans la liste d'ensembles de l'utilisateur.
Visual C#
flickr.PhotosSetMeta(photoId, "New Title", "New Description");
// Get list of users sets Photosets sets = flickr.PhotosetsGetList();
// Get the first set in the collection
Photoset set = sets.PhotosetCollection[0];
// Add the photo to that set
flickr.PhotosetsAddPhoto(set.PhotosetId, photoId);
Visual Basic
f.PhotosSetMeta(photoId, "New Title", "New Description")
' Get list of users sets
Dim sets As Photosets = f.PhotosetsGetList();
' Get the first set in the collection
Dim set As Photoset = sets.PhotosetCollection(0)
' Add the photo to that set
f.PhotosetsAddPhoto(set.PhotosetId, photoId)
Conclusion
Comme vous pouvez le voir, les mécanismes de communication avec Flickr sont relativement simples. La partie la plus complexe arrive avec l'idée d'une nouvelle application sensationnelle.
Dans la deuxième partie de cette application, je vais développer une application basée sur l'article WIA Coding 4 Fun Regardez-moi ! Acquisition d'images Windows, que vous pouvez utiliser pour télécharger automatiquement des images lorsque vous connectez un périphérique compatible à votre ordinateur.
Je suis développeur .NET et je travaille pour BT à Newcastle, Royaume-Uni. Pendant mon temps libre, je prends beaucoup de photos, je les télécharge sur Flickr et j'écris des écrans de veille pour les afficher. Lorsque je ne suis pas devant mon ordinateur, je prend encore plus de photos et je fais de l'escalade à Northumberland ou Lake District. Vous pouvez voir mes photos Flickr à l'adresse http://www.flickr.com/photos/samjudson et me contacter via le forum Channel9 Flickr.Net ou via mon blog à l'adresse http://www.wackylabs.net/, ou encore envoyer un message électronique à sam@wackylabs.net.