Skip to main content

管理与 API 请求的关系

¥Managing relations with API requests

定义内容类型（在数据库层中指定为实体）之间的关系是将实体相互连接起来。

¥Defining relations between content-types (that are designated as entities in the database layers) is connecting entities with each other.

从关闭 i18n 的 管理面板 到打开 i18n 的 REST API 的关系：

¥Relations between content-types can be managed through the admin panel or through REST API or Document Service API requests.

可以通过 Content API 通过在请求正文中传递参数来连接、断开或设置关系：

¥Relations can be connected, disconnected or set through the Content API by passing parameters in the body of the request:

参数名称描述更新类型
connect连接新实体。

可以与 disconnect 结合使用。

可以与 位置参数 结合使用来定义关系的顺序。		部分的
disconnect断开实体连接。

可以与 connect 结合使用。		部分的
set将实体设置为特定集合。使用 set 将覆盖与其他实体的所有现有连接。

不能与 connect 或 disconnect 结合使用。		满的
✏️ 注意

当在内容类型上启用 国际化（i18n） 时，你还可以传递语言环境来为特定语言环境设置关系，如以下文档服务 API 示例所示：

¥When Internationalization (i18n) is enabled on the content-type, you can also pass a locale to set relations for a specific locale, as in this Document Service API example:

await strapi.documents('api::restaurant.restaurant').update({ 
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
  locale: 'fr',
  data: { 
    category: {
      connect: ['z0y2x4w6v8u1t3s5r7q9onm', 'j9k8l7m6n5o4p3q2r1s0tuv']
    }
  }
})

如果未传递任何语言环境，则将假定使用默认语言环境。

¥If no locale is passed, the default locale will be assumed.

connect​

在请求正文中使用 connect 执行部分更新，连接指定的关系。

¥Using connect in the body of a request performs a partial update, connecting the specified relations.

connect 接受简写或全写语法：

¥connect accepts either a shorthand or a longhand syntax:

语法类型语法示例
shorthandconnect: ['z0y2x4w6v8u1t3s5r7q9onm', 'j9k8l7m6n5o4p3q2r1s0tuv']
longhandconnect: [{ documentId: 'z0y2x4w6v8u1t3s5r7q9onm' }, { documentId: 'j9k8l7m6n5o4p3q2r1s0tuv' }]

你还可以使用 重新排序关系 的普通语法。

¥You can also use the longhand syntax to reorder relations.

connect 可以与 disconnect 结合使用。

¥connect can be used in combination with disconnect.

✋ 提醒

connect 不能用于媒体属性（更多详细信息请参阅 上传插件文档）。

¥connect can not be used for media attributes (see Upload plugin documentation for more details).

发送以下请求会更新由其 documnentId a1b2c3d4e5f6g7h8i9j0klm 标识的 restaurant。请求使用 categories 属性将餐厅与其 documentId 标识的 2 个类别连接起来：

¥Sending the following request updates a restaurant, identified by its documnentId a1b2c3d4e5f6g7h8i9j0klm. The request uses the categories attribute to connect the restaurant with 2 categories identified by their documentId:

关系重新排序​

¥Relations reordering

位置参数可以传递给 connect 的普通语法来定义关系的顺序。

¥Positional arguments can be passed to the longhand syntax of connect to define the order of relations.

普通语法接受对象数组，每个对象包含要连接的条目的 documentId 和一个可选的 position 对象，用于定义连接关系的位置。

¥The longhand syntax accepts an array of objects, each object containing the documentId of the entry to be connected and an optional position object to define where to connect the relation.

✏️ 不同的关系有不同的语法

本文档中描述的语法对于一对多、多对多和多向关系非常有用。
对于一对一、多对一和单向关系，语法 也支持，但仅使用最后一个关系，因此最好使用较短的格式（例如：{ data: { category: 'a1b2c3d4e5f6g7h8i9j0klm' } }，请参阅 REST API 文档）。

