JSON API for WP 文件翻譯

Iamxiarui發表於2016-09-03

JSONAPI

1.基本概念

1.1 Requsets 請求

使用一個簡單的rest風格的HTTP GET或POST請求。查詢呼叫API,包括一個非空值json在URL中。

JSON API 有兩種方式：

隱式：通過設定JSON的引數查詢WP頁面上的任何一個非空值，通常會以JSON格式的方式返回這個頁面的內容；
顯式：通過設定JSON觸發一個已知的方法。見第二節：一個完整的請求方法列表。

1. 隱式呼叫

http://www.example.org/?json=1（返回該站全部json格式資料）
http://www.example.org/?p=47&json=1（返回文章id為47的json資料）
http://www.example.org/tag/banana/?json=1（返回標籤是banana的json資料）

2. 顯示呼叫

http://www.example.org/?json=getrecentposts（返回最新文章json資料，預設返回很多欄位，可以指定）
http://www.example.org/?json=getpost&postid=47（返回id為47的文章json資料）
http://www.example.org/?json=gettagposts&tag_slug=banana（返回tag標籤是banana的json資料）注意：這裡的方法用下劃線 _ 和短連線符 – 都可以。

3. 連結友好型呼叫

http://www.example.org/api/getrecentposts/
http://www.example.org/api/getpost/?postid=47
http://www.example.org/api/gettagposts/?tag_slug=banana注意：這裡必須用下劃線 _ ，不允許用短連線符 – 。

進一步閱讀：

見第三節：有關請求引數的更多資訊包括請求引數修改響應。

1.2 控制器

JSON API的1.0版引入了模組化控制器系統。這允許開發人員靈活的新增API的功能和給使用者更多方法啟用控制。

核心控制器

之前大多數的1.0可用方法已經被移到核心控制器。除了 submitcomment 和 createpost ，它們分別是現在可用的響應控制器和文章控制器。

核心控制器是唯一一個預設的可用控制器。其他的所有功能必須從JSON API的設定頁面中啟用（設定在WP後臺的管理選單中）。

指定控制器

這裡有幾個方法指定一定控制器，取決與你如何呼叫API：

http://www.example.org/?json=getrecentposts (核心控制器是隱含的，方法是getrecentposts)
http://www.example.org/api/info/ (核心控制器是隱含的)
http://www.example.org/api/core/getcategoryposts/ (核心控制器也可以顯式指定)
http://www.example.org/?json=respond.submit_comment (響應控制器，submit_comment 方法)

舊版本相容

JSON API保留了1.0版本以前的支援。例如，如果你呼叫該方法不指定Posts 控制器，它將自己選擇，而不是核心。

可用控制器

當前版本包含了三個控制器：核心、文章和響應。鼓勵開發者建議或者提出其他的控制器。

進一步閱讀：

見第2節：可用控制器和完整請求方式參考。有關使用新的控制器擴充套件JSON API文件見5.2：開發JSON API控制器。

1.3 Responses

對於JSON API的標準響應，格式是JSON。

下面是一個來自 http://localhost/wordpress/?json=1 示例響應，它是預設的WP安裝資訊：

{
  "status": "ok",
  "count": 1,
  "count_total": 1,
  "pages": 1,
  "posts": [
    {
      "id": 1,
      "type": "post",
      "slug": "hello-world",
      "url": "http:\/\/localhost\/wordpress\/?p=1",
      "title": "Hello world!",
      "title_plain": "Hello world!",
      "content": "<p>Welcome to WordPress. This is your first post. Edit or delete it, then start blogging!<\/p>\n",
      "excerpt": "Welcome to WordPress. This is your first post. Edit or delete it, then start blogging!\n",
      "date": "2009-11-11 12:50:19",
      "modified": "2009-11-11 12:50:19",
      "categories": [],
      "tags": [],
      "author": {
        "id": 1,
        "slug": "admin",
        "name": "admin",
        "first_name": "",
        "last_name": "",
        "nickname": "",
        "url": "",
        "description": ""
      },
      "comments": [
        {
          "id": 1,
          "name": "Mr WordPress",
          "url": "http:\/\/wordpress.org\/",
          "date": "2009-11-11 12:50:19",
          "content": "<p>Hi, this is a comment.<br \/>To delete a comment, just log in and view the post's comments. There you will have the option to edit or delete them.<\/p>\n",
          "parent": 0
        }
      ],
      "comment_count": 1,
      "comment_status": "open"
    }
  ]
}

