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

Document Service API

Document Service API は Query Engine API の上に構築されています。 ドキュメント に対して CRUD（作成、取得、更新、削除）を行います。

Document Service API はドキュメントの 件数カウント にも対応し、コンテンツタイプで 下書きと公開 が有効な場合は、公開、公開取り下げ、下書きの破棄 など Strapi 固有の操作も行えます。

Strapi 5 では、API レベルでドキュメントは documentId で一意に識別されます。

documentId の説明: Strapi v4 の id に代わる識別子

以前の Strapi では、Content API とデータベース行の両方で使われる id の概念が常に安定しているとは限りませんでした。1 エントリに複数バージョンやローカライズがあり、複製やインポート／エクスポートなどで数値の id が変わる場合がありました。

この制限に対処するため、Strapi 5 では 24 文字の英数字 documentId を導入し、物理レコードから独立した、コンテンツエントリの一意で永続的な識別子としました。

Strapi 5 内部では、リレーション、公開、ローカライズ、バージョン履歴の管理にこの識別子を使います。エントリのありうるバリエーションはすべて単一の ドキュメント 概念にまとまります。

そのため Strapi 5 以降、多くの API とサービスは操作の一貫性のために id より documentId を前提にします。移行のため両方を返す API もありますが、コンテンツのクエリには documentId を使うことを強く推奨します。将来のバージョンでは documentId だけが使われる可能性があります。

id から documentId への移行の詳細は 破壊的変更のページ と Entity Service から Document Service API への移行ガイド を参照してください。

Strapi 5 では Entity Service API は非推奨です

Document Service API は Strapi v4 で使われていた Entity Service API に代わります（Strapi v4 のドキュメント）。

Entity Service API からの移行手順は 移行リファレンス を参照してください。

Note

リレーションの接続・切断・設定は REST API と同様に Document Service API でも行えます（例は REST API のリレーション を参照）。

設定​

documents.strictParams は、findMany や findOne など Document Service メソッドに渡すパラメータを厳密に検証するオプションです。API 設定 ファイル（./config/api.js または ./config/api.ts）で設定します。documents.strictParams の詳細は API 設定 の表を参照してください。

ドキュメントオブジェクト​

Document の各メソッドは、安定した documentId のもとにまとめられたコンテンツエントリのあるバージョンを表す、ドキュメントオブジェクトまたはその配列を返します。返却オブジェクトに通常含まれるものは次のとおりです。

  • documentId: ロケールや下書き／公開をまたいでエントリを指し続ける永続的な識別子。
  • id: 特定のロケール／バージョンのレコードに対応するデータベース上の識別子。
  • モデルフィールド: コンテンツタイプスキーマで定義されたすべてのフィールド。リレーション、コンポーネント、ダイナミックゾーンは、populate で明示しない限りポピュレートされません（フィールドのポピュレート）。fields で返すフィールドを絞れます（フィールドの選択）。
  • メタデータ: 利用可能な場合は publishedAt、createdAt、updatedAt、createdBy / updatedBy。

コンテンツタイプで 下書きと公開 と Internationalization が有効なら、ドキュメントオブジェクトに status や locale が含まれることもあります。

メソッド一覧​

以下ではメソッドごとにパラメータと例を説明します。

メソッド用途
findOne()documentId でドキュメントを取得。ロケールや status で絞り込み可能。
findFirst()フィルターに一致する最初の 1 件を返す。
findMany()フィルター・ソート・ページネーション付きで一覧を返す。
create()ドキュメントを作成。ロケールを指定可能。
update()documentId でドキュメントを更新。
delete()ドキュメントまたは特定ロケール版を削除。
publish()ドキュメントの下書きを公開する。
unpublish()公開済みドキュメントを下書きに戻す。
discardDraft()下書きデータを捨て、公開版だけを残す。
count()条件に一致するドキュメント数を数える。

findOne()​

渡した documentId とパラメータに一致するドキュメントを取得します。

構文: findOne(parameters: Params) => Document

パラメータ​

パラメータ説明既定値型
documentIdドキュメント IDID
locale取得するドキュメントのロケール。既定ロケール文字列または undefined
statusコンテンツタイプで 下書きと公開 が有効な場合: 公開状態。次のいずれか。
  • 'published' — 公開版のみ
  • 'draft' — 下書きのみ