¥The syntaxes described in this documentation are useful for one-to-many, many-to-many and many-ways relations.
For one-to-one, many-to-one and one-way relations, the syntaxes are also supported but only the last relation will be used, so it's preferable to use a shorter format (e.g.: { data: { category: 'a1b2c3d4e5f6g7h8i9j0klm' } }, see REST API documentation).

要定义关系的 position，请传递以下 4 个不同位置属性之一：

¥To define the position for a relation, pass one of the following 4 different positional attributes:

参数名称和语法描述类型
before: documentId将关系定位在给定 documentId 之前。documentId(字符串)
after: documentId将关系定位在给定的 documentId 之后。documentId(字符串)
start: true将关系放置在现有关系列表的开头。布尔值
end: true将关系放置在现有关系列表的末尾。布尔值

position 参数是可选的，默认为 position: { end: true }。

¥The position argument is optional and defaults to position: { end: true }.

✏️ 顺序

由于 connect 是一个数组，因此操作顺序很重要，因为它们将按顺序处理（请参见下面的组合示例）。

¥Since connect is an array, the order of operations is important as they will be treated sequentially (see combined example below).

✋ 提醒

同一关系不应连接多次，否则 API 将返回验证错误。

¥The same relation should not be connected more than once, otherwise it would return a Validation error by the API.

考虑数据库中的以下记录：

¥Consider the following record in the database:

categories: [
  { documentId: 'j9k8l7m6n5o4p3q2r1s0tuv' }
  { documentId: 'z0y2x4w6v8u1t3s5r7q9onm' }
]

发送以下请求会更新由其 documentId a1b2c3d4e5f6g7h8i9j0klm 标识的 restaurant，将实体关系与 ma12bc34de56fg78hi90jkl 的 documentId 连接起来以获得 categories 属性，并将其定位在具有 documentId z0y2x4w6v8u1t3s5r7q9onm 的实体之前：

¥Sending the following request updates a restaurant, identified by its documentId a1b2c3d4e5f6g7h8i9j0klm, connecting a relation of entity with a documentId of ma12bc34de56fg78hi90jkl for the categories attribute and positioning it before the entity with documentId z0y2x4w6v8u1t3s5r7q9onm:

Example request to update the position of one relation

PUT http://localhost:1337/api/restaurants/a1b2c3d4e5f6g7h8i9j0klm

{
  data: {
    categories: {
      connect: [
        { documentId: 'ma12bc34de56fg78hi90jkl', position: { before: 'z0y2x4w6v8u1t3s5r7q9onm' } },
      ]
    }
  }
}

边缘情况：草稿和发布或 i18n 已禁用​

¥Edge cases: Draft & Publish or i18n disabled

当 Strapi 5 的一些内置功能针对内容类型（例如 起草并发布 和 国际化 (i18)）禁用时，connect 参数的使用方式可能会有所不同：

¥When some built-in features of Strapi 5 are disabled for a content-type, such as Draft & Publish and Internationalization (i18), the connect parameter might be used differently:

从关闭草稿和发布的 Category 到打开草稿和发布的 Article 的关系：

¥Relation from a Category with i18n off to an Article with i18n on:

在这种情况下，你可以选择要连接到哪个语言环境：

¥In this situation you can select which locale you are connecting to:

data: {
    categories: {
      connect: [
        { documentId: 'z0y2x4w6v8u1t3s5r7q9onm', locale: 'en' },
        // Connect to the same document id but with a different locale 👇
        { documentId: 'z0y2x4w6v8u1t3s5r7q9onm', locale: 'fr' },
      ]
   }
}

根据你的用例阅读一些高级 Category。

¥Relation from a Category with Draft & Publish off to an Article with Draft & Publish on:

data: {
  categories: {
    connect: [
      { documentId: 'z0y2x4w6v8u1t3s5r7q9onm', status: 'draft' },
      // Connect to the same document id but with different publication states 👇
      { documentId: 'z0y2x4w6v8u1t3s5r7q9onm', status: 'published' },
    ]
  }
}

