取得資料的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 請求剖析
• 使用 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() 呼叫：

<?php
$query = new WP_Query( array(
    'tax_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 从服务器检索不同的资源。

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

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

使用顶级参数

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

參數	意義
context	請求的範圍。可能的值可以是 view、embed 或 edit。預設為view。
page	貼文集合的目前頁面。預設為 1。
per_page	每頁貼文總數。預設為 10。
搜尋	搜尋查詢。將結果限制為匹配字串。
after	僅傳回在此參數中指定的日期之後發布的貼文。
modified_after	#僅傳回在此參數中指定的日期之後修改的貼文。
作者	作者 ID。用於限制屬於特定作者的結果。
author_exclude	#結果集不包括指派給特定作者的貼文。
之前	僅傳回在此參數中指定的日期之前發布的貼文。
modified_before	#僅傳回在此參數中指定的日期之前修改的貼文。
排除	要從搜尋結果中排除的貼文 ID 陣列。
include	將結果限制為此數組中指定的帖子 ID。
offset	將搜尋結果偏移指定的數字。
order	集合的順序。可以是 asc 或 desc。
orderby	集合的排序屬性。可能的值可以是author, date, id, include, modified, parent, relevance, slug 、include_slugs 和title。
search_columns	#您可以指定要搜尋的列名數組。
<strong>slug</strong>	將結果限制為具有特定 slug 的貼文。
status	用於限制具有特定狀態的貼文的收集。
tax_relation	#用於根據多個分類法之間的關係來限制結果集。
類別	按類別分類中指派的術語過濾結果集。
categories_exclude	#將結果集過濾為除類別分類中指定的特定術語之外的項目。
<strong>標籤</strong>	按標籤分類中指定的術語過濾結果集。
tags_exclude	#將結果集過濾為標籤分類中指定的特定術語之外的項目。
sticky	用於將結果集限制為黏性項目。

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/<id>/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=<post_id>

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

$ GET /wp/v2/tags?post=<post_id>

如果我们需要检索 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 的其他三个操作，即创建、更新和删除资源。所以请继续关注。

以上是取得資料的WP REST API的詳細內容。更多資訊請關注PHP中文網其他相關文章！