通过 REST API 管理关系
¥Managing relations through the REST API
定义内容类型(在数据库层中指定为实体)之间的关系是将实体相互连接起来。
¥Defining relations between content-types (that are designated as entities in the database layers) is connecting entities with each other.
内容类型之间的关系可以通过发送到内容 API 的 管理面板 或 REST 请求进行管理。
¥Relations between content-types can be managed through the admin panel or through REST requests sent to the Content API.
可以通过 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 结合使用。 | 满的 |
connect
在请求正文中使用 connect
执行部分更新,连接指定的关系。
¥Using connect
in the body of a request performs a partial update, connecting the specified relations.
connect
接受简写或普通语法。在以下示例中,数字指实体 ID:
¥connect
accepts either a shorthand or a longhand syntax. In the following examples, numbers refers to entity ids:
语法类型 | 语法示例 |
---|---|
shorthand | connect: [2, 4] |
longhand | connect: [{ id: 2 }, { id: 4 }] |
你还可以使用 重新排序关系 的普通语法。
¥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).
- Shorthand syntax example
- Longhand syntax example
发送以下请求将 restaurant
实体更新为 id
1
,并使用 categories
属性将该实体与具有 id
2
和 4
的实体连接起来:
¥Sending the following request updates the restaurant
entity with id
1
, using the categories
attribute to connect the entity with entities with id
2
and 4
:
PUT
http://localhost:1337/api/restaurants/1
{
data: {
categories: {
connect: [2, 4]
}
}
}
const fetch = require('node-fetch');
const response = await fetch(
'http://localhost:1337/api/restaurants/1',
{
method: 'put',
body: {
data: {
categories: {
connect: [2, 4]
}
}
}
}
);
发送以下请求将 restaurant
实体更新为 id
1
,并使用 categories
属性将该实体与具有 id
2
和 4
的实体连接起来:
¥Sending the following request updates the restaurant
entity with id
1
, using the categories
attribute to connect the entity with entities with id
2
and 4
:
PUT
http://localhost:1337/api/restaurants/1
{
data: {
categories: {
connect: [
{ id: 2 },
{ id: 4 }
]
}
}
}
const fetch = require('node-fetch');
const response = await fetch(
'http://localhost:1337/api/restaurants/1',
{
method: 'put',
body: {
data: {
categories: {
connect: [
{ id: 2 },
{ id: 4 }
]
}
}
}
}
);
关系重新排序
¥Relations reordering
位置参数可以传递给 connect
的普通语法来定义关系的顺序。
¥Positional arguments can be passed to the longhand syntax of connect
to define the order of relations.
普通语法接受对象数组,每个对象包含要连接的条目的 id
和一个可选的 position
对象,用于定义连接关系的位置。
¥The longhand syntax accepts an array of objects, each object containing the id
of the entry to be connected and an optional position
object to define where to connect the relation.
本文档中描述的语法对于一对多、多对多和多向关系非常有用。
对于一对一、多对一和单向关系,语法 也支持,但仅使用最后一个关系,因此最好使用较短的格式(例如:{ data: { category: 2 } }
,请参阅 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: 2 } }
, see REST API documentation).
要定义关系的 position
,请传递以下 4 个不同位置属性之一:
¥To define the position
for a relation, pass one of the following 4 different positional attributes:
参数名称和语法 | 描述 | 类型 |
---|---|---|
before: id | 将关系定位在给定 id 之前。 | 条目 id |
after: id | 将关系定位在给定的 id 之后。 | 条目 id |
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.
- Basic example
- Combined example
考虑数据库中的以下记录:
¥Consider the following record in the database:
categories: [
{ id: 1 }
{ id: 2 }
]
发送以下请求将 restaurant
实体更新为 id
1
,将实体与 id
3
的关系连接到 categories
属性,并将其定位在具有 id
2
的实体之前:
¥Sending the following request updates the restaurant
entity with id
1
, connecting a relation of entity with id
3
for the categories
attribute and positioning it before the entity with id
2
:
PUT http://localhost:1337/api/restaurants/1
{
data: {
categories: {
connect: [
{ id: 3, position: { before: 2 } },
]
}
}
}
考虑数据库中的以下记录:
¥Consider the following record in the database:
categories: [
{ id: 1 }
{ id: 2 }
]
在 PUT 请求的请求正文中发送以下示例会更新多个关系:
¥Sending the following example in the request body of a PUT request updates multiple relations:
PUT http://localhost:1337/api/restaurants/1
{
data: {
categories: {
connect: [
{ id: 6, position: { after: 1} },
{ id: 7, position: { before: 2 } },
{ id: 8, position: { end: true } },
{ id: 9 },
{ id: 10, position: { start: true } },
]
}
}
}
省略 position
参数(如 id: 9
)默认为 position: { end: true }
。所有其他关系都相对于另一个现有的 id
(使用 after
或 before
)或相对于关系列表(使用 start
或 end
)定位。操作按照 connect
数组中定义的顺序依次处理,因此生成的数据库记录将如下所示:
¥Omitting the position
argument (as in id: 9
) defaults to position: { end: true }
. All other relations are positioned relative to another existing id
(using after
or before
) or relative to the list of relations (using start
or end
). Operations are treated sequentially in the order defined in the connect
array, so the resulting database record will be the following:
categories: [
{ id: 10 },
{ id: 1 },
{ id: 6 },
{ id: 7 },
{ id: 2 },
{ id: 8 },
{ id: 9 }
]
disconnect
在请求正文中使用 disconnect
执行部分更新,断开指定的关系。
¥Using disconnect
in the body of a request performs a partial update, disconnecting the specified relations.
disconnect
接受简写或普通语法。在以下示例中,数字指实体 ID:
¥disconnect
accepts either a shorthand or a longhand syntax. In the following examples, numbers refers to entity ids:
语法类型 | 语法示例 |
---|---|
shorthand | disconnect: [2, 4] |
longhand | disconnect: [{ id: 2 }, { id: 4 }] |
disconnect
可以与 connect
结合使用。
¥disconnect
can be used in combination with connect
.
- Shorthand syntax example
- Longhand syntax example
发送以下请求将 restaurant
实体更新为 id
1
,断开与 id
2
和 4
实体的关系:
¥Sending the following request updates the restaurant
entity with id
1
, disconnecting the relations with entities with id
2
and 4
:
PUT http://localhost:1337/api/restaurants/1
{
data: {
categories: {
disconnect: [2, 4],
}
}
}
发送以下请求将 restaurant
实体更新为 id
1
,断开与 id
2
和 4
实体的关系:
¥Sending the following request updates the restaurant
entity with id
1
, disconnecting the relations with entities with id
2
and 4
:
PUT http://localhost:1337/api/restaurants/1
{
data: {
categories: {
disconnect: [
{ id: 2 },
{ id: 4 }
],
}
}
}
set
使用 set
执行完整更新,按照指定的顺序将所有现有关系替换为指定的关系。
¥Using set
performs a full update, replacing all existing relations with the ones specified, in the order specified.
set
接受简写或普通语法。在以下示例中,数字指实体 ID:
¥set
accepts a shorthand or a longhand syntax. In the following examples, numbers refers to entity ids:
语法类型 | 语法示例 |
---|---|
shorthand | set: [2, 4] |
longhand | set: [{ id: 2 }, { id: 4 }] |
由于 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: [{ id: 2 }, { id: 4 }] }}
data: { categories: { set: [2, 4] }}
data: { categories: [2, 4] }
(如 REST API 文档 中所用)¥
data: { categories: [2, 4] }
(as used in the REST API documentation)
- Shorthand syntax example
- Longhand syntax example
发送以下请求将 restaurant
实体更新为 id
1
,替换所有先前存在的关系,并使用 categories
属性将该实体与具有 id
2
和 4
的实体连接起来:
¥Sending the following request updates the restaurant
entity with id
1
, replacing all previously existing relations and using the categories
attribute to connect the entity with entities with id
2
and 4
:
PUT http://localhost:1337/api/restaurants/1
{
data: {
categories: {
set: [2, 4],
}
}
}
发送以下请求将 restaurant
实体更新为 id
1
,替换所有先前存在的关系,并使用 categories
属性将该实体与具有 id
2
和 4
的实体连接起来:
¥Sending the following request updates the restaurant
entity with id
1
, replacing all previously existing relations and using the categories
attribute to connect the entity with entities with id
2
and 4
:
PUT http://localhost:1337/api/restaurants/1
{
data: {
categories: {
set: [
{ id: 2 },
{ id: 4 }
],
}
}
}