2.請求方法

請求方法可以從以下控制器得到：

核心控制器：基本內省方法
文章控制器：文章資料處理方法
響應控制器：評論/引用提交方法
桌面部件控制器：檢索側邊欄小部件方法

2.1 核心控制方法

核心控制器提供了一套基本完成的從WordPress的檢索內容的內省方法。

方法：info

返回關於JSON API的相關資訊。

可選引數

controller：返回一個指定控制器的詳細資訊。

普通響應：

{
  "status": "ok",
  "json_api_version": "1.0",
  "controllers": [
    "core"
  ]
}

指定控制器為核心的響應：

{
  "status": "ok",
  "name": "Core",
  "description": "Basic introspection methods",
  "methods": [
    ...
  ]
}

方法：`get_recent_posts`

返回一個最近文章的集合。

你可以呼叫這些：

通過設定JSON為一個非空值（即json=1）來從WP主頁獲取;
通過設定json=get_recent_posts從任何頁面獲取。

可選引數

count – 決定返回多少數量的最近文章，預設為10；
page – 返回一個結果中的指定頁面號；
post_type – 用於檢索自定義文章型別。

響應：

{
  "status": "ok",
  "count": 10,
  "count_total": 79,
  "pages": 7,
  "posts": [
    { ... },
    { ... },
    ...
  ]
}

方法：`get_posts`

返回根據WP的WP_Query引數獲取的文章，預設的引數是ignore_sticky_posts=1，它可以被覆蓋。

可選引數

count – 決定返回多少數量的最近文章，預設為10；
page – 返回一個結果中的指定頁面號；
post_type – 用於檢索自定義文章型別。

進一步閱讀

檢視WP_Query文件對於支援引數的完整列表，目前post_status被忽略。

響應：

{
  "status": "ok",
  "count": 1,
  "posts": [
    { ... }
  ]
}

方法：`get_post`

返回一個簡單的文章物件

下面其中一個是必需的

在一個文章URL中隱式呼叫JSON API，也就是（?json=1）；
id / post_id – 設定文章ID；
slug / post_slug – 設定文章的URL的slug。

slug是指wordpress在啟用了偽靜態後，你的文章(post)與頁面(page)、標籤(tag)、分類(Category)在訪問的時候顯示在瀏覽器位址列上域名後面的地址。

可選引數

post_type – 用於檢索自定義文章型別。

響應：

{
  "status": "ok",
  "post": { ... }
}

方法：`get_page`

返回一個簡單的頁面物件

下面其中一個是必需的

在一個文章URL中隱式呼叫JSON API，也就是（?json=1）；
id / post_id ：設定文章ID；
slug / post_slug ：設定文章的URL的slug。

可選引數

children – 設定一個非空值來包括子頁面的遞迴層次結構；
post_type – 用於檢索自定義文章型別。

響應：

{
  "status": "ok",
  "page": { ... }
}

方法：`get_date_posts`

返回一個指定日期（年、月、日）歸檔的文章或者頁面集合。

下面其中一個是必需的

日期歸檔頁面上隱含呼叫JSON API（即？JSON=1）；
date – 設定一個日期格式比如 YYYY、YYYY-MM、YYYY-MM-DD（非數字字元會從變數中剝離，所以YYYYMMDD、YYYY/MM/DD也是有效的）

可選引數

count – 決定返回多少數量的最近文章，預設為10；
page – 返回一個結果中的指定頁面號；
post_type – 用於檢索自定義文章型別。

響應：

{
  "status": "ok",
  "count": 10,
  "count_total": 79,
  "pages": 7,
  "posts": [
    { ... },
    { ... },
    ...
  ]
}

方法：`get_category_posts`

返回一個指定分類的文章或者頁面集合。

下面其中一個是必需的

類別檔案頁面上隱含呼叫JSON API（即？JSON=1）
id or category_id – 設定分類ID
slug or category_slug – 設定分類URL的slug

