WordPress REST API的默认端点旨在按默认情况下返回数据，以提供大多数站点和用例，但是通常需要在某些情况下访问或公开各种对象类型的响应中的其他数据。
与WordPress的其余部分一样，REST API旨在高度扩展以满足这些需求。本指南详细详细介绍了如何使用默认端点的响应添加其他数据register_rest_field和register_meta功能。您可以使用这些功能将字段添加到REST API支持的任何对象类型中。这些自定义字段可以支持GET和更新操作。
关于改变响应的重要说明
从核心REST API端点响应中更改或删除数据可能会破坏插件或WordPress核心行为，应尽可能避免使用。
API在API响应上揭示了许多领域，包括您可能不需要的内容，或者可能不适合您的网站工作方式。虽然诱人地修改或从REST API响应中删除字段，但 将要 引起API客户的问题，希望标准响应。这包括移动客户端，帮助您管理网站的第三方工具或WP-Admin本身。
您可能只需要少量数据，但是请务必记住，API是要向所有客户端展示界面，而不仅仅是您正在使用的功能。改变反应是危险的。
添加字段并不危险，因此，如果您需要修改数据，最好使用修改的数据复制字段。从不鼓励拆除田地；如果您需要获取较小的数据子集，请使用 _fields范围 或使用上下文。
如果您必须从现有上下文中删除字段，则应确保行为是 选择参加 例如，通过提供自定义查询参数来触发字段删除。
API无法阻止您改变响应，但是该代码结构强烈劝阻这样做。在内部，现场注册由过滤器提供动力，如果您绝对别无选择，可以使用这些供力。
使用register_rest_field vs register_meta
有两种方法可用于将数据添加到WordPress REST API响应中，register_rest_field和register_meta。
register_rest_field可用于将任意字段添加到任何REST API响应中，可用于使用API读取和写入数据。要注册一个新的REST字段，您必须提供自己的回调功能来获取或设置该字段的值，并手动指定自己的该字段的架构定义。
register_meta用于将现有的自定义元值进行白色，以通过REST API访问。通过设置元字段show_in_rest参数为true，该领域的价值将在.meta端点响应中的密钥，WordPress将处理设置用于读取和写入该元密钥的回调。这比register_rest_field，有一个警告：
在WordPress 4.9.8之前，元字段设置为
show_in_rest使用register_meta为给定类型的所有对象注册。如果一种自定义帖子类型显示一个元字段，则所有自定义帖子类型都将显示该元字段。从WordPress 4.9.8开始register_meta与object_subtype允许人们将META密钥的使用减少到特定帖子类型的参数。在WordPress 5.3之前，register_meta只能支持标量值（string，integer，number和boolean）。WordPress 5.3添加了对object和array类型。
将自定义字段添加到API响应
使用register_rest_field
这 register_rest_field 函数是将字段添加到REST API响应对象的最灵活的方法。它接受三个参数：
$object_type：作为字符串的对象的名称或正在注册该字段的对象名称的数组。这可能是一种核心类型，例如“帖子”，“术语”，“元”，“用户”或“注释”，但也可以是自定义帖子类型的字符串名称。$attribute：字段的名称。此名称将用于定义响应对象中的密钥。$args：一个带有键的数组，定义用于检索字段值（’get_callback’）的回调函数，以更新字段值（’update_callback’），并定义其架构（’schema’）。
$ args数组的每个键都是可选的，但是如果不使用，则不会添加该功能。这意味着您可以指定一个回调函数以读取值并省略更新回调，以使该字段在需要时读取。
字段应在rest_api_init行动。使用此操作而不是init将防止在不使用REST API的WordPress请求期间进行字段注册。
例子
在评论回复中读取并写下额外的字段
<?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'
),
) );
} );
此示例说明了添加一个名为的字段karma对帖子的响应。它起作用是因为comment_karma现场存在，但没有核心使用。请注意，评论业力的实际实施将需要使用单独的端点。
这是一个基本示例；仔细考虑您的特定字段可能需要进行哪些权限检查或错误处理。
register_rest_field如何工作
全局变量$wp_rest_additional_fields由REST API基础架构内部使用以将响应字段添加到每个对象类型中。REST API提供register_rest_field作为添加此全局变量的实用程序功能。应避免直接添加到全局变量，以确保前向兼容性。
对于每种对象类型 – 帖子或用户，术语，评论等 – $wp_rest_additional_fields包含一系列字段定义，其中包含用于检索或更新字段值的回调。
与RET的API中的注册META合作
这 register_meta 函数简化了为特定对象类型定义元字段的过程。通过设置'show_in_rest' => true注册新的元密钥时，将通过REST API访问该密钥。
在邮寄回复中读取并写下元字段
<?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';
$meta_args = 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', $meta_args );
此示例显示了如何允许读取后元字段的读写。这将允许通过邮政请求更新该字段wp-json/wp/v2/posts/<post-id>或通过发布请求与帖子一起创建wp-json/wp/v2/posts/。
请注意，对于在自定义邮政类型上注册的元字段，帖子类型必须具有custom-fields支持。否则，元字段将不会出现在REST API中。
帖子类型特定的元
WordPress 4.9.8通过使用The The The The The The The The The The The The The The The The The The The The The The The The The The The The The The The The Condorta gogents Meta的支持。register_post_meta和register_term_meta功能。他们遵循与register_meta但是，接受帖子类型或分类法作为其第一个参数而不是对象类型。以下代码将注册my_meta_key上面的示例，但仅用于page自定义帖子类型。
$meta_args = array(
'type' => 'string',
'description' => 'A meta key associated with a string meta value.',
'single' => true,
'show_in_rest' => true,
);
register_post_meta( 'page', 'my_meta_key', $meta_args );
对象元类型
WordPress 5.3添加了使用object类型 注册元时。重要的object指的是JSON对象，这等同于PHP中的关联数组。
注册时object元，设置type到object还不够，您还需要告知WordPress哪些属性允许。这是通过在注册元数据时编写JSON模式来完成的。
例如，以下代码示例注册一个称为“释放”的元字段，该字段接受给定的JSON数据。
{
"meta": {
"release": {
"version": "5.2",
"artist": "Jaco"
}
}
}
register_post_meta(
'post',
'release',
array(
'single' => true,
'type' => 'object',
'show_in_rest' => array(
'schema' => array(
'type' => 'object',
'properties' => array(
'version' => array(
'type' => 'string',
),
'artist' => array(
'type' => 'string',
),
),
),
),
)
);
注意show_in_rest变成数组而不是true并为schema钥匙。然后在properties大批。至少每个属性必须指定type，但是任何JSON模式关键字rest_validate_value_from_schema也可以使用理解。
其他属性
默认情况下，属性列表是严格的白名单。如果在未列出的请求中发送属性，则REST API将返回错误：your_property is not a valid property of Object.。如果您不提前知道属性名称additionalProperties可以使用关键字。additionalProperties接受用于验证未知属性的JSON模式。例如，为了强制执行任何其他属性是数字，可以使用以下代码。
{
"meta": {
"release": {
"version": "5.2",
"artist": "Jaco",
"unknown_field": 5.3
}
}
}
register_post_meta(
'post',
'version',
array(
'single' => true,
'type' => 'object',
'show_in_rest' => array(
'schema' => array(
'type' => 'object',
'properties' => array(
'version' => array(
'type' => 'string',
),
'artist' => array(
'type' => 'string',
),
),
'additionalProperties' => array(
'type' => 'number',
),
),
),
)
);
additionalProperties可以设置为true以允许任何格式的未知属性，但不建议这样做。
阵列元类型
WordPress 5.3还增加了支持使用的支持array类型。重要的array指的是JSON数组，这等同于PHP中的数字阵列。
注册时array元，设置type到array是不够的，您需要向WordPress告知阵列中的项目的预期格式。这是通过在注册元数据时编写JSON模式条目来完成的。
如果您不提供此值，register_meta将返回错误并发出以下警告：When registering an "array" meta type to show in the REST API, you must specify the schema for each array item in "show_in_rest.schema.items".
以下代码示例注册一个称为“项目”的元字段，其中包含项目名称列表。它接受给定的JSON数据。
{
"meta": {
"projects": [
"WordPress",
"BuddyPress"
]
}
}
register_post_meta(
'post',
'projects',
array(
'single' => true,
'type' => 'array',
'show_in_rest' => array(
'schema' => array(
'type' => 'array',
'items' => array(
'type' => 'string',
),
),
),
)
);
再次注意show_in_rest变成数组而不是true并为schema钥匙。
这items关键字用于定义JSON架构以验证每个数组成员的反对。它可以是标量类型string或复杂类型object。
例如，要接受给定的JSON数据，将使用以下元注册。
{
"meta": {
"projects": [
{
"name": "WordPress",
"website": "https://wordpress.org"
},
{
"name": "BuddyPress",
"website": "https://buddypress.org"
}
]
}
}
register_post_meta(
'post',
'projects',
array(
'single' => true,
'type' => 'array',
'show_in_rest' => array(
'schema' => array(
'items' => array(
'type' => 'object',
'properties' => array(
'name' => array(
'type' => 'string',
),
'website' => array(
'type' => 'string',
'format' => 'uri',
),
),
),
),
),
)
);
array类型强制执行数组键是从0开始的顺序整数array_values。非单个元数据
非单个元字段每个对象具有一个值数组，而不是每个对象一个值。这些值中的每个值都存储在元表中的单独行中。
这array和object类型也可以与非单打元字段一起使用。例如，如果来自早期的“释放”元密钥single设置false，可以接受以下JSON数据。
{
"meta": {
"release": [
{
"version": "5.2",
"artist": "Jaco"
},
{
"version": "5.1",
"artist": "Betty"
}
]
}
}
这将导致两个元数据库行。第一个包含{ "version": "5.2", "artist": "Jaco" }第二个包含{ "version": "5.1", "artist": "Betty" }。
同样，如果已设置的“项目”示例将接受以下数据single到false。
{
"meta": {
"projects": [
[
"WordPress",
"BuddyPress"
],
[
"bbPress"
]
]
}
}
这将导致两个元数据库行。第一个包含[ "WordPress", "BuddyPress" ]第二个包含[ "bbPress" ]。
无效的存储值
如果元字段的现有值未针对注册类型和模式进行验证，则该元字段的值将返回为null。如果执行更新请求时，该零值已将其传递回API，则将收到一个rest_invalid_stored_value错误：The %s property has an invalid stored value, and cannot be updated to null.。要解决此问题，要么更新具有有效值的元密钥，要么从您的请求中省略该属性。
默认元数据值
WordPress 5.5添加 官方支持 如果未定义值，则指定元数据的默认值。例如，使用此代码段price元字段将设置为0.00在REST API响应中，如果尚未值。
register_post_meta(
'product',
'price',
array(
'single' => true,
'type' => 'string',
'default' => '0.00',
)
);
添加链接到API响应
WordPress生成了与查询资源关联的链接列表，以使其更容易导航到相关资源。
{
"_links": {
"self": [
{
"href": "https://make.wordpress.org/core/wp-json/wp/v2/posts/28312"
}
],
"collection": [
{
"href": "https://make.wordpress.org/core/wp-json/wp/v2/posts"
}
],
"author": [
{
"embeddable": true,
"href": "https://make.wordpress.org/core/wp-json/wp/v2/users/8670591"
}
],
"replies": [
{
"embeddable": true,
"href": "https://make.wordpress.org/core/wp-json/wp/v2/comments?post=28312"
}
],
"wp:term": [
{
"taxonomy": "category",
"embeddable": true,
"href": "https://make.wordpress.org/core/wp-json/wp/v2/categories?post=28312"
},
{
"taxonomy": "post_tag",
"embeddable": true,
"href": "https://make.wordpress.org/core/wp-json/wp/v2/tags?post=28312"
}
]
}
}
来自make.wordpress.org post的链接示例
虽然这些链接将出现在_linksJSON响应对象中的属性，它不存储在WP_REST_Response::$data或可以通过WP_REST_Response::get_data()。相反，服务器将在回应响应数据之前将链接数据附加到响应。
可以通过使用自定义链接添加到响应中WP_REST_Response::add_link()方法。此方法接受三个参数：链接关系，URL和链接属性列表。例如，添加author和wp:term关联。
<?php
$response->add_link( 'author', rest_url( "/wp/v2/users/{$post->post_author}" ) );
$response->add_link( 'https://api.w.org/term', add_query_arg( 'post', $post->ID, rest_url( "/wp/v2/{$tax_base}" ) ) );
链接关系必须是 IANA的注册链接关系 或您控制的URI。
author是一种注册的链接关系，描述为“上下文的作者”，我们用它来指向写帖子的WordPress用户。不存在描述与帖子相关的术语的链接关系，因此WordPress使用https://api.w.org/term` URL. This is transformed toWP：使用Curie生成响应时术语“”。
第三个参数add_link()是自定义属性的列表。这embeddable属性可用于包括链接资源出现在_embedded使用时的部分_embed查询参数。如果添加了具有相同关系的多个链接，则嵌入式响应将以相同的顺序添加链接。
<?php
$response->add_link( 'author', rest_url( "/wp/v2/users/{$post->post_author}" ), array(
'embeddable' => true,
) );
$response->add_link( 'author', rest_url( "/wp/v2/users/{$additional_author}" ), array(
'embeddable' => true,
) );
链接到多作者帖子的示例实现。
{
"_links": {
"author": [
{
"embeddable": true,
"href": "https://yourwebsite.com/wp-json/wp/v2/users/1"
},
{
"embeddable": true,
"href": "https://yourwebsite.com/wp-json/wp/v2/users/2"
}
]
},
"_embedded": {
"author": [
{
"id": 1,
"name": "Primary Author"
},
{
"id": 2,
"name": "Secondary Author"
}
]
}
}
添加订单链接。
注册一个居里
WordPress版本4.5引入了对紧凑型URI或Curies的支持。这使得与完整URL相比，可以简单得多的标识符引用链接，这很容易漫长。
使用居里注册rest_response_link_curies筛选。例如。
<?php
function my_plugin_prefix_register_curie( $curies ) {
$curies[] = array(
'name' => 'my_plugin',
'href' => 'https://api.mypluginurl.com/{rel}',
'templated' => true,
);
return $curies;
}
这将从https://api.mypluginurl.com/my_link` tomy_plugin：my_linkin the API response. The full URL must still be used when adding links usingwp_rest_response :: add_link`。