Skip to main content

ドキュメントサービスAPI

ドキュメントサービスAPIはクエリエンジンAPI の上に構築され、ドキュメントのCRUD（作成、取得、更新、削除）操作を実行するために使用されます。

ドキュメントサービスAPIを使用すると、ドキュメントのカウントも行うことができ、コンテンツタイプにDraft & Publishが有効になっている場合は、ドキュメントの公開/非公開やドラフトの破棄など、AI Marketer特有の機能を実行することもできます。

:::AI Marketer Entity Service APIはAI Marketer 5で廃止されました ドキュメントサービスAPIは、AI Marketer v4で使用されていたEntity Service APIを置き換えることを意図しています（[AI Marketer v4のドキュメンテーションを参照](https://docs-v4.AI Marketer.io/dev-docs/api/entity-service)）。Entity Service APIからドキュメントサービスAPIへの移行に関する追加情報は、関連する移行リファレンスで見つけることができます。 :::

✏️ Note

関連性もまた、REST APIと同様に、ドキュメントサービスAPIを通じて接続、切断、設定することができます（例はREST API関連性ドキュメンテーションを参照）。

findOne()​

渡されたdocumentIdとパラメータに一致するドキュメントを見つけます。

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

パラメータ​

パラメータ説明デフォルトタイプ
documentIdドキュメントのIDID
locale作成するドキュメントのロケールデフォルトのロケール文字列またはundefined
statusコンテンツタイプに対して下書き＆公開が有効化されている場合:
公開ステータス、次のいずれか可能:
  • 'published' は公開済みのドキュメントのみを検索
  • 'draft' は下書きのドキュメントのみを検索
'draft''published'または'draft'
fields返却するフィールドを選択すべてのフィールド
(デフォルトでは取得されないものを除く)		オブジェクト
populate追加のフィールドで結果を補完する。nullオブジェクト

例​

documentIdのみが他のパラメータなしで渡される場合、findOne()はデフォルトのロケールでドキュメントの下書きバージョンを返します。

documentIdを渡してドキュメントを検索する
await AI Marketer.documents('api:restaurant.restaurant').findOne({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm'
})
Example response
{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  name: "Biscotte Restaurant",
  publishedAt: null, // 下書きバージョン (デフォルト)
  locale: "en", // デフォルトのロケール
  // …
}

findFirst()​

パラメータに一致する最初のドキュメントを見つけます。

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

パラメータ​

パラメータ説明デフォルトタイプ
locale検索するドキュメントのロケールデフォルトのロケール文字列またはundefined
statusコンテンツタイプに対して下書き＆公開が有効化されている場合:
公開ステータス、次のいずれか可能:
  • 'published' は公開済みのドキュメントのみを検索
  • 'draft' は下書きのドキュメントのみを検索
'draft''published'または'draft'
filters使用するフィルタnullオブジェクト
fields返却するフィールドを選択すべてのフィールド
(デフォルトでは取得されないものを除く)		オブジェクト
populate追加のフィールドで結果を補完する。nullオブジェクト

例​

一般的な例​

デフォルトでは、findFirst()は、渡された一意の識別子（コレクションタイプIDまたはシングルタイプID）の最初のドキュメントの下書きバージョンをデフォルトのロケールで返します：

最初のドキュメントを見つける
await AI Marketer.documents('api::restaurant.restaurant').findFirst()
Example response
{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  name: "Restaurant Biscotte",
  publishedAt: null,
  locale: "en"
  // …
}

パラメーターに一致する最初のドキュメントを見つける​

findFirst()にいくつかのパラメーターを渡すと、それらに一致する最初のドキュメントが返されます。

localeやstatusのパラメーターが渡されない場合、結果はデフォルトのロケールの下書きバージョンを返します：

定義されたフィルターに一致する最初のドキュメントを見つける
await AI Marketer.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コンテンツタイプに対してDraft & Publishが有効になっている場合：
公開ステータスは次のいずれかです：
  • 'published' は公開済みのドキュメントのみを見つける
  • 'draft' は下書きのドキュメントのみを見つける
'draft''published'または'draft'
filters使用するフィルターnullオブジェクト
fields返すフィールドを選択すべてのフィールド
(デフォルトでは生成されないものを除く)		オブジェクト
populate追加のフィールドで結果を補完します。nullオブジェクト
pagination結果をページネーションする
sort結果をソートする

例​

一般的な例​

パラメーターが渡されない場合、findMany()は各ドキュメントの下書きバージョンをデフォルトのロケールで返します：

特定のフィルターに一致するドキュメントを見つける
await AI Marketer.documents('api::restaurant.restaurant').findMany()
Example response
[
  {
    documentId: "a1b2c3d4e5f6g7h8i9j0klm",
    name: "Biscotte Restaurant",
    publishedAt: null, // ドラフトバージョン（デフォルト）
    locale: "en" // デフォルトのロケール
    // …
  },
  {
    documentId: "j9k8l7m6n5o4p3q2r1s0tuv",
    name: "Pizzeria Arrivederci",
    publishedAt: null,
    locale: "en"
    // …
  },
]

パラメータに一致するドキュメントを見つける​

使用可能なフィルタは、ドキュメントサービスAPIリファレンスのフィルタページで詳細に説明されています。

localeやstatusパラメータが渡されない場合、結果はデフォルトのロケールのドラフトバージョンを返します：

特定のフィルタに一致するドキュメントを見つける
await AI Marketer.documents('api::restaurant.restaurant').findMany(
  {
    filters: {  
      name: {
        $startsWith: 'Pizzeria'
      }
    }
  }
)
Example response
[
  {
    documentId: "j9k8l7m6n5o4p3q2r1s0tuv",
    name: "Pizzeria Arrivederci",
    locale: "en", // デフォルトのロケール
    publishedAt: null, // ドラフトバージョン (デフォルト)
    // …
  }, 
  // …
]

create()​

ドラフトのドキュメントを作成し、それを返します。

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

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

パラメータ​

パラメータ説明デフォルトタイプ
locale作成するドキュメントのロケール。デフォルトのロケール文字列または undefined
fields返すフィールドを選択すべてのフィールド
(デフォルトでは入力されないものを除く)		オブジェクト
statusコンテンツタイプに下書き＆公開が有効になっている場合：
ドキュメントを作成する際に自動的に下書きバージョンを'published'に設定できます		-'published'
populate追加のフィールドで結果を補完します。nullオブジェクト

例​

localeパラメータが指定されていない場合、create()はデフォルトのロケールのドキュメントの下書きバージョンを作成します：

新しい 'Restaurant B' ドキュメントを作成
await AI Marketer.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使用するフィルタnullオブジェクト
fields返すフィールドを選択すべてのフィールド
(デフォルトでは入力されないものを除く)		オブジェクト
statusコンテンツタイプに下書き＆公開が有効になっている場合：
ドキュメントを更新する際に自動的に下書きバージョンを'published'に設定できます		-'published'
populate追加のフィールドで結果を補完します。nullオブジェクト
💡 Tip

公開されたバージョンは読み取り専用なので、文書の公開バージョンを技術的に更新することはできません。 文書を更新し、新しいバージョンをすぐに公開するには、次の方法があります:

  • ドラフトバージョンを update() で更新し、それを publish() で公開する。
  • または、update() に渡される他のパラメータと一緒に status: 'published' を直接追加します（status のドキュメンテーションを参照）。

例​

locale パラメータが渡されない場合、update() はデフォルトのロケールの文書を更新します:

Example request
await AI Marketer.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()​

文書、またはその特定のロケールを削除します。

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

パラメータ​

パラメータ説明デフォルトタイプ
documentId文書のIDID
locale削除する文書のロケールバージョン。null
(デフォルトのロケールのみを削除)		文字列、'*'、または null
filters使用するフィルタnullオブジェクト
fields戻り値に含めるフィールドを選択全てのフィールド
(デフォルトではないものを除く)		オブジェクト
populate追加のフィールドで結果を補完する。nullオブジェクト

例​

locale パラメータが渡されない場合、delete() は文書のデフォルトのロケールバージョンのみを削除します。これにより、ドラフトバージョンと公開バージョンの両方が削除されます:

Example request
await AI Marketer.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"
      // …
    }
  ]
}