可選引數

count – 決定返回多少數量的最近文章，預設為10；
page – 返回一個結果中的指定頁面號；
post_type – 用於檢索自定義文章型別。

響應：

{
  "status": "ok",
  "count": 10,
  "count_total": 79,
  "pages": 7,
  "category": { ... }
  "posts": [
    { ... },
    { ... },
    ...
  ]
}

方法：`get_tag_posts`

返回一個指定標籤的文章或者頁面集合。

下面其中一個是必需的

類別檔案頁面上隱含呼叫JSON API（即？JSON=1）
id or tag_id – 設定標籤ID
slug or tag_slug – 設定標籤URL的slug

可選引數

count – 決定返回多少數量的最近文章，預設為10；
page – 返回一個結果中的指定頁面號；
post_type – 用於檢索自定義文章型別。

響應：

{
  "status": "ok",
  "count": 10,
  "count_total": 79,
  "pages": 7,
  "tag": { ... }
  "posts": [
    { ... },
    { ... },
    ...
  ]
}

方法：`get_author_posts`

返回一個指定作者的文章或頁面集合。

下面其中一個是必需的

類別檔案頁面上隱含呼叫JSON API（即？JSON=1）
id or author_id – 設定作者ID
slug or author_slug – 設定作者URL的slug

可選引數

count – 決定返回多少數量的最近文章，預設為10；
page – 返回一個結果中的指定頁面號；
post_type – 用於檢索自定義文章型別。

響應：

{
  "status": "ok",
  "count": 10,
  "count_total": 79,
  "pages": 7,
  "author": { ... }
  "posts": [
    { ... },
    { ... },
    ...
  ]
}

方法：`get_search_results`

返回文章/頁面響應搜尋查詢的集合。

下面其中一個是必需的

一個搜尋結果頁上隱含呼叫JSON API（即？JSON=1）
search – 設定希望查詢的內容

可選引數

count – 決定返回多少數量的最近文章，預設為10；
page – 返回一個結果中的指定頁面號；
post_type – 用於檢索自定義文章型別。

響應：

{
  "status": "ok",
  "count": 10,
  "count_total": 79,
  "pages": 7,
  "posts": [
    { ... },
    { ... },
    ...
  ]
}

方法：`get_date_index`

返回日期頁面的永久連結的集合和樹狀的歸檔檔案。

響應：

{
  "status": "ok",
  "permalinks": [
    "...",
    "...",
    "..."
  ],
  "tree": {
    "2009": {
      "09": 17,
      "10": 20,
      "11": 7
    }
  }
}

方法：`get_category_index`

返回有效的分類集合

可選引數

parent – 返回父類Id的直接子類

響應：

{
  "status": "ok",
  "count": 3,
  "categories": [
    { ... },
    { ... },
    { ... }
  ]
}

方法：`get_tag_index`

返回有效的標籤集合

響應：

{
  "status": "ok",
  "count": 3
  "tags": [
    { ... },
    { ... },
    { ... }
  ]
}

方法：`get_author_index`

返回有效的部落格作者

響應：

{
  "status": "ok",
  "count": 3,
  "authors": [
    { ... },
    { ... },
    { ... }
  ]
}

方法：`get_page_index`

返回一個頁面文章的層次樹。

響應：

{
  "status": "ok",
  "pages": [
    { ... },
    { ... },
    { ... }
  ]
}

方法：`get_nonce`

返回一個WordPress的現時價值，呼叫一些所需的資料操作方法。

必需引數

controller – 該方法的JSON API控制器將用於該隨機數
method-要呼叫的方法（目前create_post是得到隨機數的唯一方法）

響應：

{
  "status": "ok",
  "controller": "posts",
  "method": "create_post",
  "nonce": "cefe01efd4"
}

進一步閱讀：

要了解更多關於隨機數如何在WordPress的使用，請看Mark Jaquith’s article on the subject。

2.2 文章控制器方法

方法：`create_post`

新建一篇文章

必需引數

nonce – 可從getnonce方法得到可用的（呼叫變數controller=posts和method=createpost）

可選引數

