获取数据的WP REST API

在本系列的前面部分中，我们一直在研究什么是 WP REST API 以及它如何帮助我们使用 WordPress 后端构建更好的应用程序。

然后，我们研究了在服务器上设置身份验证以生成经过身份验证的请求的两种不同方法。第一种是基本身份验证方法，它在开发环境中很有用，并且允许快速原型设计，因为它不需要太多时间来设置。高级身份验证方法是 OAuth 2.0，推荐用于生产环境，因为它比基本身份验证方法安全得多。

现在我们已经了解了如何设置身份验证，我们准备生成经过身份验证的请求以释放 WP REST API 的全部功能。由于其易于使用，我们将在本系列中使用基本身份验证，但建议您为生产服务器使用 OAuth 2.0 身份验证（由 WordPress REST API 身份验证插件提供）。

WordPress REST API 身份验证插件通过添加身份验证机制来控制对 API 端点的访问，从而增强了 WordPress REST API 的安全性。它带有一些身份验证方法：

• 基本身份验证
• API 密钥身份验证
• JWT 身份验证
• OAuth 2.0 身份验证

设置身份验证后，您可以为不同的 API 端点定义访问控制规则。它允许您配置哪些用户或角色有权访问特定端点。它还提供了根据用户角色、能力或特定用户 ID 限制访问的选项。

在本系列的当前部分中，我们将首次亲身体验 WP REST API。我们将：

• 分析 GET 请求的结构
• 查看 OPTIONS 请求如何自行记录 API
• 向服务器发送请求以检索数据
• 分析包括属性、架构和链接的服务器响应

因此，我们首先分析一个简单的 GET 请求的结构。

GET 请求剖析

在深入研究使用 WP REST API 检索任何数据的详细信息之前，我们需要熟悉发送到服务器的请求的语法。这将为我们将来与 WP REST API 的交互奠定坚实的基础。

考虑发送到服务器的以下请求：

$GET https://localserver/wp-json/wp/v2/posts

我们发送的请求类型是 GET — 我们在本系列的第一部分中介绍的六个 HTTP 动词之一。 GET 请求用于从服务器检索数据。因此，当在服务器上执行时，上述请求会以 JSON 数据的形式检索所有 post 对象的集合。

考虑到请求 URI，我们可以将其分为以下部分：

• https://localserver/：我的本地开发服务器的 URL。它可以是任何 URL，具体取决于您的 WordPress 安装位置。
• /wp-json：WP REST API 的端点前缀。
• /wp：WP REST API 的命名空间。
• /v2：WP REST API 的版本。
• /posts：这是我们要从服务器检索的资源。

命名空间可防止运行多个插件时可能发生的覆盖，每个插件都为 RESTful API 提供自己的抽象层。因此，每个抽象都在自己的边界内工作，不会影响属于其他抽象的方法和属性。

除了使用上述 URI 检索资源（帖子）集合之外，我们还可以通过提及其 ID 来检索特定资源：

$GET /wp/v2/posts/100

上面的请求将返回一个 post 对象，因为它向下查找 ID 为 100 的 post 资源。

通常，我们还需要搜索符合某些特定条件的帖子。例如，您可以按类别过滤帖子，如以下代码片段所示。

$ GET /wp/v2/posts?categories=20,30

通过发送上述请求，我们可以检索属于 ID 20 和 30 的类别的所有帖子。如您所见，您可以在 categories 参数中传递一个或多个类别 ID，它应该返回帖子在类别分类中分配特定术语。

上述语法相当于以下 WP_Query() 调用：

 array(
        array(
            'taxonomy' => 'category',
            'field'    => 'term_id',
            'terms'    => array( 20, 30 ),
        ),
    ),
) );

因此，上述 GET 请求将检索属于 ID 为 20 和 30 的两个类别的帖子列表。相同的语法也可用于具有两个以上元素的数组参数.

