# 增删改查操作

> Source: https://strapi.nodejs.cn/cms/api/entity-service/crud

🌐 CRUD operations with the Entity Service API

实体服务 API 通过 `findOne()`、`findMany()`、`create()`、`update()` 和 `delete()` 方法对内容执行 CRUD 操作，支持过滤、分页、关联和本地化。

🌐 The Entity Service API performs CRUD operations on content through `findOne()`, `findMany()`, `create()`, `update()`, and `delete()` methods, supporting filtering, pagination, relations, and localization.

:::caution

在 Strapi v5 中，实体服务 API 已被弃用。请考虑改用 [文档服务 API](/cms/api/document-service)。

🌐 The Entity Service API is deprecated in Strapi v5. Please consider using the [Document Service API](/cms/api/document-service) instead.

:::

[实体服务 API](/cms/api/entity-service) 构建在 [查询引擎 API](/cms/api/query-engine) 之上，并使用它对实体执行 CRUD 操作。

🌐 The [Entity Service API](/cms/api/entity-service) is built on top of the the [Query Engine API](/cms/api/query-engine) and uses it to perform CRUD operations on entities.

在此 API 的函数调用中使用的 `uid` 参数是一个按以下格式构建的 `string`：`[category]::[content-type]`，其中 `category` 可以是：`admin`、`plugin` 或 `api`。

🌐 The `uid` parameter used in function calls for this API is a `string` built with the following format: `[category]::[content-type]` where `category` is one of: `admin`, `plugin` or `api`.

示例：

🌐 Examples:

- 获取 Strapi 管理面板用户的正确 `uid` 是 `admin::user`。
- 上传插件的一个可能的 `uid` 可以是 `plugin::upload.file`。
- 由于用户定义的自定义内容类型的 `uid` 遵循 `api::[content-type]` 语法，如果存在内容类型 `article`，则通过 `api::article.article` 进行引用。

:::tip