status – 設定後的狀態（”草稿”或”釋出”），預設是”草稿”；
title – 文章標題；
content – 文章內容；
author – 這篇文章的作者（登入名），預設為當前登入使用者；
categories – 以逗號分隔的分類列表（固定URL）；
tags – 一個以逗號分隔的標籤列表（固定URL）。

注意：包括上傳附件的 attachment 欄位，將儲存在您的新文章。

方法：`update_post`

更新一篇文章。

必需引數

nonce – 可從getnonce方法得到可用的（呼叫變數controller=posts和method=createpost）

下面其中一個是必需的

id / post_id ：設定文章ID；
slug / post_slug ：設定文章的URL的slug。

可選引數

status – 設定後的狀態（”草稿”或”釋出”），預設是”草稿”；
title – 文章標題；
content – 文章內容；
author – 這篇文章的作者（登入名），預設為當前登入使用者；
categories – 以逗號分隔的分類列表（固定URL）；
tags – 一個以逗號分隔的標籤列表（固定URL）。

注意：包括上傳附件的 attachment 欄位，將儲存在您的新文章。

方法：`delete_post`

刪除一篇文章。

必需引數

nonce – 可從getnonce方法得到可用的（呼叫變數controller=posts和method=createpost）

下面其中一個是必需的

id / post_id ：設定文章ID；
slug / post_slug ：設定文章的URL的slug。

2.3 響應控制器方法

方法：`submit_comment`

提交一個評論到WP文章。

必需引數

post_id – 文章id
name – 評論者的名字
email – 評論者的電子郵件地址
content – 評論內容

可選引數

redirect – 重定向而不是返回JSON物件
redirect_ok – 重定向到一個特定的URL時的狀態值 ok
redirect_error – 重定向到一個特定的URL時的狀態值 error
redirect_pending – 重定向到一個特定的URL時的狀態值 pending

自定義狀態值

pending – 如果評論是提交待稽核的時候指定

2.4 小部件控制器方法

方法：`get_sidebar`

檢索分配到側邊欄的小工具。

必需引數

sidebar_id – 側邊欄的名稱或編號檢索。

3、請求引數

API請求可以通過指定下列引數之一作為URL查詢變數。

舉例：

除錯回應： http://www.example.org/api/getpageindex/?dev=1
控制元件樣式JSONP輸出： http://www.example.org/api/getrecentposts/?callback=show_postswidget&readmore=More&count=3
重定向錯誤： http://www.example.org/api/posts/createpost/?callbackerror=http%3A%2F%2Fwww.example.org%2Fhelp.html

3.1 輸出修飾引數

下面的引數修飾你從API返回什麼樣的結果。重定向響應樣式用於資料處理方法中。

設定 callback JavaScript函式名將觸發JSONP式的回撥。
設定 redirect 到URL會導致使用者的瀏覽器重定向到指定的、追加狀態值到查詢變數中的URL（見下面一節響應物件對狀態值的解釋）。
設定 redirect_[status] 允許您根據不同的status值控制瀏覽器重定向。
設定 dev 一個非空值增加了text/plain可讀性和空白響應。
誤差被抑制，除非dev被設為非空值。
設定 jsonencodeoptions 將讓您指定整數位掩碼來修改PHP的json_encode（注：此選項僅在PHP版本公認5.3+）
設定 jsonunescapedunicode 將其轉義等效替代的Unicode轉義字元。
省略所有上述引數將導致一個標準JSON響應。

3.2 內容修飾引數

這些引數可以修飾所有內省的方法：

date_format-更改日期值的格式。使用相同的語法是PHP的 data() 函式。預設值是Y-m-d H:i:s。
read_more – 改變”閱讀更多”在文章內容中的連結文字。
include – 指定文章哪個資料欄位。要求用逗號分隔後的欄位列表。所有的欄位不能為空。
exclude – 指定排除文章哪個資料欄位。要求用逗號分隔後的欄位列表。
custom_fields – 包括文章自定義的欄位。要求逗號分隔的自定義欄位的鍵列表。
author_meta – 包括額外的後設資料的作者。應該是一個逗號分隔的後設資料欄位列表。
count – 控制文章數目，包括（預設為由WordPress指定的號碼）
order – 控制文章結果的順序（“DESC”或“ASC”）。預設值是’DESC’。
order_by – 控制哪些欄位結果需要排序。要求是下列值之一：
- author
- date （預設值）
- title
- modified
- menu_order （只在頁面有作用）
- parent
- ID
- rand
- metavalue（metakey也必須設定）
- none
- comment_count
metakey，metavalue，meta_compare-檢索基於自定義欄位中的鍵或值的文章（或頁面）。

