Koala 项目技术文档

1. 安装指南

在 Bundler 中添加以下代码：

gem "koala"

或者使用以下命令安装：

[sudo|rvm] gem install koala

2. 项目的使用说明

Koala 是一个为 Ruby 开发的 Facebook 库，支持 Graph API、Marketing API、Atlas API、实时更新、测试用户和 OAuth 验证。使用 Koala 可以轻松地访问 Facebook 数据，并返回简单的 JSON 格式数据。

配置

大多数应用只需要使用一个应用配置。你可以在 Koala 中设置全局配置，这样就不需要每次都提供这些值：

# 在 Rails 中，你可以将以下代码放在 config/initializers/koala.rb 中
Koala.configure do |config|
  config.access_token = MY_TOKEN
  config.app_access_token = MY_APP_ACCESS_TOKEN
  config.app_id = MY_APP_ID
  config.app_secret = MY_APP_SECRET
  # 查看Koala::Configuration了解更多选项，包括如何通过自己的代理服务器发送请求的详细信息。
end

Graph API 使用

Graph API 是访问 Facebook 数据的接口。使用 Koala 访问 Graph API 非常简单。首先，你需要一个访问令牌，可以通过 Facebook 的 Graph API Explorer 获取。

然后，开始探索：

require 'koala'

# 如果像上面那样设置了默认值，就不需要 access_token 和其他值
@graph = Koala::Facebook::API.new(access_token)

profile = @graph.get_object("me")
friends = @graph.get_connections("me", "friends")
@graph.put_connections("me", "feed", message: "我正在我的墙上写东西！")

# 三部分查询也很简单！
@graph.get_connections("me", "mutualfriends/#{friend_id}")

# 你可以使用时间线 API：
# (查看 https://developers.facebook.com/docs/beta/opengraph/tutorial/)
@graph.put_connections("me", "namespace:action", object: object_url)

# 为了额外的安全性（推荐），你可以提供 appsecret 参数，
# 将你的访问令牌与你的应用密钥绑定。
# (查看 https://developers.facebook.com/docs/reference/api/securing-graph-api/)

# 在执行此操作时，你需要在你的应用设置的高级部分中启用“对所有调用都要求证明”。
@graph = Koala::Facebook::API.new(access_token, app_secret)

# Facebook 现在正在对他们的 API 进行版本控制。
# 如果你不指定版本，Facebook 将默认使用你的应用允许使用的最旧版本。
# 查看https://developers.facebook.com/docs/apps/versions 获取更多信息。
#
# 你可以全局指定版本：
Koala.config.api_version = "v2.0"
# 或者在每个请求的基础上指定版本
@graph.get_object("me", {}, api_version: "v2.0")

大多数请求的响应是来自 Facebook 服务器返回的 JSON 数据，格式为 Hash。

当检索返回数组结果的数据时（例如，当调用 API#get_connections 或 API#search），将返回一个 GraphCollection 对象，这使得轻松翻页成为可能：

# 返回当前登录用户的 feed 条目作为 GraphCollection
feed = @graph.get_connections("me", "feed")
feed.each { |f| do_something_with_item(f) } # 它是 Array 的子类
next_feed = feed.next_page

# 你也可以获取一个描述下一页 URL 的数组：[路径，参数]
# 这对于在多个浏览器请求之间存储页面状态非常有用
next_page_params = feed.next_page_params
page = @graph.get_page(next_page_params)

你也可以使用 Facebook 的批量 API 同时进行多个调用：

# 返回一个结果数组，就像它们是非批量调用一样
@graph.batch do |batch_api|
  batch_api.get_object('me')
  batch_api.put_wall_post('在一个批次中发布帖子。')
end

你可以为 Koala 的 Graph API 方法的每个调用传递一个“后处理”块。这有两个好处：

1. 你可以修改 Graph API 方法返回的结果：

    education = @graph.get_object("me") { |data| data['education'] }
    # 返回的值只包含配置文件中的 "education" 部分
   

2. 你可以就地消费数据，这在批量情况下特别有用，这样你就不需要从长列表的数组条目中拉取结果：

    @graph.batch do |batch_api|
      # 假设你有数据库字段 "about_me" 和 "photos"
      batch_api.get_object('me')                {|me|     self.about_me = me }
      batch_api.get_connections('me', 'photos') {|photos| self.photos   = photos }
    end
   

查看 wiki 获取更多细节和示例。

3. 项目 API 使用文档

Koala 提供了丰富的 API 用于与 Facebook 交互，以下是部分 API 的使用说明：

App Access Tokens

获取应用程序自己的访问令牌，可以在没有用户会话的情况下用于订阅和其他一些请求：

@oauth = Koala::Facebook::OAuth.new(app_id, app_secret, callback_url)
@oauth.get_app_access_token

对于在 Facebook 上构建应用程序的开发人员，解析签名请求非常简单：

@oauth.parse_signed_request(signed_request_string)

OAuth 类还有其他可能在某些情况下有用的方法。

实时更新

有时，主动调用 Facebook 是一件麻烦事——让它主动调用你吧。Graph API 允许你的应用程序订阅图中的某些对象的真实时更新；查看 官方 Facebook 文档 获取有关你可以订阅的对象以及可能应用的限制的更多信息。

Koala 使得使用 RealtimeUpdates 类与你的应用程序进行交互变得简单：

# 这个类也支持上面描述的默认设置
@updates = Koala::Facebook::RealtimeUpdates.new(app_id: app_id, secret: secret)

使用 RealtimeUpdates 类，你可以对你的实时更新订阅做几乎所有事情：

# 添加/修改对任何用户的 first_name 或 last_name 字段更改的更新订阅
@updates.subscribe("user", "first_name, last_name", callback_url, verify_token)

# 获取当前订阅的数组（每个你订阅的对象一个哈希）
@updates.list_subscriptions

# 从更新中取消订阅一个对象
@updates.unsubscribe("user")

RealtimeUpdates 类还提供了一个静态方法来响应 Facebook 服务器对你回调 URL 的验证：

# 如果 params 中的 verify_token 与 verify_token 匹配，则返回 params 中的 hub.challenge 参数
Koala::Facebook::RealtimeUpdates.meet_challenge(params, your_verify_token)

关于 meet_challenge 和 RealtimeUpdates 类的更多信息，请查看 wiki 上的实时更新页面。

测试用户

我们还支持测试用户 API，允许你创建虚拟用户并使用 Graph API 指挥他们按照你的意愿行动：

# 这个类也支持上面描述的默认设置
@test_users = Koala::Facebook::TestUsers.new(app_id: id, secret: secret)
user = @test_users.create(is_app_installed, desired_permissions)
user_graph_api = Koala::Facebook::API.new(user["access_token"])
# 或者，如果你想要创建一个社区：
@test_users.create_network(network_size, is_app_installed, common_permissions)

与 Facebook 通信

Koala 使用 Faraday 发送 HTTP 请求，这意味着你对应用程序如何向 Facebook 发送 HTTP 请求有完全的控制权。你可以在全局设置 Faraday 选项，或者在每次请求时传递它们（或两者都做）：

# 设置一个 SSL 证书以避免 Net::HTTP 错误
Koala.http_

...（此处省略部分内容，因为文章内容较多，可以根据实际需要继续补充）

4. 项目安装方式

请参考“安装指南”部分的内容进行项目安装。