在终端中运行 [`strapi content-types:list`](/cms/cli#strapi-content-typeslist) 命令，以显示特定 Strapi 实例的所有可能内容类型的 `uid`。

🌐 Run the [`strapi content-types:list`](/cms/cli#strapi-content-typeslist) command in a terminal to display all possible content-types' `uid`s for a specific Strapi instance.

:::

## findOne()

查找与参数匹配的第一个条目。

🌐 Finds the first entry matching the parameters.

语法：`findOne(uid: string, id: ID, parameters: Params)` ⇒ `Entry`

🌐 Syntax: `findOne(uid: string, id: ID, parameters: Params)` ⇒ `Entry`

### 参数 {#parameters}

🌐 Parameters

| 参数 | 描述 | 类型 |
| --- | --- | --- |
| `fields` | 要返回的属性 | `String[]` |
| `populate` | 要 [填充](/cms/api/entity-service/populate) 的关系、组件和动态区域 | [`PopulateParameter`](/cms/api/entity-service/populate) |
| `locale` | 当启用国际化插件时的语言代码（例如 `fr-FR`）。针对本地化变体而非默认语言。 | `string` |

### 例子 {#example}

🌐 Example

```js
const entry = await strapi.entityService.findOne('api::article.article', 1, {
  fields: ['title', 'description'],
  populate: { category: true },
});
```

## findMany()

查找与参数匹配的条目。

🌐 Finds entries matching the parameters.

语法：`findMany(uid: string, parameters: Params)` ⇒ `Entry[]`

🌐 Syntax: `findMany(uid: string, parameters: Params)` ⇒ `Entry[]`

### 参数 {#parameters-1}

🌐 Parameters

| 参数 | 描述 | 类型 |
| --- | --- | --- |
| `fields` | 要返回的属性 | `String[]` |
| `filters` | 使用的[筛选器](/cms/api/entity-service/filter) | [`FiltersParameters`](/cms/api/entity-service/filter) |
| `start` | 要跳过的条目数量（参见 [分页](/cms/api/entity-service/order-pagination#pagination)） | `Number` |
| `limit` | 要返回的条目数量（参见 [分页](/cms/api/entity-service/order-pagination#pagination)） | `Number` |
| `sort` | [订单](/cms/api/entity-service/order-pagination) 定义 | [`OrderByParameter`](/cms/api/entity-service/order-pagination) |
| `populate` | 关系、组件和动态区域以 [填充](/cms/api/entity-service/populate) | [`PopulateParameter`](/cms/api/entity-service/populate) |
| `publicationState` | 发布状态，可以是：<ul><li>`live` 仅返回已发布条目</li><li>`preview` 返回草稿条目和已发布条目（默认）</li></ul> | `PublicationStateParameter` |
| `locale` | 当启用国际化插件时的语言环境代码。将结果限制为该语言环境（默认语言环境请省略）。 | `string` |

### 例子 {#example-1}

🌐 Example

```js
const entries = await strapi.entityService.findMany('api::article.article', {
  fields: ['title', 'description'],
  filters: { title: 'Hello World' },
  sort: { createdAt: 'DESC' },
  populate: { category: true },
});
```

<br/>

:::tip

要仅检索草稿条目，请结合使用 `preview` 发布状态和 `publishedAt` 字段：

🌐 To retrieve only draft entries, combine the `preview` publication state and the `publishedAt` fields:

```js
const entries = await strapi.entityService.findMany('api::article.article', {
  publicationState: 'preview',
  filters: {
    publishedAt: {
      $null: true,
    },
  },
});

:::

## create()

Creates one entry and returns it

Syntax: `create(uid: string, parameters: Params)` ⇒ `Entry`

### Parameters

| Parameter  | Description | Type |
| ---------- | ----------- | ---------- |
| `fields`   | Attributes to return | `String[]`  |
| `populate` | Relations, components and dynamic zones to [populate](/cms/api/entity-service/populate) | [`PopulateParameter`](/cms/api/entity-service/populate) |
| `locale` | Locale code when the Internationalization plugin is enabled. Creates the entry for that locale. | `string` |
| `data`     | Input data  | `Object` |

:::tip

在 `data` 对象中，可以使用 `connect`、`disconnect` 和 `set` 参数按照 REST API 描述的语法管理关系（参见 [管理关系](/cms/api/rest/relations)）。

🌐 In the `data` object, relations can be managed with the `connect`, `disconnect`, and `set` parameters using the syntax described for the REST API (see [managing relations](/cms/api/rest/relations)).

:::

### Example

```js
const entry = await strapi.entityService.create('api::article.article', {
  data: {
    title: 'My Article',
  },
});

```

## update()

Updates one entry and returns it.

:::note
`update()` only performs a partial update, so existing fields that are not included won't be replaced.
:::

Syntax: `update(uid: string, id: ID, parameters: Params)` ⇒ `Entry`

:::tip

在 `data` 对象中，可以使用 `connect`、`disconnect` 和 `set` 参数按照 REST API 描述的语法管理关系（参见 [管理关系](/cms/api/rest/relations)）。

🌐 In the `data` object, relations can be managed with the `connect`, `disconnect`, and `set` parameters using the syntax described for the REST API (see [managing relations](/cms/api/rest/relations)).

:::

### Parameters

| Parameter  | Description | Type |
| ---------- | ------------- | ---------- |
| `fields`   | Attributes to return | `String[]`  |
| `populate` | Relations, components and dynamic zones to [populate](/cms/api/entity-service/populate) | [`PopulateParameter`](/cms/api/entity-service/populate) |
| `locale` | Locale code when the Internationalization plugin is enabled. Updates the matching localized variant. | `string` |
| `data`     | Input data  | `object`  |

### Example

```js
const entry = await strapi.entityService.update('api::article.article', 1, {
  data: {
    title: 'xxx',
  },
});

```

## delete()

Deletes one entry and returns it.

Syntax: `delete(uid: string, id: ID, parameters: Params)` ⇒ `Entry`

### Parameters

| Parameter  | Description | Type |
| ---------- | --------- | -------- |
| `fields`   | Attributes to return | `String[]`  |
| `populate` | Relations, components and dynamic zones to [populate](/cms/api/entity-service/populate) | [`PopulateParameter`](/cms/api/entity-service/populate) |
| `locale` | Locale code when the Internationalization plugin is enabled. Deletes the localized variant that matches this locale. | `string` |

### Example

```js
const entry = await strapi.entityService.delete('api::article.article', 1);

```