'draft''published' または 'draft'
fields返すフィールドを選択すべてのフィールド
（既定でポピュレートされないものを除く）		Object
populate追加フィールドを ポピュレート する。nullObject

例​

documentId だけを渡し他にパラメータがない場合、findOne() は既定ロケールの下書き版を返します。

documentId を指定してドキュメントを取得
await strapi.documents('api::restaurant.restaurant').findOne({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm'
})
Example response
{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  name: "Biscotte Restaurant",
  publishedAt: null, // draft version (default)
  locale: "en", // default locale
  // …
}

findOne() は一致するドキュメントがあればそれを返し、なければ null を返します。

findFirst()​

パラメータに一致する最初のドキュメントを取得します。

構文: findFirst(parameters: Params) => Document

パラメータ​

パラメータ説明既定値型
locale検索対象ドキュメントのロケール。既定ロケール文字列または undefined
statusコンテンツタイプで 下書きと公開 が有効な場合: 公開状態。次のいずれか。
  • 'published' — 公開版のみ
  • 'draft' — 下書きのみ
'draft''published' または 'draft'
filters使う フィルターnullObject
fields返すフィールドを選択すべてのフィールド
（既定でポピュレートされないものを除く）		Object
populate追加フィールドを ポピュレート する。nullObject

例​


基本的な例​

既定では、findFirst() は渡した一意識別子（コレクション型の id またはシングル型の id）に対応する最初のドキュメントの、既定ロケールの下書き版を返します。

最初のドキュメントを取得
await strapi.documents('api::restaurant.restaurant').findFirst()
Example response
{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  name: "Restaurant Biscotte",
  publishedAt: null,
  locale: "en"
  // …
}
パラメータで最初の 1 件を取得​

findFirst() にパラメータを渡すと、条件に一致する最初のドキュメントを返します。

locale や status を省略すると、既定ロケールの下書き版が返ります。

定義したフィルターに一致する最初のドキュメントを取得
await strapi.documents('api::restaurant.restaurant').findFirst(
  {
    filters: {
      name: {
        $startsWith: "Pizzeria"
      }
    }
  }
)
Example response
{
  documentId: "j9k8l7m6n5o4p3q2r1s0tuv",
  name: "Pizzeria Arrivederci",
  publishedAt: null,
  locale: "en"
  // …
}

findMany()​

パラメータに一致するドキュメントを取得します。

構文: findMany(parameters: Params) => Document[]

パラメータ​

パラメータ説明既定値型
locale検索対象ドキュメントのロケール。既定ロケール文字列または undefined
statusコンテンツタイプで 下書きと公開 が有効な場合: 公開状態。次のいずれか。
  • 'published' — 公開版のみ
  • 'draft' — 下書きのみ
'draft''published' または 'draft'
filters使う フィルターnullObject
fields返すフィールドを選択すべてのフィールド
（既定でポピュレートされないものを除く）		Object
populate追加フィールドを ポピュレート する。nullObject
pagination結果を ページネーション する
sort結果を ソート する

例​


基本的な例​

パラメータを省略すると、findMany() は各ドキュメントについて既定ロケールの下書き版を返します。

パラメータなしでドキュメント一覧を取得
await strapi.documents('api::restaurant.restaurant').findMany()
Example response
[
  {
    documentId: "a1b2c3d4e5f6g7h8i9j0klm",
    name: "Biscotte Restaurant",
    publishedAt: null, // draft version (default)
    locale: "en" // default locale
    // …
  },
  {
    documentId: "j9k8l7m6n5o4p3q2r1s0tuv",
    name: "Pizzeria Arrivederci",
    publishedAt: null,
    locale: "en"
    // …
  },
]
パラメータで一覧を取得​

利用できるフィルターは Document Service API リファレンスの filters を参照してください。

locale や status を省略すると、既定ロケールの下書き版が返ります。

条件に一致するドキュメントを取得
await strapi.documents('api::restaurant.restaurant').findMany(
  {
    filters: {  
      name: {
        $startsWith: 'Pizzeria'
      }
    }
  }
)
Example response
[
  {
    documentId: "j9k8l7m6n5o4p3q2r1s0tuv",
    name: "Pizzeria Arrivederci",
    locale: "en", // default locale
    publishedAt: null, // draft version (default)
    // …
  }, 
  // …
]

create()​

下書きのドキュメントを作成して返します。

作成するコンテンツのフィールドは data オブジェクトで渡します。