现在我们已经了解了如何格式化 GET 请求并提供其参数，是时候看看 OPTIONS 请求了。 OPTIONS 请求可以轻松地浏览 API，并且实际上可以作为一种自记录方式，通过记录端点上所有可用的 HTTP 方法以及参数来使 API 更易于访问他们支持。

使用 OPTIONS 请求在 API 中导航

如前所述，OPTIONS 请求对于探索 API 非常有帮助。它提到了属于某个路由的所有端点，并提供了这些端点支持 CRUD 操作的参数列表。

让我们向 /wp/v2/posts 路由发送 OPTIONS 请求，以检查它支持哪些端点以及我们可以沿 GET请求查询数据：

$curl -X OPTIONS /wp/v2/posts

我使用curl发送上述请求，但您可以使用您选择的任何工具，包括Postman。请务必包含上述路由的完整路径，包括您的服务器的路径。

{
    "namespace": "wp/v2",
    "methods": [...],
    "endpoints": [...],
    "schema": {...},
    "_links": {...}
}

上面的 OPTIONS 请求 /wp/v2/posts 路由返回 JSON 格式的数据，其中包含五个属性：

• 命名空间
• 方法
• 端点
• schema
• _links

{
    "namespace": "wp/v2",
    ....
}

namespace 属性标识当前插件的命名空间。在我们的例子中，它是 wp/v2，表示 WP REST API 的版本 2。我们已经在上一节中了解了命名空间及其服务的用途。

{
    ...
    "methods": [
        "GET",
        "POST"
    ],
    ...
}

methods 属性包含当前路由支持的所有方法的数组。通过查看上述请求返回的响应，可以清楚地看到 /wp/v2/posts 路由支持两种方法，即 GET 和 POST 。这意味着我们可以使用 /wp/v2/posts 路由来检索帖子，以及创建新帖子。我们将在本系列的下一部分中处理 POST 方法，因此我们暂时只关注 GET 方法。

下一个属性 — endpoints — 包含当前路由支持的端点数组。此属性直接链接到前面提到的 methods 属性，因为它列出了支持的方法的端点。

{
    ...
    "endpoints": [
        {
            "methods": [
                "GET"
            ],
            "args": {...},
            "allow_batch": {"v1":true}
        },
        {
            "methods": [
                "POST"
            ],
            "args": {...},
            "allow_batch": {"v1":true}
        }
    ],
    ...
}

endpoints 属性包含对象值，而对象值又包含三个属性，即 methods、args 和 allow_batch。 methods 属性包含 HTTP 方法的数组，下一个 args 属性包含这些方法支持的所有参数。最后，allow_batch 属性用于了解端点是否支持批量请求功能。这些是我们以 URI 参数的形式随请求发送的参数。

查看 GET 方法支持的参数，我们发现了 20 多个参数，包括 context、page、required、type、default。 required 属性指示该参数是否为必需，而 default 属性表示该参数的默认值。另一方面， type 属性指示应传递的值的类型。除此之外，它还可能包含其他特定于参数的属性。

"methods": [
        "GET"
],
"args": {
    "context": {
        "required": false,
        "default": "view",
        "type": "string",
        "description": "Scope under which the request is made; determines fields present in response."
    },
    "page": {
        "required": false,
        "default": 1,
        "type": "integer",
        "description": "Current page of the collection.",
        "minimum": "1"
    },
    "per_page": {
        "required": false,
        "default": 1,
        "type": "integer",
        "description": "Maximum number of items to be returned in result set.",
        "minimum": "1",
        "maximum": "100"
    },
}

返回的响应中的 schema 属性记录了当前资源的所有属性。该架构定义了 JSON 格式的数据结构。 WP REST API 中使用的架构格式基于 JSON 架构规范草案 4。