disconnect​

在请求正文中使用 disconnect 执行部分更新，断开指定的关系。

¥Using disconnect in the body of a request performs a partial update, disconnecting the specified relations.

disconnect 接受简写或全写语法：

¥disconnect accepts either a shorthand or a longhand syntax:

语法类型语法示例
shorthanddisconnect: ['z0y2x4w6v8u1t3s5r7q9onm', 'j9k8l7m6n5o4p3q2r1s0tuv']
longhanddisconnect: [{ documentId: 'z0y2x4w6v8u1t3s5r7q9onm' }, { documentId: 'j9k8l7m6n5o4p3q2r1s0tuv' }]

disconnect 可以与 connect 结合使用。

¥disconnect can be used in combination with connect.


发送以下请求会更新由其 documentId a1b2c3d4e5f6g7h8i9j0klm 标识的 restaurant，断开与由其 documentId 标识的 2 个条目的关系：

¥Sending the following request updates a restaurant, identified by its documentId a1b2c3d4e5f6g7h8i9j0klm, disconnecting the relations with 2 entries identified by their documentId:

Example request using the shorthand syntax

PUT http://localhost:1337/api/restaurants/a1b2c3d4e5f6g7h8i9j0klm

{
  data: {
    categories: {
      disconnect: ['z0y2x4w6v8u1t3s5r7q9onm', 'j9k8l7m6n5o4p3q2r1s0tuv'],
    }
  }
}

set​

使用 set 执行完整更新，按照指定的顺序将所有现有关系替换为指定的关系。

¥Using set performs a full update, replacing all existing relations with the ones specified, in the order specified.

set 接受简写或全写语法：

¥set accepts a shorthand or a longhand syntax:

语法类型语法示例
shorthandset: ['z0y2x4w6v8u1t3s5r7q9onm', 'j9k8l7m6n5o4p3q2r1s0tuv']
longhandset: [{ documentId: 'z0y2x4w6v8u1t3s5r7q9onm' }, { documentId: 'j9k8l7m6n5o4p3q2r1s0tuv' }]

由于 set 替换了所有现有关系，因此不应与其他参数结合使用。要执行部分更新，请使用 connect 和 disconnect。

¥As set replaces all existing relations, it should not be used in combination with other parameters. To perform a partial update, use connect and disconnect.

✏️ 省略集合

省略任何参数都相当于使用 set。
例如，以下 3 种语法都是等效的：

¥Omitting any parameter is equivalent to using set.
For instance, the following 3 syntaxes are all equivalent:

  • data: { categories: set: [{ documentId: 'z0y2x4w6v8u1t3s5r7q9onm' }, { documentId: 'j9k8l7m6n5o4p3q2r1s0tuv' }] }}

  • data: { categories: set: ['z0y2x4w6v8u1t3s5r7q9onm2', 'j9k8l7m6n5o4p3q2r1s0tuv'] }}

  • data: { categories: ['z0y2x4w6v8u1t3s5r7q9onm2', 'j9k8l7m6n5o4p3q2r1s0tuv'] }

发送以下请求会更新由其 documentId a1b2c3d4e5f6g7h8i9j0klm 标识的 restaurant，替换所有先前存在的关系并使用 categories 属性连接由其 documentId 标识的 2 个类别：

¥Sending the following request updates a restaurant, identified by its documentId a1b2c3d4e5f6g7h8i9j0klm, replacing all previously existing relations and using the categories attribute to connect 2 categories identified by their documentId:

Example request using the shorthand syntax with set

PUT http://localhost:1337/api/restaurants/a1b2c3d4e5f6g7h8i9j0klm

{
  data: {
    categories: {
      set: ['z0y2x4w6v8u1t3s5r7q9onm', 'j9k8l7m6n5o4p3q2r1s0tuv4'],
    }
  }
}