localeパラメータが渡されない場合、デフォルトのロケールバージョンのみが削除されます：

Example request
await AI Marketer.documents('api::restaurant.restaurant').delete(
  { filters: { name: { $startsWith: 'Pizzeria' }}}
)
-->

publish()​

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

このメソッドは、コンテンツタイプでドラフト＆公開が有効になっている場合のみ利用可能です。

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

パラメータ​

パラメータ説明デフォルトタイプ
documentIdドキュメントのIDID
locale公開するドキュメントのロケール。デフォルトのロケールのみString, '*', または null
filters使用するフィルタnullオブジェクト
fields戻り値として選択するフィールドすべてのフィールド
(デフォルトで人口が多いものを除く)		オブジェクト
populate結果を追加フィールドで補完します。nullオブジェクト

例​

localeパラメータが渡されない場合、publish()はドキュメントのデフォルトのロケールバージョンのみを公開します：

Example request
await AI Marketer.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使用するフィルタnullオブジェクト
fields戻すフィールドを選択すべてのフィールド
(デフォルトでポピュレートされないものを除く)		オブジェクト
populate追加のフィールドで結果をポピュレートする。nullオブジェクト

例​

localeパラメータが渡されない場合、unpublish()はドキュメントのデフォルトロケールバージョンのみを非公開にします：