最后一个 _links 属性包含一个对象数组，其中包含关联资源的链接。对象中的键指定关系类型（例如 author、collection、self、comments 等） ，其值是指向相关资源的链接。该链接标准基于 HAL（超文本应用语言）。您可以通过阅读 Mike Kelley 撰写的规范来了解有关 HAL 的更多信息。

以类似的方式，我们也可以向其他路由（包括用户、评论、媒体、页面等）发送 OPTIONS 请求，以检查其支持的方法和参数。 OPTIONS 请求是您使用 WP REST API 时最好的朋友。

WP REST API 提供了另一种评估 API 可用性的方法，即向 /wp-json 索引路由发送 GET 请求。这将列出所有路由及其端点及其支持的方法和参数。

$curl -X GET http://wordpress-server/wp-json

上述请求将返回一个包含路由属性的响应对象，如下所示：

此功能非常强大，因为它列出了所有路由及其支持的方法和参数，因此无需在外部记录所有这些内容。当我们对不同的资源执行CRUD操作时，我们将引用这个响应对象。

查看了探索 API 的选项后，现在让我们开始使用 WP REST API 从服务器检索数据。

处理帖子

到目前为止，我们已经熟悉了 OPTIONS 请求，这是一种评估 API 可用性的自记录方式。我们还研究了它如何显示给定路由支持的方法和参数。利用这些知识，我们现在准备使用 WP REST API 从服务器检索不同的资源。

我们将从 posts 资源开始，因为它是 WordPress 的主要构建块。我们将使用不同的标准来检索帖子。通过应用这些知识，您将能够使用 WP REST API 查询帖子，就像使用 WP_Query 类一样。

在本系列中，我们一直在使用 posts 资源来演示示例请求及其响应，并且我们已经知道如何通过 ID 检索帖子集合和单个帖子。所以我们不会再讨论这个了。相反，我们将研究一些使用顶级参数检索帖子的更高级方法。

使用顶级参数

WP REST API 直接在 GET 端点上公开一些最常用的帖子查询变量。这些参数是：

context 参数用于根据我们正在工作的范围获取帖子。如果我们只是在索引页面上列出帖子，那么我们可以使用 view 上下文。但是，如果我们要检索帖子以进行编辑，则需要使用 edit 上下文：

$GET /wp/v2/posts?context=edit

edit 上下文参数在 title、content 和 raw 字段="inline">摘录。这个 raw 字段的值可以在编辑器中回显出来，用于编辑内容。

使用 edit 上下文需要您作为具有 edit_posts 权限的用户进行身份验证。

使用 embed 作为 context 参数的值可获取帖子的集合及其属性的最小子集。

上面提到的其他参数非常不言自明，您可以在 HTTP 客户端中使用它们。

这些是允许您根据特定条件查询帖子的基本参数。

如何使用其他条件过滤记录

除了使用一些基本的顶级参数检索帖子集合之外，WP REST API 还允许您按各种其他条件过滤记录。通过使用此语法，我们可以像使用 WP_Query() 类一样查询帖子。

分页参数是所有过滤器中最重要的，因为它们在帖子列表页面上广泛使用。分页参数允许我们在每页显示特定数量的帖子，并导航到包含帖子的特定数量的页面。

默认情况下，GET 请求会检索每页 10 个帖子的集合。让我们看看如何提交 GET 请求来检索每页仅五个帖子：

$GET /wp/v2/posts?per_page=5

上述请求使用 per_page 变量，如果您使用过 WP_Query()，您可能会熟悉该变量。

page 参数与 per_page 参数结合使用，用于导航到特定数量的页面。每页检索到五个帖子后，我们将发出以下请求以导航到第二页：

$GET /wp/v2/posts?per_page=5&page=2

在使用 WP REST API 在列表页面上构建分页时，per_page 和 page 过滤器非常方便。

除了上述请求返回的帖子集合之外，服务器还返回许多标头以及包含有用信息的响应，包括帖子总数和页数。这些值包含在 X-WP-TotalPages 和 X-WP-Total 响应标头中。

