关系 Relations

使用 REST API 管理关系的顺序

通过 REST API 管理关系

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

可以通过 管理面板 或通过发送到 Content API 的 REST 请求来管理内容类型之间的关系。

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

参数名称说明更新类型
connect连接新实体。

可以与 disconnect 结合使用。

可以与 位置参数 一起使用，以定义关系的顺序。		部分
disconnect断开实体。

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

不能与 connect 或 disconnect 结合使用。		完整

connect

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

connect 接受简写或全写语法。在以下示例中，数字表示实体 ID：

语法类型语法示例
简写connect: [2, 4]
全写connect: [{ id: 2 }, { id: 4 }]

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

connect 可以与 disconnect 结合使用。

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

简写语法示例

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:

使用简写语法的示例请求 REST

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

json
{
  "data": {
    "categories": {
      "connect": [2, 4]
    }
  }
}
Node
js
const fetch = require('node-fetch')

const response = await fetch(
  'http://localhost:1337/api/restaurants/1',
  {
    method: 'put',
    body: {
      data: {
        categories: {
          connect: [2, 4]
        }
      }
    }
  }
)

普通语法示例

发送以下请求会更新“id”为“1”的“restaurant”实体，并使用“categories”属性将该实体与“id”为“2”和“4”的实体连接起来：

使用普通语法的示例请求

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

json
{
  "data": {
    "categories": {
      "connect": [
        { "id": 2 },
        { "id": 4 }
      ]
    }
  }
}
Node
js
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 }
          ]
        }
      }
    }
  }
)

关系重新排序

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

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

不同关系的不同语法

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

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

参数名称和语法说明类型
before: id将关系定位在给定 id 之前。条目 id
after: id将关系定位在给定 id 之后。条目 id
start: true将关系定位在现有关系列表的开头。布尔值
end: true将关系定位在现有关系列表的末尾。布尔值

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

顺序

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

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

基本示例

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

json
{
  "categories": [
    { "id": 1 },
    { "id": 2 }
  ]
}

发送以下请求将更新“id”为“1”的“restaurant”实体，将“categories”属性的“id”为“3”的实体关系连接起来，并将其定位在“id”为“2”的实体之前：

更新一个关系位置的示例请求
bash
PUT http://localhost:1337/api/restaurants/1
json
{
  "data": {
    "categories": {
      "connect": [
        { "id": 3, "position": { "before": 2 } }
      ]
    }
  }
}

组合示例

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

json
{
  "categories": [
    { "id": 1 },
    { "id": 2 }
  ]
}

在 PUT 请求的请求正文中发送以下示例可更新多个关系：

重新排序多个关系的示例请求
bash
PUT http://localhost:1337/api/restaurants/1
json
{
  "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 数组中定义的顺序依次处理，因此生成的数据库记录将如下所示：

json
{
  "categories": [
    { "id": 10 },
    { "id": 1 },
    { "id": 6 },
    { "id": 7 },
    { "id": 2 },
    { "id": 8 },
    { "id": 9 }
  ]
}

disconnect

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

disconnect 接受简写或全写语法。在以下示例中，数字表示实体 ID：

语法类型语法示例
简写disconnect: [2, 4]
全写disconnect: [{ id: 2 }, { id: 4 }]

disconnect 可与 connect 结合使用。

简写语法示例

Sending the following request updates the restaurant entity with id 1, disconnecting the relations with entities with id 2 and 4:

使用简写语法的示例请求
bash
PUT http://localhost:1337/api/restaurants/1
json
{
  "data": {
    "categories": {
      "disconnect": [2, 4]
    }
  }
}

普通语法示例

发送以下请求将更新 id 为 1 的餐厅实体，断开与 id 为 2 和 4 的实体的关系：

使用普通语法的示例请求
bash
PUT http://localhost:1337/api/restaurants/1
json
{
  "data": {
    "categories": {
      "disconnect": [
        { "id": 2 },
        { "id": 4 }
      ]
    }
  }
}

set

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

set 接受简写或全写语法。在以下示例中，数字指的是实体 ID：

语法类型语法示例
简写set: [2, 4]
全写set: [{ id: 2 }, { id: 4 }]

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

省略 set

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

  • data: { categories: { set: [{ id: 2 }, { id: 4 }] }}
  • data: { categories: { set: [2, 4] }}
  • data: { categories: [2, 4] } (就像在 REST API 文档中一样)

简写语法示例

发送以下请求将更新 id 为 1 的 restaurant 实体，替换所有先前存在的关系，并使用 categories 属性将该实体与 id 为 2 和 4 的实体连接起来：

使用简写语法的示例请求 with set
bash
PUT http://localhost:1337/api/restaurants/1
json
{
  "data": {
    "categories": {
      "set": [2, 4]
    }
  }
}

普通语法示例

发送以下请求将更新 id 为 1 的 restaurant 实体，替换所有先前存在的关系，并使用 categories 属性将该实体与 id 为 2 和 4 的实体连接起来：

使用普通语法的示例请求 with set
bash
PUT http://localhost:1337/api/restaurants/1
json
{
  "data": {
    "categories": {
      "set": [
        { "id": 2 },
        { "id": 4 }
      ]
    }
  }
}