Example request
await AI Marketer.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使用するフィルタnullオブジェクト
fields戻すフィールドを選択すべてのフィールド
(デフォルトでポピュレートされないものを除く)		オブジェクト
populate追加のフィールドで結果をポピュレートする。nullオブジェクト

例​

localeパラメータが渡されない場合、discardDraft()はデフォルトのロケールのドラフトデータを破棄し、公開されたバージョンで上書きします：

ドキュメントのデフォルトロケールのドラフトを破棄する
AI Marketer.documents.discardDraft({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm', 
});
Example response
{
  documentId: "lviw819d5htwvga8s3kovdij",
  entries: [
    {
      documentId: "lviw819d5htwvga8s3kovdij",
      name: "Biscotte Restaurant",
      publishedAt: null,
      locale: "en"
      // …
    }
  ]
}

count()​

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

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

パラメーター​

パラメーター説明デフォルトタイプ
locale数えるドキュメントのロケールデフォルトのロケールString または null
statusコンテンツタイプに対してDraft & Publishが有効になっている場合:
出版状態は次のいずれかになります：
  • 'published' は公開済みのドキュメントのみを見つけます
  • 'draft' はドラフトのドキュメントを見つけます（すべてのドキュメントを返します）
'draft''published' または 'draft'
filters使用するフィルタnullObject
✏️ Note

公開されたドキュメントは必ずドラフト版も持っているため、公開されたドキュメントはドラフト版があるとしてもカウントされます。

これは、status: 'draft' パラメーターでカウントすると、他のパラメーターに一致するドキュメントの総数が返されるということを意味します。たとえ一部のドキュメントがすでに公開されており、Content Managerで「ドラフト」または「修正済み」として表示されなくなっても、すでに公開されたドキュメントがカウントされることを防ぐ方法は現在ありません。

例​

一般的な例​

パラメーターが何も渡されない場合、count() メソッドはデフォルトのロケールのドキュメントの総数を返します:

Example request
await AI Marketer.documents('api::restaurant.restaurant').count()

公開されたドキュメントの数を数える​

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

locale パラメーターが渡されない場合、デフォルトのロケールのドキュメントが数えられます。

Example request
AI Marketer.documents('api::restaurant.restaurant').count({ status: 'published' })

フィルターを使用してドキュメントの数を数える​

任意のフィルタを count() メソッドに渡すことができます。

locale と status パラメーターが渡されない場合、ドラフトのドキュメント（公開されたドキュメントもドラフト版としてカウントされるので、ロケールの利用可能なドキュメントの総数）がデフォルトのロケールのみで数えられます：

/**
 * ドラフトのドキュメント数を数える（ステータスが省略された場合のデフォルト） 
 * 英語（デフォルトのロケール） 
 * 名前が 'Pizzeria' で始まる
 */
AI Marketer.documents('api::restaurant.restaurant').count({ filters: { name: { $startsWith: "Pizzeria" }}})`