使用 WP REST API 创建分页时，X-WP-TotalPages 和 X-WP-Total 响应标头非常有用，因为它们列出了页面总数以及帖子总数。

除了分页过滤器之外，您还可以按日期过滤帖子。

因此，如果我们要查找日期为 2015-10-15（yyyy/mm/dd）发布的帖子，可以通过以下查询来实现：

$ GET /wp/v2/posts?modified_after=2015-10-14&modified_before=2015-10-16

我们已经在本教程的上一节中了解了如何使用 categories 参数获取属于特定类别或多个类别的帖子。让我们看看如何显示属于 id 为 5 和 6 的类别的帖子：

$ GET /wp/v2/posts?categories=5,6

上述请求将检索属于 ID 为 5 和 6 的类别的所有帖子的列表。

通过以下方式使用 categories_exclude 参数可以达到相反的效果：

$ GET /wp/v2/posts?categories_exclude=5,6

这将检索帖子列表，同时排除属于 ID 为 5 或 6 的类别的所有帖子。

现在我们已经在 WP REST API 的帮助下查看了查询帖子时的不同选项，我们准备进一步推进我们的旅程并查看 WP REST API 支持的一些其他资源。

使用帖子修订、类别和标签

帖子修订提供了一种查看和恢复对帖子所做编辑的方法。 WP REST API 提供了一种通过查询 /posts//revisions 端点来查看帖子的所有修订版本的方法。因此，对于 ID 为 10 的给定帖子，可以通过发送以下请求来检索所有修订：

$ GET /wp/v2/posts/10/revisions

上述请求将返回一个包含修订对象的数组。修订对象包含在发布对象中找到的属性的子集。下面是 Postman 中的修订对象示例：

只要我们知道其 ID，就可以检索特定的修订版本。因此，可以通过以下对象检索 ID 为 10 的帖子上 ID 为 2 的修订：

$ GET /wp/v2/posts/10/revisions/2

上述请求将返回单个修订对象。

除了帖子修订之外，还可以通过以下请求检索特定帖子的类别：

$ GET /wp/v2/categories?post=

对于标签，我们使用以下请求，其中 是帖子的 ID：

$ GET /wp/v2/tags?post=

如果我们需要检索 ID 为 10 的帖子的帖子元数据，我们将以经过身份验证的用户身份发送以下请求：

$ GET /wp/v2/posts/10/meta

这将返回一个元对象数组。

请注意，要在 WP REST API 中使用帖子和页面元，您需要安装配套插件，该插件可从 WP REST API 团队在 GitHub 上获取。

使用其他资源

到目前为止，我们已经为使用 WP REST API 检索数据奠定了相当坚实的基础。我们已经研究了选项请求以及它如何帮助我们在不需要外部文档的情况下探索 API。

您始终可以向特定资源发送 OPTIONS 请求，并检查它支持哪些端点和参数。如果您需要列出 WP REST API 提供的所有路由，您可以向 /wp-json 处的索引端点发送 GET 请求，正如我们在本教程的开始。

考虑到自我文档的优势，我认为我们不需要进一步探索本教程中的每个单独资源，因为您现在可以自己完成此操作。

接下来会发生什么？

在这个冗长的教程中，我们学习了使用 OPTIONS 请求探索 API 并使用 WP REST API 从服务器检索数据。我们只查看了一些资源，包括帖子、修订后和帖子元，因为我们无法仅在一个教程中涵盖所有支持的资源。但您现在应该能够使用我们在本教程中介绍的技术自行探索 API。

WordPress 的经济非常活跃。有主题、插件、库和许多其他产品可以帮助您构建网站和项目。该平台的开源性质也使其成为提高编程技能的绝佳选择。

在本系列的下一部分中，我们将学习执行 CRUD 的其他三个操作，即创建、更新和删除资源。所以请继续关注。