構文: create(parameters: Params) => Document

パラメータ​

パラメータ説明既定値型
locale作成するドキュメントのロケール。既定ロケール文字列または undefined
fields返すフィールドを選択すべてのフィールド
（既定でポピュレートされないものを除く）		Object
statusコンテンツタイプで 下書きと公開 が有効な場合: 'published' にすると、作成と同時に下書きを自動公開できる-'published'
populate追加フィールドを ポピュレート する。nullObject

例​

locale を省略すると、create() は既定ロケール向けの下書き版を作成します。

新しい「Restaurant B」ドキュメントを作成
await strapi.documents('api::restaurant.restaurant').create({
  data: {
    name: 'Restaurant B'
  }
})
Example response
{
  documentId: "ln1gkzs6ojl9d707xn6v86mw",
  name: "Restaurant B",
  publishedAt: null,
  locale: "en",
}
Tip

コンテンツタイプで 下書きと公開 が有効なら、作成と同時にドキュメントを公開できます（status の説明 を参照）。

update()​

ドキュメントのバージョンを更新して返します。

構文: update(parameters: Params) => Promise<Document>

パラメータ​

パラメータ説明既定値型
documentIdドキュメント IDID
locale更新するドキュメントのロケール。既定ロケール文字列または null
filters使う フィルターnullObject
fields返すフィールドを選択すべてのフィールド
（既定でポピュレートされないものを除く）		Object
statusコンテンツタイプで 下書きと公開 が有効な場合: 'published' にすると、更新と同時に下書きを自動公開できる-'published'
populate追加フィールドを ポピュレート する。nullObject
Tip

公開版は読み取り専用のため、公開版そのものを直接更新することはできません。 内容を更新してすぐ公開するには、次のいずれかを使います。

  • 下書きを update() で更新し、続けて publish() で 公開する。
  • update() に渡すパラメータに status: 'published' を含める（status の説明 を参照）。
Caution

繰り返し可能なコンポーネントの更新に Document Service API を使うことは推奨されません（詳しくは関連する 破壊的変更の項目 を参照）。

例​

locale を省略すると、update() は既定ロケールのドキュメントを更新します。

Example request
await strapi.documents('api::restaurant.restaurant').update({ 
    documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
    data: { name: "New restaurant name" }
})
Example response
{
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
  name: "New restaurant name",
  locale: "en",
  publishedAt: null, // draft
  // …
}

delete()​

1 件のドキュメント、またはその特定ロケール版を削除します。

構文: delete(parameters: Params): Promise<{ documentId: ID, entries: Number }>

パラメータ​

パラメータ説明既定値型
documentIdドキュメント IDID
locale削除するドキュメントのロケール版。null
（既定ロケールのみ削除）		文字列、'*'、または null
filters使う フィルターnullObject
fields返すフィールドを選択すべてのフィールド
（既定でポピュレートされないものを除く）		Object
populate追加フィールドを ポピュレート する。nullObject

例​

locale を省略すると、delete() はドキュメントの既定ロケール版だけを削除します。下書きと公開版の両方が削除されます。

Example request
await strapi.documents('api::restaurant.restaurant').delete({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm', // documentId,
})
Example response
{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  entries: [
    {
      "documentId": "a1b2c3d4e5f6g7h8i9j0klm",
      "name": "Biscotte Restaurant",
      "publishedAt": "2024-03-14T18:30:48.870Z",
      "locale": "en"
      // …
    }
  ]
}

publish()​

ドキュメントの 1 つまたは複数のロケールを公開します。

コンテンツタイプで 下書きと公開 が有効なときだけ使えます。

構文: publish(parameters: Params): Promise<{ documentId: ID, entries: Number }>

パラメータ​

パラメータ説明既定値型
documentIdドキュメント IDID
locale公開するドキュメントのロケール。既定ロケールのみ文字列、'*', または null
filters使う フィルターnullObject
fields返すフィールドを選択すべてのフィールド
（既定でポピュレートされないものを除く）		Object
populate追加フィールドを ポピュレート する。nullObject

例​

locale を省略すると、publish() はドキュメントの既定ロケール版だけを公開します。

Example request
await strapi.documents('api::restaurant.restaurant').publish({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
});
Example response
{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  entries: [
    {
      "documentId": "a1b2c3d4e5f6g7h8i9j0klm",
      "name": "Biscotte Restaurant",
      "publishedAt": "2024-03-14T18:30:48.870Z",
      "locale": "en"
      // …
    }
  ]
}

