メインコンテンツまでスキップ

API リクエストでのリレーション管理

コンテンツタイプ間のリレーション（データベース層ではエンティティ同士の接続）は、エンティティを相互に結びつけることです。

リレーションは 管理画面、REST API、Document Service API のリクエストで管理できます。

Content API では、リクエストボディにパラメータを渡してリレーションを接続・切断・設定できます。このペイロードは単一エントリのリレーションとマルチリレーション（one-to-many、many-to-one、many-to-many、many-way）の両方で使えます。複数リンクを許すリレーションフィールドでは、API はリレーション ID の配列を想定し、レスポンスでも配列を返します。

パラメータ名説明更新の種類
connect新しいエンティティを接続します。

disconnect と併用できます。

位置指定引数と組み合わせて、リレーションの順序を定義できます。		部分
disconnectエンティティの接続を切ります。

connect と併用できます。		部分
set指定した集合に置き換えます。set を使うと、他エンティティへの既存の接続はすべて上書きされます。

connect や disconnect とは併用できません。		全体
Note

マルチリレーションは REST API と GraphQL API の両方で管理できます。connect、disconnect、set はどちらの API でも利用できます。一方、Document Service API はリレーション操作を扱いません。

Note

コンテンツタイプで Internationalization (i18n) が有効な場合、特定ロケール向けにリレーションを設定するためにロケールを渡せます。次は Document Service API の例です。

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

ロケールを省略すると既定ロケールが使われます。

connect​

リクエストボディで connect を使うと部分更新として、指定したリレーションを接続します。

connect には省略形と詳細形があります。

構文の種類構文の例
省略形connect: ['z0y2x4w6v8u1t3s5r7q9onm', 'j9k8l7m6n5o4p3q2r1s0tuv']
詳細形connect: [{ documentId: 'z0y2x4w6v8u1t3s5r7q9onm' }, { documentId: 'j9k8l7m6n5o4p3q2r1s0tuv' }]

詳細形では リレーションの並べ替え も指定できます。

connect は disconnect と併用できます。

Caution

メディア属性への connect は公式にはサポートされていません。上級者向けにアップロードファイルの ID を指定して接続する方法はありますが、Strapi が推奨・保証するものではなく、下書きと公開で ID が食い違うなど簡単に壊れます。利用は自己責任で慎重に行ってください。

次のリクエストは、documentId が a1b2c3d4e5f6g7h8i9j0klm の restaurant を更新します。categories 属性で、それぞれ documentId で示した 2 件のカテゴリに接続します。

Example REST request

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

{
  data: {
    categories: {
      connect: ['z0y2x4w6v8u1t3s5r7q9onm', 'j9k8l7m6n5o4p3q2r1s0tuv']
    }
  }
}
Example Node request
const fetch = require('node-fetch');

const response = await fetch(
  'http://localhost:1337/api/restaurants/a1b2c3d4e5f6g7h8i9j0klm',
  {
    method: 'put',
    body: {
      data: {
        categories: {
          connect: ['z0y2x4w6v8u1t3s5r7q9onm', 'j9k8l7m6n5o4p3q2r1s0tuv']
        }
      }
    }
  }
);

リレーションの並べ替え​

4.6.0This feature requires Strapi version 4.6.0 or later.

connect の詳細形では、位置引数を渡してリレーションの順序を定義できます。

詳細形はオブジェクトの配列で、各オブジェクトに接続するエントリの documentId と、任意の position（接続位置）を含めます。

リレーションの種類ごとの構文

このドキュメントの構文は one-to-many、many-to-many、many-way に特に有用です。
one-to-one、many-to-one、one-way でも同様の構文は使えますが、最後のリレーションだけが使われるため、短い形式（例: { data: { category: 'a1b2c3d4e5f6g7h8i9j0klm' } }）を使う方がよいです（REST API のドキュメント 参照）。

position には次の 4 種類のいずれかを渡します。

