REST API 不僅僅是一組默認路由。它也是創(chuàng)建自定義路由和端點的工具。前端提供了一組默認的 URL 映射，但用于創(chuàng)建它們的工具（如 API 和查詢類：等）也可用于創(chuàng)建自己的 URL 映射，或自定義查詢。

本文檔詳細介紹了如何使用您自己的端點創(chuàng)建完全自定義的路由。我們將首先通過一個簡短的示例，然后將其擴展到內(nèi)部使用的完整控制器模式。

良好的基礎

所以您想向 API 添加自定義端點？驚人的！讓我們從一個簡單的例子開始。

我們從一個如下所示的簡單函數(shù)開始：

<?php
/**
 * Grab latest post title by an author!
 *
 * @param array $data Options for the function.
 * @return string|null Post title for the latest,
 * or null if none.
 */
function my_awesome_func( $data ) {
  $posts = get_posts( array(
    'author' => $data['id'],
  ) );
 
  if ( empty( $posts ) ) {
    return null;
  }

 
  return $posts[0]->post_title;
}

要通過 API 提供此功能，我們需要注冊一個路由。這告訴 API 使用我們的函數(shù)來響應給定的請求。我們通過一個名為 的函數(shù)來做到這一點，該函數(shù)應該在 的回調(diào)中調(diào)用。

我們需要向它傳遞三件事：命名空間、我們想要的路由和選項。我們稍后會回到命名空間wordpress調(diào)用參數(shù)，但現(xiàn)在讓我們選擇 /v1。我們用 //{id} 匹配路由，其中?? {id} 是一個整數(shù)。

<?php
add_action( 'rest_api_init', function () {
  register_rest_route( 'myplugin/v1', '/author/(?P\d+)', array(
    'methods' => 'GET',
    'callback' => 'my_awesome_func',
  ) );
} );

目前，我們只注冊路由的一個端點。 （"Route" 是 URL，"" 是對應的方法和 URL），如果您的站點域是 wp-json 并且您保留 API 路徑的 wp-jsonwordpress調(diào)用參數(shù)，那么完整的 URL 將是 (?P\d+ )。每個路由可以有任意數(shù)量的端點，對于每個端點，您可以定義允許的 HTTP 方法、用于響應該請求的回調(diào)函數(shù)以及用于創(chuàng)建自定義權限的權限回調(diào)。此外，您可以在請求中定義允許的字段，每個字段指定一個默認值、一個清理回調(diào)、一個驗證回調(diào)以及是否需要該字段。

命名空間

命名空間是端點 URL 的第一部分。它們應該用作供應商/包前綴，以防止自定義路由之間發(fā)生沖突。命名空間允許兩個插件添加具有不同功能的同名路由。

命名空間通常應遵循 /v1 模式，其中供應商通常是您的插件或主題，v1 代表 API 的第一個版本。如果您需要破壞與新端點的兼容性，則可以將其限制為 v2。

上述情況，來自兩個不同插件的兩個同名路由，要求所有提供者使用唯一的命名空間。供應商功能前綴、類前綴和/或類名稱空間不會在主題或插件中使用，否則將不會這樣做，這是非常重要的。

使用命名空間的另一個好處是客戶端可以檢測到對您的自定義 API 的支持。 API 索引列出了站點上可用的命名空間：

{

  "name": "WordPress Site",
  "description": "Just another WordPress site",
  "url": "http://example.com/",
  "namespaces": [
    "wp/v2",
    "vendor/v1",
    "myplugin/v1",
    "myplugin/v2",
  ]
}

如果客戶想要檢查您的 API 是否存在于網(wǎng)站上，他們可以查看此列表。 （有關更多信息，請參閱探索指南。）

參數(shù)

默認情況下，路由接受請求中傳入的所有參數(shù)。這些組合成一組參數(shù)，然后添加到對象中，作為第一個參數(shù)傳遞給您的端點：