unpublish()​

ドキュメントの 1 つまたはすべてのロケール版の公開を取り下げ、取り下げたロケール版の件数を返します。

コンテンツタイプで 下書きと公開 が有効なときだけ使えます。

構文: unpublish(parameters: Params): Promise<{ documentId: ID, entries: Number }>

パラメータ​

パラメータ説明既定値型
documentIdドキュメント IDID
locale公開を取り下げるロケール。既定ロケールのみ文字列、'*', または null
filters使う フィルターnullObject
fields返すフィールドを選択すべてのフィールド
（既定でポピュレートされないものを除く）		Object
populate追加フィールドを ポピュレート する。nullObject

例​

locale を省略すると、unpublish() はドキュメントの既定ロケール版の公開だけを取り下げます。

Example request
await strapi.documents('api::restaurant.restaurant').unpublish({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm' 
});
Example response
{
  documentId: "lviw819d5htwvga8s3kovdij",
  entries: [
    {
      documentId: "lviw819d5htwvga8s3kovdij",
      name: "Biscotte Restaurant",
      publishedAt: null,
      locale: "en"
      // …
    }
  ]
}

discardDraft()​

下書きデータを破棄し、公開版の内容で上書きします。

コンテンツタイプで 下書きと公開 が有効なときだけ使えます。

構文: discardDraft(parameters: Params): Promise<{ documentId: ID, entries: Number }>

パラメータ​

パラメータ説明既定値型
documentIdドキュメント IDID
locale下書きを破棄するロケール。既定ロケールのみ。文字列、'*', または null
filters使う フィルターnullObject
fields返すフィールドを選択すべてのフィールド
（既定でポピュレートされないものを除く）		Object
populate追加フィールドを ポピュレート する。nullObject

例​

locale を省略すると、discardDraft() は既定ロケールについてだけ下書きを破棄し、公開版で上書きします。

ドキュメントの既定ロケールの下書きを破棄
await strapi.documents('api::restaurant.restaurant').discardDraft({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm', 
});
Example response
{
  documentId: "lviw819d5htwvga8s3kovdij",
  entries: [
    {
      documentId: "lviw819d5htwvga8s3kovdij",
      name: "Biscotte Restaurant",
      publishedAt: null,
      locale: "en"
      // …
    }
  ]
}

count()​

渡したパラメータに一致するドキュメント数を数えます。

構文: count(parameters: Params) => number

パラメータ​

パラメータ説明既定値型
locale数える対象のロケール既定ロケール文字列または null
statusコンテンツタイプで 下書きと公開 が有効な場合: 公開状態。次のいずれか。
  • 'published' — 公開版のみを数える
  • 'draft' — 下書きを数える（すべてのドキュメントが対象になる）
'draft''published' または 'draft'
filters使う フィルターnullObject
Note

公開済みドキュメントには必ず下書き側の対応もあるため、公開済みでも下書き版があるものとして数えられます。

そのため status: 'draft' で数えても、他の条件に一致するドキュメントの総数が返ります。一部はすでに公開済みで、Content Manager 上では「下書き」や「変更あり」と表示されない場合でも同様です。公開済みをこのカウントから除外する方法は現状ありません。

例​


基本的な例​

パラメータを省略すると、count() は既定ロケールのドキュメント総数を返します。

Example request
await strapi.documents('api::restaurant.restaurant').count()
公開済みだけを数える​

公開済みドキュメントだけを数えるには、count() に status: 'published' を他のパラメータと一緒に渡します。

locale を省略すると、既定ロケールのドキュメントが数えられます。

Example request
await strapi.documents('api::restaurant.restaurant').count({ status: 'published' })
フィルター付きで数える​

フィルター は count() にも渡せます。

locale と status の両方を省略すると、下書き（status 省略時の既定。公開済みも下書き版があるものとして数えられるため、ロケール内の利用可能ドキュメント総数に相当）が、既定ロケールについてだけ数えられます。

/**
 * 下書きドキュメント数を数える（status 省略時の既定）
 * 英語（既定ロケール）
 * 名前が 'Pizzeria' で始まるもの
 */
await strapi.documents('api::restaurant.restaurant').count({ filters: { name: { $startsWith: "Pizzeria" } } })
このページを編集