Sam Judson BT

Sumario

Quase todas as pessoas parecem estar envolvidas com Flickr nos dias de hoje; uma das mais novas modas dos aplicativos "Web 2.0" baseados na Web. Com o seu estilo agora bastante imitado, um layout social orientado a sistema de rede e o uso das mais novas tecnologias AJAX para fornecer ao usuário uma experiência verdadeiramente interativa, o Flickr define o futuro dos aplicativos na Internet. Além disso, um dos principais padrões de referência de um aplicativo "Web 2.0" (desculpe; é a última vez que utilizarei essa palavra) é a API pública já fornecida e que pode ser por nós usada para oferecer novos e interessantes modos de exibição e manipulação de fotos.

Nesta página

Introdução
Conceitos de Flickr API
Comece já a execução de Flickr
Autenticação
Carregamento de fotos
Conclusão

Introdução

A primeira coisa que mencionarei é que a finalidade deste artigo é o .NET 2.0, mas a biblioteca Flickr.Net API funciona tão bem quanto em .NET 1.1; por isso, não deixe que isso o atrapalhe. Também presumo que saiba como gravar aplicativos em .NET, utilizando o Visual Studio 2005 ou uma das edições gratuitas do Visual Studio 2005 Express. Estarei enfatizando principalmente os aplicativos Windows Forms, mas digo novamente que a biblioteca Flickr.Net API pode ser muito bem usada para aplicativos da Web, inclusive quando hospedados em um ambiente Medium Trust (consulte meu site da Web para obter mais detalhes sobre Medium Trust).

Também presumo que esteja familiarizado com o modo de utilização do Flickr e com o fato de ter uma conta lá. Caso contrário, OBTENHA UMA!

Obtenha uma Chave API

Para começar, você precisará obter uma API Key para usar com o Flickr. Você solicita novas chaves e as gerencia da seção Your Keys do site Flickr Services da Web em http://www.flickr.com/services/api/keys. A solicitação de uma nova chave deve ser uma ocorrência quase instantânea. Uma vez obtida a sua Chave API, você pode retornar para a mesma página e clicar no link Edit Configuration. Esse procedimento permite editar a descrição do uso de sua Chave API e mostrar a você o seu Shared Secret, de que precisará se desejar efetuar solicitações autenticadas a Flickr.

Ao executar os exemplos a seguir, você terá de substituir o exemplo da chave API pelo seu.

Obtenha a biblioteca Flickr.Net API

A biblioteca Flickr.Net API pode ser transferida por download do site Flickr.Net da Web. Existe também um fórum para enviar suas perguntas específicas de Flickr.Net (quando relacionadas a Flickr API em geral, é melhor enviá-las na lista de endereços de Flickr API).

O download contém o código-fonte para a biblioteca e as DLLs compiladas de depuração e de versão. Para fins deste artigo, utilizaremos a DLL de versão, mas você tem liberdade para adicionar o projeto de código-fonte diretamente à sua solução.

Conceitos de Flickr API

Neste ponto, vamos ver alguns conceitos e convenções de nomenclatura interessantes de Flickr API.

Usuários

Um usuário é exclusivamente identificado por sua User ID. Será algo parecido com "40123132@N01." No local onde houver referência a Username, terá o mesmo sentido que o seu Screen name - nome que é exibido na página inicial e que você pode alterar quando desejar. Isso nunca deveria ser armazenado em cache por seu aplicativo porque pode ser alterado a qualquer momento.

O termo final é o seu Alias ou a parte de seu Flickr URL que identificou você. Quando você cria uma conta, será o mesmo procedimento da sua User ID (essa URL sempre funcionará); você pode especificar um formato mais amigável para essa URL apenas uma vez.

Autenticação

Quando você autentica um usuário, o Flickr lhe fornece um Token. Esse token é exclusivo para a sua Chave API, para o usuário que você autenticou e para as permissões a você concedidas (por exemplo, somente leitura ou acesso de gravação). Ele permanecerá válido, desde que o usuário não cancele a sua autenticação, e você deveria teoricamente armazenar isso em cache dentro de seu aplicativo.

Uma vez autenticado o token, as chamadas de Flickr responderão como se fossem enviadas por esse usuário e mostrarão as fotos para as quais têm permissão e que outros podem não ter, como fotos particulares ou fotos de família e de amigos que foram assinaladas para serem exibidas para eles somente. Você também poderá modificar essas fotos e carregar novas fotos para a conta desse usuário.

Sem autenticação, você ainda pode fazer bastante coisa, como exibir todas as fotos públicas, procurar por fotos de usuários ou por marca, além de procurar grupos públicos.