パラメータ名と構文説明型
before: documentId指定した documentId の前に並べます。documentId（文字列）
after: documentId指定した documentId の後に並べます。documentId（文字列）
start: true既存のリレーション一覧の先頭に並べます。Boolean
end: true既存のリレーション一覧の末尾に並べます。Boolean

position は省略可能で、省略時は position: { end: true } と同じです。

順番の意味

connect は配列のため、記述した順に処理されます（下の組み合わせ例を参照）。

Caution

同じリレーションを複数回接続しないでください。API がバリデーションエラーを返します。

データベースに次のレコードがあるとします。

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

次のリクエストは、documentId が a1b2c3d4e5f6g7h8i9j0klm の restaurant を更新し、categories に documentId が ma12bc34de56fg78hi90jkl のリレーションを追加し、documentId z0y2x4w6v8u1t3s5r7q9onm のエンティティの前に置きます。

1 件のリレーションの位置を更新するリクエスト例

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

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

エッジケース: 下書きと公開または i18n が無効な場合​

コンテンツタイプで 下書きと公開 や Internationalization (i18n) がオフになっていると、connect の使い方が次のように変わることがあります。

i18n がオフの Category から、i18n がオンの Article へのリレーション:

接続先のロケールを次のように指定できます。

data: {
    categories: {
      connect: [
        { documentId: 'z0y2x4w6v8u1t3s5r7q9onm', locale: 'en' },
        // 同じ documentId で別ロケールに接続 👇
        { documentId: 'z0y2x4w6v8u1t3s5r7q9onm', locale: 'fr' },
      ]
   }
}

下書きと公開がオフの Category から、オンのアーティクルへのリレーション:

data: {
  categories: {
    connect: [
      { documentId: 'z0y2x4w6v8u1t3s5r7q9onm', status: 'draft' },
      // 同じ documentId で別の公開状態に接続 👇
      { documentId: 'z0y2x4w6v8u1t3s5r7q9onm', status: 'published' },
    ]
  }
}

disconnect​

リクエストボディで disconnect を使うと部分更新として、指定したリレーションの接続を切ります。

disconnect にも省略形と詳細形があります。

構文の種類構文の例
省略形disconnect: ['z0y2x4w6v8u1t3s5r7q9onm', 'j9k8l7m6n5o4p3q2r1s0tuv']
詳細形disconnect: [{ documentId: 'z0y2x4w6v8u1t3s5r7q9onm' }, { documentId: 'j9k8l7m6n5o4p3q2r1s0tuv' }]

disconnect は connect と併用できます。


次のリクエストは、documentId が a1b2c3d4e5f6g7h8i9j0klm の restaurant を更新し、documentId で指定した 2 件のエントリとの接続を切ります。

省略形を使ったリクエスト例

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

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

set​

set は全体更新で、既存のリレーションをすべて、指定した順序の集合に置き換えます。

set には省略形と詳細形があります。

構文の種類構文の例
省略形set: ['z0y2x4w6v8u1t3s5r7q9onm', 'j9k8l7m6n5o4p3q2r1s0tuv']
詳細形set: [{ documentId: 'z0y2x4w6v8u1t3s5r7q9onm' }, { documentId: 'j9k8l7m6n5o4p3q2r1s0tuv' }]

set は既存をすべて置き換えるため、他パラメータと併用しないでください。部分更新には connect と disconnect を使います。

Note
set を省略する場合

パラメータを省略するのは set を使うのと同じです。
例えば次の 3 つはいずれも同じ意味です。

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

次のリクエストは、documentId が a1b2c3d4e5f6g7h8i9j0klm の restaurant を更新し、以前のリレーションをすべて置き換えて、categories で documentId により指定した 2 件のカテゴリだけを接続します。

set と省略形のリクエスト例

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

{
  data: {
    categories: {
      set: ['z0y2x4w6v8u1t3s5r7q9onm', 'j9k8l7m6n5o4p3q2r1s0tuv4'],
    }
  }
}
このページを編集