3.3 使用 `include`/`exclude`/`redirects`

關於 `include`/`exclude`引數

預設情況下你會得到包括每個文章物件的所有值。指定列表中的 include 值可以讓物件過濾掉一些沒有的值。指定列表的 exclude 可以讓文章物件包含除去你的列表中的欄位的所有值。比如查詢 exclude=comments 會包含除去comments的所有值。

關於`redirects`引數

重定向響應樣式作用在於當你需要使用者在瀏覽器發出請求而不是使用像cURL那樣的代理請求。設定一個 redirect 引數會讓使用者瀏覽器重新想到指定的URL而不是返回一個JSON物件，由此產生的狀態值是作為一個額外的查詢變數。

例如用redicect呼叫API的方法設定為http://www.example.com/foo將導致重定向到下列之一：

http://www.example.com/foo?status=ok
http://www.example.com/foo?status=error
您還可以設定不同的網址，以不同方式處理狀態值。您可以設定redirectok為http://www.example.com/handleok，並redirecterror為http://www.example.com/handleerror，為了有更多的調整控制方法的結果。

4、響應物件

本節介紹您可以從WordPress的檢索資料物件和可選的URL重定向。

狀態值

所有的JSON API請求結果中都有狀態值。這兩個基本狀態值ok和error。附加狀態值可用於某些方法（如pending在的情況下，submit_comment方法）。這裡自定義狀態值的API方法在文件中包含自定義狀態值的這一節。

命名相容性

熟悉WordPress開發可能會注意到效能和引數的許多名字已被更改。這是一個風格上的選擇，打算提供更多的清晰度和一致性的介面。

4.1 文章響應物件

id – Integer
type – String (例如文章或者頁面)
slug – String
url – String
title – String
title_plain – String
content – String (通過修改 read_more引數)
excerpt – String
date – String (通過修改date_format引數)
modified – String (通過修改date_format引數)
categories – 分類物件集合
tags – 標籤物件集合
author – 作者物件
comments – 評論物件集合
attachments – 附件物件集合
comment_count – Integer
comment_status – String (“open” 或者 “closed”)
thumbnail – String (只在指定一個縮圖)
customfields – Object (通過設定包括customfields引數用逗號分隔的自定義欄位名稱列表)
taxonomy_(taxonomy) – 自定義分類物件的集合 (這些類似分類或標籤響應物件，依賴於分類是否是層級的)

注意：該thumbnail屬性返回URL通過可選引數thumbnail_size指定的圖片尺寸。預設情況下，這將使用 thumbnail 或 post-thumbnail 大小，取決於你的WordPress版本。

4.2. 分類響應物件

id – Integer
slug – String
title – String
description – String
parent – Integer
post_count – Integer

4.3. 標籤響應物件

id – Integer
slug – String
title – String
description – String
post_count – Integer

4.4. 作者響應物件

id – Integer
slug – String
name – String
first_name – String
last_name – String
nickname – String
url – String
description – String

**注意：您可以通過設定包括其他值author_meta引數，以逗號分隔的後設資料欄位列表。 **

4.5. 評論響應物件

id – Integer
name – String
url – String
date – String
content – String
parent – Integer
author – Object (只在評論作者已經註冊或登入)

4.6. 附件響應物件

id – Integer
url – String
slug – String
title – String
description – String
caption – String
parent – Integer
mime_type – String
images – 有值的物件包括thumbnail，medium，large，full，其中每一個具有url，width和height的物件，只在附件是圖片的時候起作用。