Listas de fotos

Quando você executa uma pesquisa em Flickr, as fotos não serão exibidas todas de uma só vez, mas sim páginas de resultados. Por exemplo, se uma pesquisa normalmente apresenta 1.000 fotos, ela mostrará os detalhes das 100 primeiras fotos; em seguida, as próximas 100 e assim por diante, no total de 10 páginas. É possível especificar o tamanho da página (o número de fotos a serem exibidas de cada vez) e o número de páginas a serem mostradas; por exemplo, se você definir o tamanho da página (ou a propriedade PerPage) como 500, serão exibidas somente 2 páginas. Na maioria dos casos, 500 é o número máximo, mas verifique na documentação do Flickr API para obter mais informações sobre o método em questão e o que ele oferece.

Comece já a execução de Flickr

Crie uma instância de Flickr

Primeiro, vamos criar um objeto Flickr simples, passando a sua chave API anteriormente obtida.

Visual C#

string apikey = "1234abcd1234abcd";
Flickr flickr = new Flickr(apikey);
			

Visual Basic

Dim apikey As String = "1234abcd1234abcd"
Dim f As Flickr = New Flickr(apikey)
			

Nessa instância do objeto Flickr, você pode efetuar pesquisas, procurar grupos, localizar usuários e executar as etapas necessárias para autenticação de um usuário (desde que você forneça o Shared Secret também).

Localize as fotos

A linha de código a seguir pesquisa todas as fotos Flickr para localizar àquelas com a marca "microsoft":

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)
			

A classe PhotoSearchOptions é o modo mais fácil e mais flexível de pesquisa de fotos. Muitas de suas propriedades são opcionais, mas abrange todas as opções disponíveis para a função de pesquisa complexa, inclusive UserId, Tags e SortOrder.

A classe Photos contém uma seleção de propriedades, algumas das quais podem não ser imediatamente óbvias. Conforme anteriormente mencionado, quando você efetua uma pesquisa em Flickr, o resultado é exibido em forma de página. Por padrão, uma página apresentará 100 fotos, e a pesquisa anterior mostrará as 100 primeiras fotos (ou menos quando houver menos quantidade) para a pesquisa especificada. A opção Photos.TotalPhotos fornecerá o número total de fotos disponíveis na pesquisa atual, enquanto a opção Photos.TotalPages fornecerá o número de páginas necessárias para que todas as fotos disponíveis sejam mostradas. Ao modificar a propriedade Page da classe PhotoSearchOptions, você poderá exibir mais páginas de Flickr.

O código a seguir mostra a segunda e a terceira páginas de resultados de Flickr para a pesquisa acima mencionada:

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)
			

A classe Photos também contém uma propriedade PhotoCollection, que é onde se encontram as fotos. É possível adicionar objetos PhotoCollection simultaneamente para juntar uma ou mais páginas de resultados. Também é possível utilizar a instrução foreach para fazer um loop por todas as fotos da coleção.

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
			

Localize um usuário e suas fotos

Para localizar um usuário, é preciso pesquisar nos nomes das telas ou na URL da página inicial (ou usar a autenticação, que abordaremos mais adiante). Se você tiver o nome da tela de um usuário (por exemplo, "Sam Judson"), os códigos a seguir lhe fornecerão a User ID desse usuário.

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
			

Essa ID de usuário pode ser usada para pesquisar as fotos, opções favoritas, grupos, contatos desse usuário, e assim por diante. (Peço desculpas a meus fãs britânicos por utilizar a palavra favorite na ortografia americana por toda a API, mas o culpado é o Flickr e não eu:-)

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)
			

Eu poderia ficar aqui sentado o dia inteiro e listar cada método na API, mas basicamente se já consta de Flickr API, também encontra-se disponível na biblioteca .Net, e o nome do método será o mesmo que o método Flickr, mas sem os pontos finais e o bit flickr no início. Por exemplo, "flickr.people.getPublicGroups" é "PeopleGetPublicGroups" na Biblioteca Flickr.Net API.

Autenticação

Esta é talvez a parte mais complexa de qualquer aplicativo (pelo menos em termos de interação com Flickr); sendo assim, abordaremos esse tópico passo a passo. O aplicativo mostrado como exemplo no final terá uma implementação completa da autenticação da área de trabalho nele. A autenticação baseada na Web é ligeiramente diferente e é abordada no final.

Obtenha o Frob

Frob? O que é? Não estou bem certo quanto ao significado da palavra Frob, mas basicamente é uma chave temporária que você pode passar para o Flickr, que depois solicitará ao usuário para autenticar seu aplicativo. Uma vez autenticado, você pode utilizar esse mesmo Frob para obter o Authentication Token e a User ID do usuário autenticado (eu disse que voltaríamos a falar sobre esse assunto).

