云策 WordPress 开发者社区

REST API 文档

Users

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

概述

本文档详细介绍了 WordPress REST API 中用户相关的端点，包括用户数据模式、列表查询、创建、检索、更新和删除操作。面向开发者，提供了完整的字段定义和请求参数说明。

关键要点

  • 用户模式定义了用户记录的所有字段，如 id、username、email、roles 等，每个字段包含 JSON 数据类型、上下文和只读属性。
  • 支持通过 GET /wp/v2/users 查询用户列表，可使用 context、page、per_page、search、orderby 等参数进行过滤和排序。
  • 创建用户使用 POST /wp/v2/users，必需参数包括 username、email 和 password。
  • 检索、更新和删除用户分别通过 GET、POST 和 DELETE 方法操作 /wp/v2/users/<id> 或 /wp/v2/users/me 端点。
  • 删除用户时需指定 force 和 reassign 参数，以处理用户文章和链接的重新分配。

代码示例

// 示例请求：获取用户列表
$ curl https://example.com/wp-json/wp/v2/users

// 示例请求：删除用户
$ curl -X DELETE https://example.com/wp-json/wp/v2/users/<id>
📄 原文内容

Schema

The schema defines all the fields that exist within a user 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 user.

JSON data type: integer

Read only

Context: embed, view, edit
username Login name for the user.

JSON data type: string

Context: edit
name Display name for the user.

JSON data type: string

Context: embed, view, edit
first_name First name for the user.

JSON data type: string

Context: edit
last_name Last name for the user.

JSON data type: string

Context: edit
email The email address for the user.

JSON data type: string,
Format: email

Context: edit
url URL of the user.

JSON data type: string,
Format: uri

Context: embed, view, edit
description Description of the user.

JSON data type: string

Context: embed, view, edit
locale Locale for the user.

JSON data type: string

Context: edit

One of: , en_US

nickname The nickname for the user.

JSON data type: string

Context: edit
slug An alphanumeric identifier for the user.

JSON data type: string

Context: embed, view, edit
registered_date Registration date for the user.

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

Read only

Context: edit
roles Roles assigned to the user.

JSON data type: array

Context: edit
password Password for the user (never included).

JSON data type: string

Context:

capabilities All capabilities assigned to the user.

JSON data type: object

Read only

Context: edit
extra_capabilities Any extra capabilities assigned to the user.

JSON data type: object

Read only

Context: edit
avatar_urls Avatar URLs for the user.

JSON data type: object

Read only

Context: embed, view, edit
meta Meta fields.

JSON data type: object

Context: view, edit

List Users

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

Definition

GET /wp/v2/users

Example Request

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

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.
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: asc

One of: asc, desc

orderby Sort collection by user attribute.

Default: name

One of: id, include, name, registered_date, slug, include_slugs, email, url

slug Limit result set to users with one or more specific slugs.
roles Limit result set to users matching at least one specific role provided. Accepts csv list or single role.
capabilities Limit result set to users matching at least one specific capability provided. Accepts csv list or single capability.
who Limit result set to users who are considered authors.
One of: authors
has_published_posts Limit result set to users who have published posts.

Create a User

Arguments

<a href="#schema-username">username</a> Login name for the user.

Required: 1

<a href="#schema-name">name</a> Display name for the user.
<a href="#schema-first_name">first_name</a> First name for the user.
<a href="#schema-last_name">last_name</a> Last name for the user.
<a href="#schema-email">email</a> The email address for the user.

Required: 1

<a href="#schema-url">url</a> URL of the user.
<a href="#schema-description">description</a> Description of the user.
<a href="#schema-locale">locale</a> Locale for the user.
One of: , en_US
<a href="#schema-nickname">nickname</a> The nickname for the user.
<a href="#schema-slug">slug</a> An alphanumeric identifier for the user.
<a href="#schema-roles">roles</a> Roles assigned to the user.
<a href="#schema-password">password</a> Password for the user (never included).

Required: 1

<a href="#schema-meta">meta</a> Meta fields.

Definition

POST /wp/v2/users

Retrieve a User

Definition & Example Request

GET /wp/v2/users/<id>

Query this endpoint to retrieve a specific user record.

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

Arguments

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

Default: view

One of: view, embed, edit

Update a User

Arguments

<a href="#schema-id">id</a> Unique identifier for the user.
<a href="#schema-username">username</a> Login name for the user.
<a href="#schema-name">name</a> Display name for the user.
<a href="#schema-first_name">first_name</a> First name for the user.
<a href="#schema-last_name">last_name</a> Last name for the user.
<a href="#schema-email">email</a> The email address for the user.
<a href="#schema-url">url</a> URL of the user.
<a href="#schema-description">description</a> Description of the user.
<a href="#schema-locale">locale</a> Locale for the user.
One of: , en_US
<a href="#schema-nickname">nickname</a> The nickname for the user.
<a href="#schema-slug">slug</a> An alphanumeric identifier for the user.
<a href="#schema-roles">roles</a> Roles assigned to the user.
<a href="#schema-password">password</a> Password for the user (never included).
<a href="#schema-meta">meta</a> Meta fields.

Definition

POST /wp/v2/users/<id>

Example Request

Delete a User

Arguments

id Unique identifier for the user.
force Required to be true, as users do not support trashing.
reassign Reassign the deleted user's posts and links to this user ID.

Required: 1

Definition

DELETE /wp/v2/users/<id>

Example Request

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

Retrieve a User

Definition & Example Request

GET /wp/v2/users/me

Query this endpoint to retrieve a specific user record.

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

Arguments

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

Default: view

One of: view, embed, edit

Update a User

Arguments

<a href="#schema-username">username</a> Login name for the user.
<a href="#schema-name">name</a> Display name for the user.
<a href="#schema-first_name">first_name</a> First name for the user.
<a href="#schema-last_name">last_name</a> Last name for the user.
<a href="#schema-email">email</a> The email address for the user.
<a href="#schema-url">url</a> URL of the user.
<a href="#schema-description">description</a> Description of the user.
<a href="#schema-locale">locale</a> Locale for the user.
One of: , en_US
<a href="#schema-nickname">nickname</a> The nickname for the user.
<a href="#schema-slug">slug</a> An alphanumeric identifier for the user.
<a href="#schema-roles">roles</a> Roles assigned to the user.
<a href="#schema-password">password</a> Password for the user (never included).
<a href="#schema-meta">meta</a> Meta fields.

Definition

POST /wp/v2/users/me

Example Request

Delete a User

Arguments

force Required to be true, as users do not support trashing.
reassign Reassign the deleted user's posts and links to this user ID.

Required: 1

Definition

DELETE /wp/v2/users/me

Example Request

$ curl -X DELETE https://example.com/wp-json/wp/v2/users/me