English
资源说明：A small, yet powerful, gem to interface with Flickr photostreams
= Fleakr
== Description
A small, yet powerful, gem to interface with Flickr photostreams
== Installation
=== Stable
sudo gem install fleakr
=== Bleeding Edge
$ git clone git://github.com/reagent/fleakr.git
$ cd fleakr
$ rake gem && sudo gem install pkg/fleakr-.gem
== Usage
To get started, you'll need to grab an API key from Flickr to at least perform any of
the non-authenticated, read-only calls. Head on over to the Flickr site to grab one, I'll
be here when you get back: http://www.flickr.com/services/api/misc.api_keys.html
Now that you have your key, you can get things rolling with irb and the fleakr gem:
$ irb -r rubygems
>> require 'fleakr'
Then, set your API key (only need to do this once per session):
>> Fleakr.api_key = ''
=== A Brief Tour
With just an API key, you have the ability to retrieve a substantial amount of data
about users, their photosets, photos, contacts, and groups. Let's start by finding a
user by his username:
>> user = Fleakr.user('the decapitator')
=> #
By email:
>> user = Fleakr.user('user@host.com')
=> #
Or even by URL:
>> user = Fleakr.user('http://www.flickr.com/photos/the_decapitator/')
=> #
Once you have a user, you can find his associated sets:
>> user.sets
=> [#,
#> user.photos.first
=> #
Or contacts:
>> user.contacts.first
=> #
Or his groups if you would like:
>> user.groups
=> [#> user.groups.first.name
=> "Rural Decay"
>> user.groups.first.id
=> "14581414@N00"
Groups also contain photos:
>> user.groups.last.photos.first.title
=> "Welcome To The Machine"
When accessing a set, you can also grab all the photos that are in that set:
>> user.sets.first
=> #
>> user.sets.first.photos.first
=> #
>> user.sets.first.photos.first.title
=> "Untitled1"
=== Contacts
Besides pulling back a given user's public contacts list, you can also retrieve the list of
contacts for the currently authenticated user (see below about authentication). For example,
you can retrieve all contacts:
>> Fleakr.contacts
=> [#]
Or just the contacts marked as 'family':
>> Fleakr.contacts(:family)
=> [#]
Or a specific page of contacts marked as 'friends':
>> Fleakr.contacts(:friends, :page => 3, :per_page => 5)
=> [#]
See the documentation for Fleakr.contacts for what options are available.
=== Photos
Each photo object contains metadata about a collection of images, each representing different
sizes. Once we have a single photo:
>> photo = user.photos.first
=> #
We can get information about one of the sizes:
>> photo.small
=> #
Grab the URL for the image itself:
>> photo.small.url
=> "http://farm4.static.flickr.com/3250/2924549350_cbc1804258_m.jpg"
Or grab the URL for its page on the Flickr site:
>> photo.small.page
=> "http://www.flickr.com/photos/the_decapitator/2924549350/sizes/s/"
Other sizes are available (:square, :thumbnail, :small, :medium, :large, :original) and
are accessed in the same way:
>> photo.original.url
=> "http://farm4.static.flickr.com/3250/2924549350_1cf67c2d47_o.jpg"
=== Tags
Tags are available for users and photos. Retrieving them is easy:
>> user = Fleakr.user('the decapitator')
>> user.tags
=> [#,
#, ...
>> user.photos.first.tags
=> [#> tag = user.photos.first.tags.first
>> tag.id
=> "21729829-3263659141-427098"
>> tag.raw
=> "decapitator"
>> tag.value
=> "decapitator"
>> tag.to_s
=> "decapitator"
>> tag.machine?
=> false
>> tag.author
=> #
Each tag can also have related tags:
>> user.photos.first.tags[1].related.first.related.first.to_s
=> "face"
You get the idea - see Fleakr::Objects::Tag for more information.
=== Comments
Similar to tags, photosets and photos can each have comments:
>> user.sets.first.comments
=> [#> user.photos.first.comments
=> [#> comment = user.photos.first.comments.first
>> comment.id
=> "21729829-3263659141-72157613553885978"
>> comment.body
=> "Dayum, that's some wishful thinking!"
>> comment.to_s
=> "Dayum, that's some wishful thinking!"
>> comment.url
=> "http://www.flickr.com/photos/the_decapitator/3263659141/#comment72157613553885978"
>> comment.author
=> #
See Fleakr::Objects::Comment for more information.
=== Collections
An individual can have zero or more collections associated with his account. These collections,
in turn, can have either collections or sets associated with them. For example:
>> user = Fleakr.user('username')
>> user.collections.length
=> 1
>> user.collections.first.title
=> "The Year in Pictures"
>> user.collections.first.collections.length
=> 2
>> user.collections.first.collections.first.sets.length
=> 3
>> user.collections.first.collections.first.sets.first.title
=> "A Trip to Yosemite"
Note that collections are limited to Flickr pro members. See Fleakr::Objects::Collection for more
information.
=== Accessing Resources by URL
Sometimes you want to retrieve a person, set, or photo but you only have the public Flickr URL for
that entity. Retrieval is easy:
>> Fleakr.resource_from_url('http://www.flickr.com/people/reagent/')
=> #
This method also supports the retrieval of photos from a shortened Flickr URL:
>> Fleakr.resource_from_url('http://flic.kr/p/95Nr83')
=> #
=== Saving Images
If a photo interests you, save it down to a directory of your choosing:
>> photo.original.save_to('/tmp')
=> #
Similarly, you can save down entire sets. Just specify the target directory and the size
of the images you're interested in:
>> user.sets.first.save_to('/tmp', :square)
=> [#> Dir["/tmp/#{user.sets.first.title}/*.jpg"].map
=> ["/tmp/The Decapitator/01_2117922283_715587b2cb_s.jpg",
"/tmp/The Decapitator/02_2125604584_9c09348fd6_s.jpg",
"/tmp/The Decapitator/03_2118696542_8af5763bde_s.jpg", ... ]
=== Searching
If you would prefer to just search photos, you can do that with search text:
>> photos = Fleakr.search('ponies!!')
=> [#,
#, ...
>> photos.first.title
=> "hiroshima atomic garden"
You can also search based on tags:
>> photos = Fleakr.search(:tags => 'macro')
>> photos.first.title
=> "Demure"
>> photos.first.id
=> "3076049945"
Searches can also be scoped to other entities in the system (namely Users and Groups):
>> user.groups.first.search('awesome')
=> [#, ...
>> user.search('serpent')
=> [#]
=== Exif Data
Exif metadata can be retrieved for a photo:
>> photo = Fleakr::Objects::Photo.find_by_id('4507120023')
>> photo.metadata.keys
=> ["ImageSize", "Optical Zoom Mode", "RedBalance", "Y-Resolution", ... ]
>> photo.metadata['ImageSize']
=> "3264x2448"
You can iterate over the available elements and grab additional information:
>> photo.metadata.map {|k, e| "#{k} => '#{e.clean}'" }
=> ["Exposure => '0.003 sec (1/400)'", "Y-Resolution => '180 dpi'", ... ]
See the documentation for Fleakr::Objects::Metadata for information on what's available.
=== Uploading Files
Before you can upload files, you need to be able to make authenticated calls to the Flickr
API. Skip to the next section (Authenticated Calls) for details on how to make this work.
Uploading single files is simple:
>> Fleakr.upload('/path/to/image.jpg')
=> [#]
Notice that the newly-uploaded image is returned. You can further inspect / modify this as
necessary. The real magic is in uploading multiple files - the upload method takes a file
glob:
>> Fleakr.upload('/path/to/images/*.jpg')
=> [#,
#,
#]
You can also set options on the file(s) that you're uploading:
>> Fleakr.upload('/path/to/party/images/*.jpg', :viewable_by => :everyone,
:title => 'Party Pics')
The full list of options can be found in the Fleakr::Objects::Photo documentation.
=== Authenticated Calls
While read-only access to the API gets you quite a bit of data, you'll need to generate an
authentication token if you want access to the more powerful features (like uploading your
own photos).
Depending on how you intend to use the Flickr API, there are 2 methods for performing
authenticated calls.
=== Single User
You'll need to configure your API key to to use Mobile authentication. If you're viewing your
list of keys on the Flickr site, click on the 'Edit key details' link and ensure that:
1. Your application description and notes are up-to-date
1. The value for 'Authentication Type' is set to 'Mobile Application'
1. The value for 'Mobile Permissions' is set to either 'write' or 'delete'
Once this is set, you'll see your Authentication URL on the key details page (it will look
something like http://www.flickr.com/auth-534525246245). Paste this URL into your browser and
confirm access to get your mini-token. Now you're ready to configure your authentication token:
Fleakr.api_key = 'ABC123'
Fleakr.shared_secret = 'sekrit' # Available with your key details on the Flickr site
token = Fleakr.token_from_mini_token('294-585-410')
Fleakr.auth_token = token.value
Fleakr.upload('/path/to/my/photo.jpg')
Once you use the mini-token once it is no longer available. To use the generated auth_token
for future requests, you'll need to make sure that you set the value permanently:
Fleakr.auth_token = '72157622657341094-41241e527f325abb'
=== Multiple Users
If you need to have your application access other users photos on their behalf, you'll want to
use the Web authentication method. Edit your key details and make sure that:
1. Your application description and notes are up-to-date
1. The value for 'Authentication Type' is set to 'Web Application'
1. You configure your callback URL to point to something valid and accessible
Make sure that your key and secret are set as above. You can then begin the process by requesting
that the user authorize access to his Flickr account by redirecting to an authorization URL. I'm
assuming Rails conventions here, but this should work with any Ruby web framework:
redirect_to Fleakr.authorization_url
By default, we request read permission for access. This doesn't really do much more than what the
public API allows, so you can request different permissions when asking for authorization:
# The values :read, :write, and :delete are supported
redirect_to Fleakr.authorization_url(:delete)
One the user authorizes your application, he will be redirected back to your callback URL with a
frob parameter as part of the query string. You'll need to exchange this for a token:
token = Fleakr.token_from_frob(params[:frob])
The actual authentication token is available by calling token.value in the above
example. You'll want to store this value somewhere to make future API calls on behalf of this
user. To make that process easier, there is a method that you can use that will allow you to
automatically scope your requests to the authenticated user:
user = Fleakr.user_for_token('72157622657341094-41241e527f325abb')
From there, you can make any of the usual calls available with the API. See
Fleakr::Objects::User for more information.
=== What Went Wrong?
Because so much of the underlying API is hidden under the covers, it's often tough to know
what's really going on when you run into unexpected behavior. To make things easier, you can
have Fleakr log all of the API traffic. Here's how:
Fleakr.logger = Logger.new('/tmp/fleakr.log')
Now any calls to the API will log both their request and response data to that file. But be
warned, this can be pretty verbose by default (especially if you're doing file uploads). To see
just the requests you need to tune the log level:
logger = Logger.new('/tmp/fleakr.log')
logger.level = Logger::INFO
Fleakr.logger = logger
Even if something doesn't go wrong, this is a good way to get a sense for when you're making
API requests.
== Contributing
If there is a feature that you would like to contribute, I gladly accept pull requests. There
are a few things that make my life easier when integrating your changes:
* Verify that all tests are passing (run `rake` from the project root)
* Keep your commits small, focused, and tested - this allows me to apply changes cleanly
* Leave the Rakefile and version information intact - if you really want to make changes,
please do so in a separate commit.
Once your changes are applied, I will add you to the list of contributors.
== Contributors
While Fleakr started as a labor of love for me, I'm glad that others have been interested
in this project enough to contribute their ideas and code:
* {Gordon Anderson}[http://github.com/gordonbanderson]
* {Mark Dickson}[http://github.com/ideaoforder]
* {John Guenin}[http://github.com/johng]
* {Thomas Olausson}[http://github.com/latompa]
* {Robert Sköld}[http://github.com/slaskis]
* {Nathan Walls}[http://github.com/base10]
* {Björn Wolf}[http://github.com/we5]
Thanks!
== Roadmap / TODO
=== 0.5.x
* Implement remaining bits of person and photo-related API calls (read-only)
* Provide a better searching interface with ruby-like option syntax
=== Future
* Implement asynchronous file upload / replacement w/ ticket checking
* Implement save-able search results (e.g. Fleakr.search('ponies').save_to('/path', :medium))
* Implement deeper associations for core elements (e.g. tags / etc..)
* Implement write methods for photos & photosets
* Implement flickr.places.* portion of API
== License
Copyright (c) 2008 Patrick Reagan (reaganpr@gmail.com)
Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.
本源码包内暂不包含可直接显示的源代码文件，请下载源码包。