Draft 文件翻譯 - API - ContentState
2021-09-09
RaftAPI
Draft 文件翻譯 - 快速開始 - 基礎API
2021-09-09
RaftAPI
Unity Networking API文件翻譯（二）：The High Level API
2015-12-16
UnityAPI
文件翻譯器怎麼用？如何翻譯Word文件？
2019-08-15
JavaPoet 文件翻譯
2018-02-19
Java
有ppt文件翻譯軟體嗎？如何翻譯整篇ppt文件
2019-08-16
MPAndroidChart文件翻譯
2019-02-19
Android
Moya官方文件翻譯
2018-03-21
Samza文件翻譯 : Backgroud
2014-04-06
本人翻譯的文件
2005-03-02
Unity Networking API文件翻譯（一）：Networking概述
2015-12-05
UnityAPI
實用的Word文件翻譯方法分享，讓Word文件快速翻譯
2019-08-12
怎麼翻譯整篇Excel文件？Excel文件翻譯一招搞定
2019-08-14
Excel
UIScrollView API 翻譯
2013-12-28
UIViewAPI
angular -- $route API翻譯
2014-07-17
AngularAPI
angular -- $routeParams API翻譯
2014-07-16
AngularAPI
Google翻譯的API
2008-03-25
GoAPI
怎麼把Excel文件翻譯成中文？Excel文件翻譯方法介紹
2019-08-21
Excel
docker官方文件翻譯3
2019-02-22
Docker
SnapKit 中文文件翻譯
2019-03-04
APK
docker官方文件翻譯4
2019-02-17
Docker
rabbitmq 官方文件翻譯-2
2019-02-16
MQ
docker官方文件翻譯5
2018-05-08
Docker
docker官方文件翻譯2
2018-05-01
Docker
docker官方文件翻譯1
2018-05-01
Docker
Core Foundation 官方文件翻譯
2017-06-22
Samza文件翻譯 : Architecture
2014-04-06
Akka Stream文件翻譯：Motivation
2015-04-13
Guava文件翻譯之 Service
2016-01-22
Guava
Guava文件翻譯之ListenableFuture
2016-01-21
Guava
expat介紹文件翻譯
2012-03-22
TailWind文件翻譯說明以及每日翻譯進度
2021-01-19
AI
JSON and Microsoft Technologies（翻譯）
2014-12-26
JSONROS
使用google翻譯 api 翻譯中文成其他語言
2018-08-06
GoAPI
puppeteer 呼叫谷歌翻譯api
2024-04-22
谷歌API
HTTPie 官方文件中文翻譯版
2019-02-16
HTTP
influxdb官網文件翻譯
2018-07-30
UX
Gin 框架中文文件（翻譯）
2018-07-13
框架

JSON API for WP 文件翻譯

1.基本概念

1.1 Requsets 請求

1.2 控制器

2.請求方法

2.1 核心控制方法

方法：info

方法：get_recent_posts

方法：get_posts

方法：get_post

方法：get_page

方法：get_date_posts

方法：get_category_posts

方法：get_tag_posts

方法：get_author_posts

方法：get_search_results

方法：get_date_index

方法：get_category_index

方法：get_tag_index

方法：get_author_index

方法：get_page_index

方法：get_nonce

2.2 文章控制器方法

方法：create_post

方法：update_post

方法：delete_post

2.3 響應控制器方法

方法：submit_comment

2.4 小部件控制器方法

方法：get_sidebar

3、請求引數

3.1 輸出修飾引數

3.2 內容修飾引數

3.3 使用 include/exclude/redirects

關於 include/exclude引數

關於redirects引數

4、響應物件

4.1 文章響應物件

4.2. 分類響應物件

4.3. 標籤響應物件

4.4. 作者響應物件

4.5. 評論響應物件

4.6. 附件響應物件

相關文章

方法：`get_recent_posts`

方法：`get_posts`

方法：`get_post`

方法：`get_page`

方法：`get_date_posts`

方法：`get_category_posts`

方法：`get_tag_posts`

方法：`get_author_posts`

方法：`get_search_results`

方法：`get_date_index`

方法：`get_category_index`

方法：`get_tag_index`

方法：`get_author_index`

方法：`get_page_index`

方法：`get_nonce`

方法：`create_post`

方法：`update_post`

方法：`delete_post`

方法：`submit_comment`

方法：`get_sidebar`

3.3 使用 `include`/`exclude`/`redirects`

關於 `include`/`exclude`引數

關於`redirects`引數