WordPress中文开发手册

  1. Home
  2. WordPress中文开发手册
  3. WordPress REST API手册
  4. 扩展REST API
  5. 修改回应

修改回应

WordPress REST API的默认端点设计为默认返回数据,为大多数站点和用例提供数据,但是往往需要扩展各种对象类型的响应。

为了适应这些需求,REST API被设计为高度可扩展的,就像其余的WordPress一样。本文档详细介绍了如何使用register_rest_field和register_meta函数向默认端点的响应添加附加数据。您可以使用这些函数将字段添加到REST API支持的任何对象类型中。这些自定义字段可以支持get和update操作。

##关于改变回应的重要注意事项

API提供了许多关于API响应的领域,包括您可能不需要的内容,或者可能不适合您的网站的工作原理。虽然从响应中修改或删除字段很诱人,但这将导致API客户端出现预期标准响应的问题。这包括移动客户端或第三方工具,以帮助您管理您的网站,最终是wp-admin本身。

您可能只需要少量数据,但请务必记住,API是将界面暴露给所有客户端,而不仅仅是您正在开发的功能。变化的反应是危险的。

添加字段不是危险的,所以如果你需要修改数据,最好是用修改的数据来复制字段。不鼓励删除字段;如果您需要回收较小的数据子集,请使用上下文,并考虑使用自己的上下文。

请注意,API不能阻止您更改响应,但代码的结构强烈阻止此。在内部,现场注册由过滤器供电,如果绝对没有其他选择,则可以使用这些注册。

什么register_rest_field

在响应的基础架构中,全局变量$ wp_rest_additional_fields用于保存要添加到每个对象类型的响应的字段。 REST API提供了register_rest_field作为添加到这个全局变量的效用函数。应避免直接添加到全局变量,以确保最大化前向兼容性。

对于每个对象类型 - 帖子或用户,术语,注释等,$ wp_rest_additional_fields包含一个字段数组,每个字段可以具有用于检索该值的回调值,并使用添加该字段的任何端点更新该值可用于更新。

如何使用register_rest_field

函数register_rest_field字段接受三个参数:

$ object_type:对象的名称,作为字符串,或该字段正在注册的对象名称的数组。当添加到帖子类型端点时,应使用“post”。或者可以使用“条款”,“元”,“用户”或“注释”。
$ attribute:字段的名称。该名称将用于定义响应对象中的键。
$ args:具有键的数组,用于定义用于检索字段值的回调函数,以更新字段的值并定义其模式。每个这些键都是可选的,但如果不使用,则不会添加该功能。
这意味着如果您指定一个回调函数来读取该值,而不是一个用于更新的回调函数,那么它将是可读的,但不可更新。这在许多情况下可能是需要的。

应在rest_api_init操作中注册字段。使用此操作而不是init将阻止在不使用REST API的WordPress请求期间发生字段注册。

在评论回应中读写一个额外的字段

这个例子的TODO:

将匿名函数更改为命名函数(讨论)
权限检查如何工作? 错误处理? (在什么条件下更新代码被调用,还有什么其他检查需要在现实世界插件中完成?)
开发手册中的代码块的更短的线条和/或样式修复

<?php
add_action( 'rest_api_init', function() {
    register_rest_field( 'comment', 'karma', array(
        'get_callback' => function( $comment_arr ) {
            $comment_obj = get_comment( $comment_arr['id'] ); 
            return (int) $comment_obj->comment_karma;
        },
        'update_callback' => function( $karma, $comment_obj ) {
            $ret = wp_update_comment( array(
                'comment_ID'    => $comment_obj->comment_ID,
                'comment_karma' => $karma
            ) );
            if ( false === $ret ) {
                return new WP_Error( 'rest_comment_karma_failed', __( 'Failed to update comment karma.' ), array( 'status' => 500 ) );
            }
            return true;
        },
        'schema' => array(
            'description' => __( 'Comment karma.' ),
            'type'        => 'integer'
        ),
    ) );
} );

此示例说明如何将一个称为业务的字段添加到帖子的响应中。 它的作用是因为comment_karma字段存在,但未被核心使用。 请注意,实际执行评论业务需要使用单独的端点。

使用Meta&register_meta

在帖子回复中读写一个后期元字段

<?php
// The object type. For custom post types, this is 'post';
// for custom comment types, this is 'comment'. For user meta,
// this is 'user'.
$object_type = 'post';
$args1 = array( // Validate and sanitize the meta value.
    // Note: currently (4.7) one of 'string', 'boolean', 'integer',
    // 'number' must be used as 'type'. The default is 'string'.
    'type'         => 'string',
    // Shown in the schema for the meta key.
    'description'  => 'A meta key associated with a string meta value.',
    // Return a single value of the type.
    'single'       => true,
    // Show in the WP REST API response. Default: false.
    'show_in_rest' => true,
);
register_meta( $object_type, 'my_meta_key', $args1 );

此示例显示如何允许读取和写入后期元字段。 这将允许通过POST请求将宇宙飞船字段更新为wp-json / wp / v2 / posts / ,或者通过POST请求发送到wp-json / wp / v2 / posts / 。

请注意,对于在自定义帖子类型上注册的元字段,帖子类型必须支持自定义字段。 否则,元字段不会出现在REST API中。