云策 WordPress 开发者社区

REST API 文档

Tags

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

概述

本文档详细介绍了 WordPress REST API 中标签（Tags）的架构和端点操作。标签作为分类术语的一种类型，具有特定的字段定义，支持通过 API 进行列表查询、创建、检索、更新和删除操作。

关键要点

  • 标签架构包含 id、count、description、link、name、slug、taxonomy 和 meta 等字段，每个字段有 JSON 数据类型、只读属性和上下文限制。
  • 标签端点包括 GET /wp/v2/tags（列表查询）、POST /wp/v2/tags（创建）、GET /wp/v2/tags/<id>（检索）、POST /wp/v2/tags/<id>（更新）和 DELETE /wp/v2/tags/<id>（删除）。
  • 列表查询支持多种参数，如 context、page、per_page、search、orderby 等，用于过滤和排序结果。
  • 创建和更新标签时，name 字段为必填，其他如 description、slug 和 meta 为可选。
  • 删除标签需指定 id 和 force=true 参数，因为标签不支持垃圾回收。

代码示例

// 示例请求：列出标签
$ curl https://example.com/wp-json/wp/v2/tags

// 示例请求：检索特定标签
$ curl https://example.com/wp-json/wp/v2/tags/<id>

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

Schema

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

JSON data type: integer

Read only

Context: view, embed, edit
count Number of published posts for the term.

JSON data type: integer

Read only

Context: view, edit
description HTML description of the term.

JSON data type: string

Context: view, edit
name HTML title for the term.

JSON data type: string

Context: view, embed, edit
slug An alphanumeric identifier for the term unique to its type.

JSON data type: string

Context: view, embed, edit
taxonomy Type attribution for the term.

JSON data type: string

Read only

Context: view, embed, edit

One of: post_tag

meta Meta fields.

JSON data type: object

Context: view, edit

List Tags

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

Definition

GET /wp/v2/tags

Example Request

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

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 term attribute.

Default: name

One of: id, include, name, slug, include_slugs, term_group, description, count

hide_empty Whether to hide terms not assigned to any posts.
post Limit result set to terms assigned to a specific post.
slug Limit result set to terms with one or more specific slugs.

Create a Tag

Arguments

<a href="#schema-description">description</a> HTML description of the term.
<a href="#schema-name">name</a> HTML title for the term.

Required: 1

<a href="#schema-slug">slug</a> An alphanumeric identifier for the term unique to its type.
<a href="#schema-meta">meta</a> Meta fields.

Definition

POST /wp/v2/tags

Retrieve a Tag

Definition & Example Request

GET /wp/v2/tags/<id>

Query this endpoint to retrieve a specific tag record.

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

Arguments

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

Default: view

One of: view, embed, edit

Update a Tag

Arguments

<a href="#schema-id">id</a> Unique identifier for the term.
<a href="#schema-description">description</a> HTML description of the term.
<a href="#schema-name">name</a> HTML title for the term.
<a href="#schema-slug">slug</a> An alphanumeric identifier for the term unique to its type.
<a href="#schema-meta">meta</a> Meta fields.

Definition

POST /wp/v2/tags/<id>

Example Request

Delete a Tag

Arguments

id Unique identifier for the term.
force Required to be true, as terms do not support trashing.

Definition

DELETE /wp/v2/tags/<id>

Example Request

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