安装应用以及生成、刷新和撤销口令

系统用户代表服务器调用,所以不能使用 Facebook 登录,也不能安装应用或通过标准的 Facebook oAuth 流程生成口令。您需要通过 API 调用执行这些操作。

系统访问口令的类型

类型 永久访问口令 推荐的限时访问口令

有效期

永不过期

有效期为 60 天

是否需要刷新?

基于用例的建议

您可以承受访问口令泄露的风险,并支持第三方应用程序离线访问数据。

您希望降低访问口令泄露的风险。

安装应用

系统用户或管理员级系统用户必须安装要用于生成访问口令的应用,以便此应用可代表该系统用户或管理员级系统用户调用 API。

系统用户和应用应属于同一个商务管理平台。系统用户或管理员级系统用户只能安装拥有广告管理 API 标准访问级别及更高级别的应用。

如要为系统用户安装应用,您需要:

  • access_token:管理员用户、管理员级系统用户或另一系统用户的访问口令
  • business_app:待安装应用的编号

如要为系统用户安装应用程序,请发出以下 POST 请求:

curl \
-F "business_app=APP-ID" \
-F "access_token=ACCESS-TOKEN" \
"https://graph.facebook.com/API-VERSION/SYSTEM-USER-ID/applications"

如果安装成功,此调用会返回一个布尔值结果。如果没有满足任意限制条件,您将看到相应的错误消息。

生成访问口令

安装应用后,系统用户便可生成永久访问口令。此过程需遵循下列限制条件:

  • 系统用户必须已按照上述步骤安装参数中传递的应用。
  • 应用仅适用于已认领该应用的公司(或这些公司的子公司)。
  • 系统用户和此次口令生成 API 调用中所用访问口令的所有者必须属于同一个商务管理平台。
  • 应用则无须属于同一商务管理平台。如果应用不属于同一商务管理平台,则会有一些限制条件。请参阅以下部分

以下是 API 调用需要的参数:

  • business_app:系统用户所属商务管理平台拥有的应用。
  • appsecret_proof:应用的计算字段。此字段为必要参数,用于确保执行 API 调用的服务器正确无误。详情请参阅登录安全
  • scope:此逗号分隔的字符串包含扩展的权限。
  • access_token:此口令属于商务管理平台管理员、管理员级系统用户或一般系统用户。
  • set_token_expires_in_60_days:设为 true,用于生成限时系统用户访问口令。此参数是非必要项。

支持的系统用户范围:

  • ads_management
  • ads_read
  • attribution_read
  • business_management
  • catalog_management
  • commerce_account_manage_orders
  • commerce_account_read_orders
  • commerce_account_read_settings
  • instagram_basic
  • instagram_branded_content_ads_brand
  • instagram_branded_content_brand
  • instagram_content_publish
  • instagram_manage_comments
  • instagram_manage_insights
  • instagram_manage_messages
  • instagram_shopping_tag_products
  • leads_retrieval
  • page_events
  • pages_manage_ads
  • pages_manage_cta
  • pages_manage_engagement
  • pages_manage_instant_articles
  • pages_manage_metadata
  • pages_manage_posts
  • pages_messaging
  • pages_read_engagement
  • pages_read_user_content
  • pages_show_list
  • private_computation_access
  • publish_video
  • read_audience_network_insights
  • read_insights
  • read_page_mailboxes
  • whatsapp_business_management
  • whatsapp_business_messaging

已停用的权限,仅对 2018 年 4 月 24 日之前创建的应用可见

publish_actions

按功能设限的权限

功能 权限

business_creative_asset_management

business_creative_managementbusiness_creative_insights
business_creative_insights_sharebusiness_data_management

commerce_public_api_beta_testing

commerce_manage_accountscommerce_account_read_reports

如要生成 appsecret_proof,您可以使用以下 PHP 代码:

$appsecret_proof = hash_hmac(
  'sha256',
  $access_token_used_in_the_call,
  $app_secret_for_the_app_used_in_the_call,
);

在上述代码示例中,app_secret_for_the_app_used_in_the_call 是指用于生成访问口令的应用的应用密钥。您可以前往应用面板查看应用密钥。

经散列处理的 appsecret_proof 应如同以下字符串:"1734d0d1e1ca62c9762c10bbc7321fdf89ecc7d819312b2f3"

