BuddyPress REST API 入门指南

 

Getting Started with the BuddyPress REST API

BuddyPress REST API 允许您从第三方网站或应用程序与 BuddyPress 进行交互。

你可以做很多的事情,比如获取动态条目、上传动态更新、与群组和成员的互动,以及更多。它并没有 100% 与插件中的功能对等,但它有大部分的功能。

在这篇文章中,我将给你介绍 BP REST API 的主要组件,以及我们使用它们的经验中的一些提示。

入门

确保你至少使用 WP 5.0 和 BuddyPress 5.0。

你可以在 https://yoursite.com/wp-json/buddypress/v1/中与各个端点进行互动,你可以在这里看到完整的列表

要测试 API 是否可用,登录到你的网站。然后使用 Postman 发送一个 GET 请求到 https://你的网址/wp-json/buddypress/v1/activity

你应该看到一个动态数据的列表。

认证

如果您从 WordPress 插件或主题中调用 API,您不需要担心认证问题。API 会检测用户是否已登录,并返回相应的数据。

如果您使用的是第三方应用程序,您就不能使用 cookie 来确认用户是否登录,所以您需要使用 OAuth 或 JWT。JWT(json web token) 认证效果很好,比 oAuth 更简单,所以我们就用它。

设置 JWT 认证

安装此插件,并按照配置说明进行操作。

确保您定义了您的密匙,并在您的 wp-config.php 文件中添加以下代码来启用 CORS。

define('JWT_AUTH_SECRET_KEY', 'your-top-secret-key');
define('JWT_AUTH_CORS_ENABLE', true);

然后,你应该可以通过发送一个 POST 请求到/wp-json/jwt-auth/v1/token,并将你的用户名和密码作为 url 参数来获得一个令牌。保存该令牌,我们将把它硬编码到我们的 API 调用中。(对于一个成熟的应用程序,你需要为此创建一个图形界面,但这是后话了)

现在可以在授权头中使用这个 Bearer 令牌来获取敏感数据,比如私人信息。

请求示例

BP REST API 有很多可用的端点,而且他们还在增加更多的端点。这不是一个详尽的列表,而是一些如何与 API 交互的例子。

动态

要抓取所有的网站动态,发送 GET 请求到 http://你的网址/wp-json/buddypress/v1/activity

下面是写稿时可用的参数清单。

$args = array(
    'exclude'           => $request['exclude'],
    'in'                => $request['include'],
    'page'              => $request['page'],
    'per_page'          => $request['per_page'],
    'search_terms'      => $request['search'],
    'sort'              => $request['order'],
    'spam'              => $request['status'],
    'display_comments'  => $request['display_comments'],
    'site_id'           => $request['site_id'],
    'group_id'          => $request['group_id'],
    'count_total'       => true,
    'fields'            => 'all',
    'show_hidden'       => false,
    'update_meta_cache' => true,
    'filter'            => false,
);

使用参数的例子是这样的。

http://你的网址/wp-json/buddypress/v1/activity?group_id=2&display_comments=false&per_page=12

要发布一个新的动态,请向同一个端点发出 POST 请求。唯一需要的参数是 “content”,当然你必须像上面描述的那样,在授权头中发送你的 Bearer 令牌。

要发布一个动态评论,你可以提出同样的请求,但要添加一个 activity_comment 的类型,并包含 parentid

https://你的网址/wp-json/buddypress/v1/activity?content=mycomment&parent=247&id=247&type=activity_comment

成员
要列出所有成员,请发送一个经过认证的 GET 请求到 https://你的网址/wp-json/buddypress/v1/members

变量:

$args = array(
            'type'           => $request['type'],
            'user_id'        => $request['user_id'],
            'user_ids'       => $request['user_ids'],
            'xprofile_query' => $request['xprofile'],
            'include'        => $request['include'],
            'exclude'        => $request['exclude'],
            'member_type'    => $request['member_type'],
            'search_terms'   => $request['search'],
            'per_page'       => $request['per_page'],
            'page'           => $request['page'],
);

要获得某一位用户的信息,只需在请求的末尾添加用户的 ID:https://你的网址/wp-json/buddypress/v1/members/12

你也可以使用 POST 创建成员,添加或删除好友关系在本文撰写时还不是 API 的一部分。

私信

BuddyPress 的私信像电子邮件,有收件箱,和发件箱。有多个私信的串,就像电子邮件。

要得到所有的私信串,你可以发送一个请求像这样:.../wp-json/buddypress/v1/messages/?box=inbox&user_id=1

一条私信串是一个数组对象,它有关于私信的信息,如 ID、收件人、消息数组、最近的消息、日期等。下面是一个私信串对象的例子。