<?php
function my_awesome_func( WP_REST_Request $request ) {
  // You can access parameters via direct array access on the object:
 $param = $request['some_param'];
 
  // Or via the helper method:
 $param = $request->get_param( 'some_param' );

 
  // You can get the combined, merged set of parameters:
 $parameters = $request->get_params();
 
  // The individual sets of parameters are also available, if needed:
 $parameters = $request->get_url_params();
  $parameters = $request->get_query_params();
  $parameters = $request->get_body_params();
  $parameters = $request->get_json_params();
  $parameters = $request->get_default_params();
 
  // Uploads aren't merged in, but can be accessed separately:
 $parameters = $request->get_file_params();
}

（要確切了解參數(shù)是如何組合的，請查看 ::() 的源代碼；基本順序是正文、查詢、URL，然后是默認值）。

一般情況下，您將獲得所有參數(shù)不變。但是，您可以在注冊路由時注冊自己的參數(shù)，以便對其進行清理和驗證。

如果請求有 -type:/json 標頭集合和正文中的有效 JSON，則 then() 會將解析后的 JSON 正文作為關聯(lián)數(shù)組返回。

參數(shù)被定義為每個端點的關鍵參數(shù)中的映射（在回調(diào)選項旁邊）。此映射使用該鍵的參數(shù)名稱，其值是該參數(shù)的選項映射。該數(shù)組可以包含默認鍵、必需鍵和 .

使用并允許主回調(diào)僅處理請求并使用類來準備要返回的數(shù)據(jù)。通過使用這兩個回調(diào)，您將能夠安全地假設您的輸入在處理時是有效且安全的。

通過我們前面的例子，我們可以確保傳入的參數(shù)總是一個數(shù)字：

<?php
add_action( 'rest_api_init', function () {
  register_rest_route( 'myplugin/v1', '/author/(?P\d+)', array(
    'methods' => 'GET',
    'callback' => 'my_awesome_func',
    'args' => array(
      'id' => array(
        'validate_callback' => function($param, $request, $key) {
          return is_numeric( $param );
        }
      ),
    ),
  ) );
} );

你也可以傳遞一個函數(shù)名給wordpress做網(wǎng)站，但是直接傳遞一些函數(shù)，比如 .我們希望最終從根本上解決這個問題。

我們也可以使用類似 ''=>'' 的東西，但是驗證會拋出一個錯誤，讓客戶知道他們做錯了什么。當您寧愿更改正在輸入的數(shù)據(jù)而不是拋出錯誤（例如無效的 HTML）時，清理很有用。

返回值

調(diào)用回調(diào)后，返回值會轉(zhuǎn)換成JSON返回給客戶端。這允許您返回基本上任何形式的數(shù)據(jù)。在上面的示例中，我們返回一個字符串或 null，這些字符串由 API 自動處理并轉(zhuǎn)換為 JSON。

與任何其他函數(shù)一樣，您也可以返回一個實例。此錯誤消息將與 500 內(nèi)部服務錯誤狀態(tài)代碼一起傳遞給客戶端。您可以通過將實例數(shù)據(jù)中的狀態(tài)選項設置為代碼來進一步自定義錯誤，例如400 錯誤的輸入數(shù)據(jù)。

前面的例子，我們現(xiàn)在可以返回一個錯誤實例：

<?php
/**
 * Grab latest post title by an author!
 *
 * @param array $data Options for the function.
 * @return string|null Post title for the latest,
 * or null if none.
 */
function my_awesome_func( $data ) {
  $posts = get_posts( array(
    'author' => $data['id'],
  ) );
 
  if ( empty( $posts ) ) {
    return new WP_Error( 'awesome_no_author', 'Invalid author', array( 'status' => 404 ) );
  }
 
  return $posts[0]->post_title;
}

當作者沒有屬于他們的任何帖子時wordpress網(wǎng)站建設，這將向客戶端返回 404 Not Found 錯誤：

文章來自互聯(lián)網(wǎng)，侵權請聯(lián)系刪除，文章闡述觀點來自文章出處，并不代表本站觀點。 www.bjcthy.com

返回