Facebook Business SDK
项目描述
Facebook Business SDK for Python
简介
Facebook Business SDK 是一个一站式商店，旨在帮助我们的合作伙伴更好地服务他们的业务。合作伙伴正在使用多个 Facebook API 来满足其客户的需求。采用所有这些 API 并在各个平台上保持其更新可能非常耗时，最终可能具有阻碍性。因此，Facebook 开发了 Business SDK，将许多 API 打包成一个 SDK，以简化实施和维护。Business SDK 是 Marketing API SDK 的升级版，包括 Marketing API 以及来自不同平台（如页面、商务管理器、Instagram 等）的许多 Facebook API。
快速入门
Business SDK 入门指南
Python 是我们第三方开发者中最受欢迎的语言。 facebook_business 是一个 Python 包，它提供了一个接口，使您的 Python 应用程序与 Business SDK 中的 Facebook API 之间进行交互。本教程涵盖了使用 SDK 所需的基本知识，并为读者提供了一些练习。
注意: facebook_business 包与 Python 2 和 3 兼容！
先决条件
注册应用
要开始使用 SDK，您必须在 developers.facebook.com 上注册一个应用。
要管理营销API，请访问您的应用仪表板，并将营销API产品添加到您的应用中。
重要：出于安全考虑，建议您在应用的设置->高级页面中开启“服务器API调用应用密钥证明”。
获取访问令牌
当某人使用Facebook登录与应用连接并批准权限请求时，应用会获取一个访问令牌，该令牌提供临时、安全的访问Facebook API的权限。
访问令牌是一个不透明的字符串，用于标识用户、应用或页面。
例如，要访问营销API，您需要为您应用生成用户访问令牌并请求ads_management权限；要访问页面API，您需要为您应用生成页面访问令牌并请求manage_page权限。
有关更多信息，请参阅我们的访问令牌指南。
目前，我们可以使用图探索器来获取访问令牌。
安装包
最简单的方法是通过在您的shell中使用pip来安装SDK。
注意：对于Python 3，请使用pip3和python3。
注意：如果这些有关于权限的抱怨，请使用sudo（这可能会发生在您使用系统安装的Python时）。
如果您没有pip
easy_install pip
现在执行
pip install facebook_business
如果您在意的是最新的版本，而不是
python setup.py install
太好了，现在您可以开始使用SDK了！
启动
创建test.py
创建一个包含以下内容的test.py文件（假设您的系统正在使用python 2.7并且安装于/opt/homebrew。更新到您的正确python位置。）
import sys
sys.path.append('/opt/homebrew/lib/python2.7/site-packages') # Replace this with the place you installed facebookads using pip
sys.path.append('/opt/homebrew/lib/python2.7/site-packages/facebook_business-3.0.0-py2.7.egg-info') # same as above
from facebook_business.api import FacebookAdsApi
from facebook_business.adobjects.adaccount import AdAccount
my_app_id = 'your-app-id'
my_app_secret = 'your-appsecret'
my_access_token = 'your-page-access-token'
FacebookAdsApi.init(my_app_id, my_app_secret, my_access_token)
my_account = AdAccount('act_<your-adaccount-id>')
campaigns = my_account.get_campaigns()
print(campaigns)
测试您的安装
使用以下命令测试您的安装
python test.py
您应该在终端窗口中看到结果。如果它抱怨令牌已过期，请重复上述步骤中描述的请求页面访问令牌的过程。
注意：我们将在本教程的其余部分使用对象模块。您也可以直接使用adobjects下的单个类文件。
理解CRUD
SDK实现了CRUD（创建、读取、更新、删除）设计。与探索图相关的对象位于facebook_business包的对象模块中。
图上的所有对象都是AbstractObject的实例。某些对象可以直接查询，因此是AbstractCrudObject（AbstractObject的子类）的实例。这两个抽象类都位于facebook_business.adobjects中。
facebook_business下还有一个额外的文件夹adobjects。在这个文件夹下，您会看到我们营销API中每个广告对象的文件。这些文件是从我们的API自动生成的，因此与API提供的功能非常相似。根据每个对象可以执行哪些CRUD操作，您会在其中看到以下方法的存在
api_getapi_updateapi_deletecreate_xxxget_xxx
例如，Campaign具有所有这些方法，但AdAccount没有。阅读营销API文档以了解更多关于如何使用不同的广告对象的信息。
AbstractCrudObject中有些函数已被弃用，如
remote_createremote_readremote_updateremote_delete
请尽量停止使用它们，因为我们可能计划很快弃用它们。
探索图
SDK通过定义代表图上对象的类来抽象API。这些类定义及其辅助函数位于facebook_business.adobjects中。
初始化对象
查看 AbstractObject 和 AbstractCrudObject 的 __init__ 方法以获取更多信息。图上的大多数对象都是从这两个之一派生的。
在实例化广告对象时，如果您想要指定其id（如果已存在），可以在定义时使用 fbid 参数。另外，如果您想使用特定的api对象而不是默认的来与API交互，可以指定 api 参数。
边
查看对象的方法以了解我们可以迭代哪些关联。例如，一个 User 对象有一个名为 get_ad_accounts 的方法，该方法返回一个 AdAccount 对象的迭代器。
广告账户
大多数广告相关操作都是在广告账户的上下文中进行的。您可以通过访问 广告管理器 来查看您有权限的账户。你们大多数人可能都有一个个人账户。
让我们获取具有给定访问令牌的用户的全部广告账户。我只有一个账户，所以以下打印内容为
>>> from facebook_business.adobjects.user import User
>>> me = adobjects.User(fbid='me')
>>> my_accounts = list(me.get_ad_accounts())
>>> print(my_accounts)
[{ 'account_id': u'17842443', 'id': u'act_17842443'}]
>>> type(my_accounts[0])
<class 'facebook_business.adobjects.AdAccount'>
警告：我们在这里实例化 User 对象时没有指定关键字参数 api=api，因为我们已经在启动时设置了默认api。
注意：我们用 list() 包装 get_ad_accounts 的返回值，因为 get_ad_accounts 返回一个位于 facebook_business.adobjects 的 EdgeIterator 对象（边迭代器），而我们希望立即获取完整列表，而不是让迭代器懒加载账户。
对于我们的目的，我们可以选择一个账户，并在其上下文中进行实验
>>> my_account = my_accounts[0]
或者如果您已经知道您的账户id
>>> my_account = adobjects.AdAccount('act_17842443')
创建
让我们创建一个活动。这是在账户的上下文中，也就是说，它的父对象应该是账户。
fields = [
]
params = {
adobjects.Campaign.Field.name : 'Conversions Campaign',
adobjects.Campaign.Field.configured_status: adobjects.Campaign.Status.paused,
}
campaign = AdAccount(id).create_campaign(fields, params)
然后我们指定关于活动的某些细节。为了确定要定义哪些属性，您应该查看对象的可用字段（位于 Campaign.Field），并查看广告对象的文档（例如，活动）。
注意：要查找字段，请查看 adobjects 目录下的单个类文件。
如果发生错误，将引发异常。可能的异常及其描述列在 facebook_business.exceptions 中。
读取
假设对象已经创建并且有节点路径，我们可以从API读取对象的属性。由于 AbstractObject 实现了 collections.MutableMapping，访问对象的属性非常简单。您可以直接像访问字典的键一样访问它们
>>> print(my_account)
{'account_id': u'17842443', 'id': u'act_17842443'}
>>> my_account = my_account.api_get(fields=[adobjects.AdAccount.Field.amount_spent])
>>> print(my_account[adobjects.AdAccount.Field.amount_spent])
{'amount_spent': 21167, 'account_id': u'17842443', 'id': u'act_17842443'}
更新
要更新对象，我们可以修改其属性，然后调用 api_update 方法以将对象与服务器同步。让我们更正“Campain”到“Campaign”这个错误
>>> campaign.api_update(fields=[], params={adobjects.Campaign.Field.name:"Potato Campaign"})
您可以在广告管理器中看到结果。
删除
如果我们决定不再想要我们创建的活动
campaign.api_delete()
有用的参数
多个访问令牌
在整个文档中，在做出任何API调用之前，都会调用 FacebookAdsApi.init 方法。此方法设置一个默认的 FacebookAdsApi 对象，用于所有地方。这简化了使用，但在一个系统使用SDK代表多个用户进行调用时不可行。
这不可行的原因是每个用户都应该有自己的 FacebookSession，有自己的访问令牌，而不是每个用户都使用相同的会话。每个会话都应用于创建一个单独的 FacebookAdsApi 对象。请参见以下示例
my_app_id = '<APP_ID>'
my_app_secret = '<APP_SECRET>'
my_access_token_1 = '<ACCESS_TOKEN_1>'
my_access_token_2 = '<ACCESS_TOKEN_2>'
proxies = {'http': '<HTTP_PROXY>', 'https': '<HTTPS_PROXY>'} # add proxies if needed
session1 = FacebookSession(
my_app_id,
my_app_secret,
my_access_token_1,
proxies,
)
session2 = FacebookSession(
my_app_id,
my_app_secret,
my_access_token_2,
proxies,
)
api1 = FacebookAdsApi(session1)
api2 = FacebookAdsApi(session2)
在SDK示例中，我们始终设置一个FacebookAdsApi对象作为默认对象。但是，与多个access_tokens一起工作需要我们使用多个api。我们可能为用户设置一个默认api，但对于其他用户，我们应该使用其api对象作为参数。在以下示例中，我们创建了两个AdUsers，第一个使用默认api，第二个使用其api对象
FacebookAdsApi.set_default_api(api1)
me1 = AdUser(fbid='me')
me2 = AdUser(fbid='me', api=api2)
创建上述相同对象的另一种方法是
me1 = AdUser(fbid='me', api=api1)
me2 = AdUser(fbid='me', api=api2)
从这里开始，以下所有对这些对象的流程保持不变。唯一例外是类方法调用，我们现在应该在每次调用中将我们想要使用的API作为最后一个参数传递。例如，调用Aduser.get_by_ids方法应该是这样的
session = FacebookSession(
my_app_id,
my_app_secret,
my_access_token_1,
proxies,
)
api = FacebookAdsApi(session1)
Aduser.get_by_ids(ids=['<UID_1>', '<UID_2>'], api=api)
CRUD
所有CRUD调用都支持一个params关键字参数，它接受一个将参数名称映射到值的字典，以实现高级修改。您可以在{your object class}.Field的属性中找到参数名称列表。在Field类下可能有其他类，这些类作为属性包含，包含父属性值的一个有效字段。
api_update和create_xxx支持一个files关键字参数，它接受一个将文件引用名称映射到二进制打开文件对象的字典。
api_get支持一个fields关键字参数，这是一种指定'fields'参数的便捷方式。fields接受在调用期间应读取的字段列表。有效的字段可以找到在Field类的属性中。
边
当初始化一个EdgeIterator或调用AdAccount.get_ad_campaigns等方法时
- 您可以指定一个
fields参数，它接受一个要读取的对象的字段列表。 - 您可以指定一个
params参数，这可以帮助您更精确地指定或过滤边。
批量调用
将大量调用组合成一个HTTP请求是高效的。SDK使此过程变得简单。您可以将调用组合成FacebookAdsApiBatch的一个实例（在facebook_business.api中可用），以轻松获取您的API实例
my_api_batch = api.new_batch()
调用可以添加到批处理中，而不是立即执行
campaign.api_delete(batch=my_api_batch)
一旦您完成添加调用到批处理，您可以发送请求
my_api_batch.execute()
请遵循营销API文档中的批量调用指南。每个批次有最佳调用数。此外，您可能需要注意速率限制，因为批量调用仅仅提高了网络性能，并且每个调用都单独计入速率限制。
异常
有关SDK可能抛出的异常列表，请参阅facebook_business.exceptions。
测试
单元测试
单元测试不需要访问令牌或网络访问。使用以下命令与默认安装的Python运行它们
python -m facebook_business.test.unit
您还可以使用tox使用多个Python版本运行单元测试
sudo apt-get install python-tox # Debian/Ubuntu
sudo yum install python-tox # Fedora
tox --skip-missing-interpreters
您可以通过安装Python的附加版本来增加解释器覆盖率。在Ubuntu上，您可以使用deadsnakes PPA。在其他发行版上，您可以从源代码构建，然后使用sudo make altinstall来避免与系统安装的版本冲突。
示例
使用示例位于examples/文件夹中。
调试
如果此SDK未按预期工作，可能是SDK问题或API问题。
这可以通过构建一个原始cURL请求并查看响应是否如预期来实现
例如
from facebook_business.adobjects.page import Page
from facebook_business.api import FacebookAdsApi
FacebookAdsApi.init(access_token=access_token, debug=True)
page = Page(page_id).api_get(fields=fields,params=params)
运行此代码时，此cURL请求将打印到控制台
curl -X 'GET' -H 'Accept: */*' -H 'Accept-Encoding: gzip, deflate' -H 'Connection: keep-alive' -H 'User-Agent: fbbizsdk-python-v3.3.1' 'https://graph.facebook.com/v3.3/<pageid>/?access_token=<access_token>&fields=name%2Cbirthday%2Cphone'
SDK Codegen
我们的SDK是从SDK Codegen自动生成的。如果您想了解我们的SDK代码是如何生成的，请检查此存储库。
问题
为了更有效地处理错误，我们决定关闭在Github上的问题报告，并转移到我们专门的错误报告渠道。如果您在使用Business SDK（Python）时遇到错误，请在我们开发者的错误报告渠道此处报告问题。
许可证
Facebook Business SDK for Python的许可证文件位于此源树的根目录中。
下载文件
下载适用于您平台的文件。如果您不确定选择哪个，请了解有关安装包的更多信息。