云策 WordPress 开发者社区

REST API 文档

Comments

查看官方原文 ↗
💡 云策文档标注

概述

本文档详细介绍了 WordPress REST API 中评论（Comments）相关的端点、数据结构和操作。核心内容包括评论的 Schema 定义、列表查询、创建、检索、更新和删除等 RESTful 接口，适用于开发者进行评论数据的管理和集成。

关键要点

  • Schema 定义了评论记录的字段，如 id、author、content、date、status 等，每个字段包含 JSON 数据类型、上下文和只读属性。
  • 支持通过 GET /wp/v2/comments 查询评论列表，可使用 context、page、per_page、search、author、post 等参数进行过滤和分页。
  • 提供创建（POST /wp/v2/comments）、检索（GET /wp/v2/comments/<id>）、更新（POST /wp/v2/comments/<id>）和删除（DELETE /wp/v2/comments/<id>）评论的端点，每个操作有特定的参数要求。
  • 部分操作如 author、author_email、status 等需要授权（Requires authorization），确保数据安全。

代码示例

// 示例请求：列出评论
$ curl https://example.com/wp-json/wp/v2/comments

// 示例请求：删除评论
$ curl -X DELETE https://example.com/wp-json/wp/v2/comments/<id>

注意事项

  • 使用 _filter 查询参数可以控制响应字段，否则默认包含所有 Schema 字段。
  • 日期字段如 date 和 date_gmt 使用 ISO8601 格式，需注意时区处理。
  • 删除操作时，force 参数可绕过回收站直接删除，需谨慎使用。
  • 对于受密码保护的文章，需提供 password 参数以访问相关评论。
📄 原文内容

Schema

The schema defines all the fields that exist within a comment record. Any response from these endpoints can be expected to contain the fields below unless the `_filter` query parameter is used or the schema field only appears in a specific context.

id Unique identifier for the comment.

JSON data type: integer

Read only

Context: view, edit, embed
author The ID of the user object, if author was a user.

JSON data type: integer

Context: view, edit, embed
author_email Email address for the comment author.

JSON data type: string,
Format: email

Context: edit
author_ip IP address for the comment author.

JSON data type: string,
Format: ip

Context: edit
author_name Display name for the comment author.

JSON data type: string

Context: view, edit, embed
author_url URL for the comment author.

JSON data type: string,
Format: uri

Context: view, edit, embed
author_user_agent User agent for the comment author.

JSON data type: string

Context: edit
content The content for the comment.

JSON data type: object

Context: view, edit, embed
date The date the comment was published, in the site's timezone.

JSON data type: string,
Format: datetime (details)

Context: view, edit, embed
date_gmt The date the comment was published, as GMT.

JSON data type: string,
Format: datetime (details)

Context: view, edit
parent The ID for the parent of the comment.

JSON data type: integer

Context: view, edit, embed
post The ID of the associated post object.

JSON data type: integer

Context: view, edit
status State of the comment.

JSON data type: string

Context: view, edit
type Type of the comment.

JSON data type: string

Read only

Context: view, edit, embed
author_avatar_urls Avatar URLs for the comment author.

JSON data type: object

Read only

Context: view, edit, embed
meta Meta fields.

JSON data type: object

Context: view, edit

List Comments

Query this endpoint to retrieve a collection of comments. The response you receive can be controlled and filtered using the URL query parameters below.

Definition

GET /wp/v2/comments

Example Request

$ curl https://example.com/wp-json/wp/v2/comments

Arguments

context Scope under which the request is made; determines fields present in response.

Default: view

One of: view, embed, edit

page Current page of the collection.

Default: 1

per_page Maximum number of items to be returned in result set.

Default: 10

search Limit results to those matching a string.
after Limit response to comments published after a given ISO8601 compliant date.
author Limit result set to comments assigned to specific user IDs. Requires authorization.
author_exclude Ensure result set excludes comments assigned to specific user IDs. Requires authorization.
author_email Limit result set to that from a specific author email. Requires authorization.
before Limit response to comments published before a given ISO8601 compliant date.
exclude Ensure result set excludes specific IDs.
include Limit result set to specific IDs.
offset Offset the result set by a specific number of items.
order Order sort attribute ascending or descending.

Default: desc

One of: asc, desc

orderby Sort collection by comment attribute.

Default: date_gmt

One of: date, date_gmt, id, include, post, parent, type

parent Limit result set to comments of specific parent IDs.
parent_exclude Ensure result set excludes specific parent IDs.
post Limit result set to comments assigned to specific post IDs.
status Limit result set to comments assigned a specific status. Requires authorization.

Default: approve

type Limit result set to comments assigned a specific type. Requires authorization.

Default: comment

password The password for the post if it is password protected.

Create a Comment

Arguments

<a href="#schema-author">author</a> The ID of the user object, if author was a user.
<a href="#schema-author_email">author_email</a> Email address for the comment author.
<a href="#schema-author_ip">author_ip</a> IP address for the comment author.
<a href="#schema-author_name">author_name</a> Display name for the comment author.
<a href="#schema-author_url">author_url</a> URL for the comment author.
<a href="#schema-author_user_agent">author_user_agent</a> User agent for the comment author.
<a href="#schema-content">content</a> The content for the comment.
<a href="#schema-date">date</a> The date the comment was published, in the site's timezone.
<a href="#schema-date_gmt">date_gmt</a> The date the comment was published, as GMT.
<a href="#schema-parent">parent</a> The ID for the parent of the comment.
<a href="#schema-post">post</a> The ID of the associated post object.
<a href="#schema-status">status</a> State of the comment.
<a href="#schema-meta">meta</a> Meta fields.

Definition

POST /wp/v2/comments

Retrieve a Comment

Definition & Example Request

GET /wp/v2/comments/<id>

Query this endpoint to retrieve a specific comment record.

$ curl https://example.com/wp-json/wp/v2/comments/<id>

Arguments

id Unique identifier for the comment.
context Scope under which the request is made; determines fields present in response.

Default: view

One of: view, embed, edit

password The password for the parent post of the comment (if the post is password protected).

Update a Comment

Arguments

<a href="#schema-id">id</a> Unique identifier for the comment.
<a href="#schema-author">author</a> The ID of the user object, if author was a user.
<a href="#schema-author_email">author_email</a> Email address for the comment author.
<a href="#schema-author_ip">author_ip</a> IP address for the comment author.
<a href="#schema-author_name">author_name</a> Display name for the comment author.
<a href="#schema-author_url">author_url</a> URL for the comment author.
<a href="#schema-author_user_agent">author_user_agent</a> User agent for the comment author.
<a href="#schema-content">content</a> The content for the comment.
<a href="#schema-date">date</a> The date the comment was published, in the site's timezone.
<a href="#schema-date_gmt">date_gmt</a> The date the comment was published, as GMT.
<a href="#schema-parent">parent</a> The ID for the parent of the comment.
<a href="#schema-post">post</a> The ID of the associated post object.
<a href="#schema-status">status</a> State of the comment.
<a href="#schema-meta">meta</a> Meta fields.

Definition

POST /wp/v2/comments/<id>

Example Request

Delete a Comment

Arguments

id Unique identifier for the comment.
force Whether to bypass Trash and force deletion.
password The password for the parent post of the comment (if the post is password protected).

Definition

DELETE /wp/v2/comments/<id>

Example Request

$ curl -X DELETE https://example.com/wp-json/wp/v2/comments/<id>