Diga ao usuário aonde ir

Após obter o Frob, é preciso passá-lo, junto com a sua Chave API e as permissões necessárias para executar Flickr, em uma URL assinada. Felizmente, a biblioteca possui um método que efetua a assinatura para você e retorna a URL para onde redirecionar o usuário. Contudo, você precisará conhecer seu Shared Secret (consulte o item "Obtenha uma chave API" acima mencionado, se ainda não tiver o seu segredo compartilhado) para calcular essa URL.

Código de exemplo

Imagine que você tenha dois botões em um formulário. O primeiro lê-se Authenticate Me e o segundo, Complete Authentication. O código a seguir ilustra o código por trás do formulário para os dois botões autenticarem um usuário para permissões de leitura/gravação.

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

			

Como você pode ver, se o usuário não o autenticar, o método AuthGetToken exibe uma exceção que pode ser usada para lidar com essa situação.

Agora você possui autenticação

Uma vez autenticado e com o Token do usuário, duas coisas podem ocorrer. Primeiro, você pode chamar novos métodos somente disponíveis quando estiver autenticado, como Flickr.PhotosSetTags(), que ativa as marcas para uma determinada foto do usuário autenticado. E também pode agora carregar fotos para a conta do usuário em questão.

Em segundo lugar, porém, alguns métodos serão executados de modo ligeiramente diferente. Por exemplo, a pesquisa acima de fotos em busca da marca "microsoft" exibirá quaisquer fotos particulares desse usuário que possua tal marca, além de suas fotos públicas e das fotos públicas de outros usuários com a marca.

A definição do token também pode ser feita no estágio do construtor, ou posteriormente.

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
			

Autenticação na Web? É diferente como?

Para efetuar a autenticação na Web, é preciso especificar na página Edit Configuration da sua chave API a página para onde deseja redirecionar os usuários após terem autenticado seu aplicativo. É denominado Callback URL. Também não é preciso criar um Frob quando estiver usando a autenticação baseada na Web.

Você pode utilizar o método Flickr.AuthCalcWebUrl para gerar uma URL para onde redirecionar o usuário.

Visual C#

string url = flickr.AuthCalcWebUrl(AuthLevel.Write);
Response.Redirect(url);

			

Visual Basic

Dim url As String = f.AuthCalcWebUrl(AuthLevel.Write)
Response.Redirect(url)
			

Na página especificada pela URL de Retorno de Chamada (Callback URL) acima, você passou o Frob na seqüência de caracteres de consulta; por exemplo, se a sua Callback URL for http://example.com/flickr.aspx, o usuário será redirecionado para http://example.com/flickr.aspx?frob=1234abcd1234abcd.

Você pode utilizar o Frob para obter o token de autenticação como no exemplo acima:

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
			

Carregamento de fotos

Uma vez autenticado um usuário, você pode carregar uma foto para a conta dele.

Esse procedimento é bastante simples. Pode ser feito diretamente de um arquivo no disco rígido ou de um objeto 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)

			

O método possui parâmetros de definição do título, descrição e marcas da foto, e também se a foto é pública ou particular (três parâmetros booleanos opcionais não exibidos anteriormente).

Atualização de fotos

Uma vez carregadas algumas fotos, você pode desejar adicioná-las a um conjunto, a um grupo ou dois, atualizar a descrição e/ou título ou ainda adicionar algumas marcas.

O código a seguir atualiza o título e a descrição da foto anteriormente carregada e a adiciona ao primeiro conjunto na lista de conjuntos do usuário.

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)
			

Conclusão

Como você pode ver, a mecânica real de comunicação com Flickr é relativamente simples. A parte difícil é a apresentação da idéia de um aplicativo novo e interessante.

Na segunda parte, desenvolverei um aplicativo baseado no artigo sobre Coding 4 Fun da WIA denominado Look at Me! Windows Image Acquisition, que você poderá usar para automaticamente carregar imagens quando se conectar a um dispositivo compatível com o seu computador.

Sou um desenvolvedor .NET que trabalha para a BT em Newcastle, Reino Unido. Nas minhas horas de folga, tiro inúmeras fotos, carrego-as para Flickr e gravo protetores de tela para exibi-las. Quando não estou usando o meu computador, gosto de tirar mais fotos ou de fazer escaladas em Northumberland ou em Lake District. Você pode ver minhas fotos em Flickr no site http://www.flickr.com/photos/samjudson e entrar em contato comigo via Channel9 Flickr.Net forum.