如要生成永久系统用户访问口令,请发出以下 POST 请求:

curl \
-F "business_app=<APP_ID>" \
-F "scope=ads_management,manage_pages" \
-F "appsecret_proof=APPSECRET-PROOF" \
-F "access_token=ACCESS-TOKEN" \
"https://graph.facebook.com/API-VERSION/SYSTEM-USER-ID/access_tokens"

如要生成限时系统用户访问口令,请发出以下 POST 请求:

curl \
-F "business_app=<APP_ID>" \
-F "scope=ads_management,manage_pages" \
-F "set_token_expires_in_60_days=true" \
-F "appsecret_proof=APPSECRET-PROOF" \
-F "access_token=ACCESS-TOKEN" \
"https://graph.facebook.com/API-VERSION/SYSTEM-USER-ID/access_tokens"

该端点之前的名称为 /SYSTEM-USER-ID/ads_access_token。向该名称发出的调用不再有效。

响应将返回访问口令字符串。如果您没有满足任意限制条件,系统将返回相应错误代码。响应:

{
  "access_token": "CAAB3rQQzTFABANaYYCmOuLhbC]Fu8cAnmkcvT0ZBIDNm1d1fSp4Eg4XA79gmYumZCoSuiMSUILUjzG3y15BJlrYwXdqwd5c7y3lOUzu6aT7MkXL6HpISksSuLP4aFKWPmwb6iOgGeugRSn766xMZCN72vTiGGLUNqC2MKRL"
}

您还可以使用商务管理平台用户界面生成系统用户访问口令。

刷新访问口令

限时系统用户口令自生成或刷新之日起 60 天内有效。如要继续使用该访问口令,开发者应在 60 天内进行刷新。如未刷新,系统将没收访问口令,而且开发者需要获取新的访问口令,才能重新获得 API 访问权限。

如要刷新限时系统用户访问口令,您需要:

  • fb_exchange_token:有效的系统用户访问口令
  • client_id:应用编号
  • client_secret:应用密钥
  • set_token_expires_in_60_days:设为 true,以刷新限时系统用户访问口令。

查询 GET oauth/access_token 端点。

请求示例

curl -i -X GET 
"https://graph.facebook.com/{graph-api-version}/oauth/access_token?  
    grant_type=fb_exchange_token&          
    client_id={app-id}&
    client_secret={app-secret}&
    set_token_expires_in_60_days=true&
    fb_exchange_token={your-access-token}"

响应示例

{
  "access_token":"{expiring-system-user-access-token}",
  "token_type": "bearer",
  "expires_in": 5183944    // Time left in seconds until the token expires
}

撤销访问口令

此端点用于执行常规口令轮换,或撤销被盗用系统用户的访问口令,以保护您的系统。

如要撤销系统用户访问口令,您需要提供以下字段:

  • revoke_token:要撤销的访问口令

  • client_id:应用编号

  • client_secret:应用密钥

  • access_token:用于识别调用者身份的访问口令

要求如下:

  • 请务必确保 client_id 与实际应用一致,并且应用未被节流、禁用或删除。

  • client_id 以及 revoke_token 的已安装应用、access_token 的已安装应用和 client_secret 都必须相同。

查询 GET oauth/revoke 端点。

请求示例

curl -i -X GET "https://graph.facebook.com/{graph-api-version}/oauth/revoke?   
    client_id={app-id}&
    client_secret={app-secret}&
    revoke_token={system-user-access-token-to-revoke}&
    access_token={your-access-token}"

响应示例

{
  "success":"true",
}

访问口令轮换

口令轮换是一项安全措施,有助于降低风险,例如减少口令泄漏所造成的损失。通过经常更改访问口令,可减少口令泄露或丢失造成的潜在损失,这与更改密码极为相似。目前,我们的系统支持在不停机的情况下轮换系统用户。如要执行轮换,请按照以下说明操作:

  1. 通过 SUAT 刷新 API 刷新系统用户访问口令。SUAT 刷新 API 将返回一个新的系统用户访问口令,该新口令自刷新之日起 60 天内有效。旧口令在过期之前仍然有效(过期时间:创建日期 + 60 天)。

  2. 部署新的系统用户访问口令。

  3. 通过 SUAT 撤销 API 撤销旧的系统用户访问口令。旧口令将立即失效,且撤销后您不能再次使用该口令。