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 方法的每个调用传递一个“后处理”块。这有两个好处:
-
你可以修改 Graph API 方法返回的结果:
education = @graph.get_object("me") { |data| data['education'] } # 返回的值只包含配置文件中的 "education" 部分
-
你可以就地消费数据,这在批量情况下特别有用,这样你就不需要从长列表的数组条目中拉取结果:
@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. 项目安装方式
请参考“安装指南”部分的内容进行项目安装。
鸿蒙开发工具大赶集
本仓将收集和展示鸿蒙开发工具,欢迎大家踊跃投稿。通过pr附上您的工具介绍和使用指南,并加上工具对应的链接,通过的工具将会成功上架到我们社区。012hertz
Go 微服务 HTTP 框架,具有高易用性、高性能、高扩展性等特点。Go01每日精选项目
🔥🔥 每日精选已经升级为:【行业动态】,快去首页看看吧,后续都在【首页 - 行业动态】内更新,多条更新哦~🔥🔥 每日推荐行业内最新、增长最快的项目,快速了解行业最新热门项目动态~~029kitex
Go 微服务 RPC 框架,具有高性能、强可扩展的特点。Go00Cangjie-Examples
本仓将收集和展示高质量的仓颉示例代码,欢迎大家投稿,让全世界看到您的妙趣设计,也让更多人通过您的编码理解和喜爱仓颉语言。Cangjie058毕方Talon工具
本工具是一个端到端的工具,用于项目的生成IR并自动进行缺陷检测。Python040PDFMathTranslate
PDF scientific paper translation with preserved formats - 基于 AI 完整保留排版的 PDF 文档全文双语翻译,支持 Google/DeepL/Ollama/OpenAI 等服务,提供 CLI/GUI/DockerPython06mybatis-plus
mybatis 增强工具包,简化 CRUD 操作。 文档 http://baomidou.com 低代码组件库 http://aizuda.comJava03国产编程语言蓝皮书
《国产编程语言蓝皮书》-编委会工作区018- DDeepSeek-R1探索新一代推理模型,DeepSeek-R1系列以大规模强化学习为基础,实现自主推理,表现卓越,推理行为强大且独特。开源共享,助力研究社区深入探索LLM推理能力,推动行业发展。【此简介由AI生成】Python00
热门内容推荐
最新内容推荐
项目优选