{
        "id": 42,
        "primary_item_id": 55,
        "secondary_item_id": 1,
        "subject": {
            "rendered": "New thread"
        },
        "excerpt": {
            "rendered": "hey there!"
        },
        "message": {
            "rendered": "<p>hey there!</p>\\n"
        },
        "date": "2019-06-03T21:23:34",
        "unread": 1,
        "sender_ids": {
            "1": 1
        },
        "recipients": {
            "1": {
                "id": 83,
                "user_id": 1,
                "thread_id": 42,
                "unread_count": 1,
                "sender_only": 0,
                "is_deleted": 0
            }
        },
        "messages": [
            {
                "id": 55,
                "thread_id": 42,
               "sender_id": 1,
                "subject": {
                    "raw": "New thread",
                    "rendered": "New thread"
                },
               "message": {
                    "raw": "hey there!",
                    "rendered": "<p>hey there!</p>\\n"
                },
                "date_sent": "2019-06-03 21:23:34"
            }
        ]
    }

要获取一个私信串,请添加私信串的 id:.../wp-json/buddypress/v1/messages/5

检索私信的参数。

$args = array(
            'user_id'      => $request['user_id'],
            'box'          => $request['box'],
            'type'         => $request['type'],
            'page'         => $request['page'],
            'per_page'     => $request['per_page'],
            'search_terms' => $request['search'],
        );

要发布新的私信,请向/messages 发送一个 POST 请求,其中包含以下参数:subjectcontentrecipients

https://site.com/wp-json/buddypress/v1/messages/?subject=reply to thread 5&content=this is my reply&recipients=1

要回复一个已有的私信串,请添加该私信串的 id 并删除 subject

https://site.com/wp-json/buddypress/v1/messages/?content=this is my reply&id=5&recipients=1

群组

要获取所有的群组,...wp-json/buddypress/v1/groups

要获得一个单独的群组,请在末尾添加群组 ID...wp-json/buddypress/v1/groups/12

要获得一个组的成员...wp-json/buddypress/v1/groups/1/members

要添加成员到一个组,请向成员端点发送一个 POST 请求,并在最后加上要添加的用户 ID.../wp-json/buddypress/v1/groups/1/members/37

要从组中删除成员,使用与上述相同的请求,但使用 DELETE。

扩展 BP REST API

有各种钩子和过滤器可用于扩展 API。您可以在 API 文档中找到所有可用的钩子和过滤器。

这里有几个使用钩子和过滤器扩展 BP REST API 的例子。

// add something to the activity post
add_filter( 'bp_rest_activity_pre_insert_value', function( $prepared_activity, $request ) {
 
    $prepared_activity->content .= $request['my_custom_param'];
    return $prepared_activity;
 
}, 10, 2 );
// add an endpoint. This is probably a bad idea, you should use your own rest base slug, not buddypress/v1. You must add your own callbacks as well.
add_action( 'bp_rest_api_init', function() {
 
    register_rest_route( 'buddypress/v1', '/my-endpoint', array(
        array(
            'methods'             => WP_REST_Server::READABLE,
            'callback'            => array( $this, 'get_items' ),
            'permission_callback' => array( $this, 'get_items_permissions_check' ),
        ),
    ) );
 
} );
// send the admin an email when a new group is created
add_action( 'bp_rest_groups_create_item', function( $group, $response, $request ) {
    $to = 'sendto@example.com';
    $subject = 'New group created!';
    $body = 'The group name is ' . $group->name;
    $headers = array('Content-Type: text/html; charset=UTF-8');
      
    wp_mail( $to, $subject, $body, $headers );
}, 10, 3 );

挑战

完整性

BP REST API 还没有完全和 BuddyPress 同步,所以有些功能不存在。比如说,好友组件是不存在的,你得自己滚动添加/删除好友的方式。它还需要自定义代码来上传带有活动帖子或消息的图片。

再造逻辑

与任何第三方应用程序一样,最难的部分是重新创建网站上已经存在的逻辑。例如,添加朋友按钮。当有人点击它之后,你需要发送 API 请求,并显示结果。如果失败了就显示错误,成功了就显示成功信息,或者是待定。你需要把这些数据保存到应用中,然后把按钮改成 “ 等待请求”,如果成功,则改成 “ 取消好友”。这种类型的考虑发生在每一次用户交互中,这需要很多额外的考虑。

支持的插件

支持第三方插件是很难的。比方说,有人在 BuddyPress 的活动发布中使用了一个图片滤镜插件。你必须在应用中重建整个 UI,然后构建端点来处理活动上传时的图片过滤器的处理。

也就是说,挑战也是乐趣的一部分。

结束语

当你使用 BuddyPress 的 API 与网站脱钩后,就会有很多新的可能性。BuddyPress 是一个强大的自托管社交互动插件,你可以建立一个像 Facebook Messenger 一样的私人消息应用,一个 Instagram 风格的照片分享应用,甚至一个完整的 Facebook 风格的社交社区应用。

你可以重建 UI,让它更快,更专注于你的特定用例。你可以离线缓存数据,利用推送通知,移动设备功能,如相机和地理定位,等等。

我们计划用它打造更多酷炫的东西,希望你也能做到。

通过 www.DeepL.com/Translator(免费版)翻译