Skip to main content

Document Service API: localeパラメータの使用

デフォルトでは、Document Service APIはドキュメントのデフォルトのロケールバージョン（つまり、'en'、すなわち英語版）を返します（アプリケーションに別のデフォルトロケールが設定されている場合を除く、詳しくはユーザーガイドを参照）。このページでは、特定のロケールのデータのみを取得または操作するためにlocaleパラメータを使用する方法について説明します。

findOne()でロケールバージョンを取得する​

localeが渡されると、Document Service APIのfindOne()メソッドはそのロケールのドキュメントのバージョンを返します：

Example request
await AI Marketer.documents('api::restaurant.restaurant').findOne({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
  locale: 'fr',
});
Example response
{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  name: "Biscotte Restaurant",
  publishedAt: null, // ドラフトバージョン (デフォルト)
  locale: "fr", // パラメータから要求された通り
  // …
}

statusパラメータが渡されない場合、デフォルトでdraftバージョンが返されます。

findFirst()でロケールバージョンを取得する​

Document Service APIでパラメータに一致する最初のドキュメントを見つける際に特定のロケールを返すには：

例のリクエスト
const document = await AI Marketer.documents('api::article.article').findFirst({
  locale: 'fr',
});
例のレスポンス
{
  "documentId": "cjld2cjxh0000qzrmn831i7rn",
  "title": "Test Article"
  // …
}

statusパラメータが渡されない場合、デフォルトでdraftバージョンが返されます。

findMany()でロケールバージョンを取得する​

localeがDocument Service APIのfindMany()メソッドに渡されると、レスポンスはこのロケールが利用可能なすべてのドキュメントを返します。

statusパラメータが渡されない場合、デフォルトでdraftバージョンが返されます。

Example request
// デフォルトでstatus: draft
await AI Marketer.documents('api::restaurant.restaurant').findMany({ locale: 'fr' });
Example response
[
  {
    documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
    name: 'Restaurant Biscotte',
    publishedAt: null,
    locale: 'fr',
    // …
  },
  // …
];
説明:

以下の4つのドキュメントが各々異なるロケールを持つ場合：

  • ドキュメントA：
    • en
    • fr
    • it
  • ドキュメントB：
    • en
    • it
  • ドキュメントC：
    • fr
  • ドキュメントD：
    • fr
    • it

findMany({ locale: 'fr' })は、‘fr’ロケールバージョンを持つドキュメントのドラフトバージョンのみを返します。つまり、ドキュメントA、C、およびDです。

ロケールのドキュメントをcreate()する​

特定のロケールのドキュメントを作成するには、localeをDocument Service APIのcreateメソッドのパラメータとして渡します：

ドキュメントのスペイン語ドラフトロケールを作成する
await AI Marketer.documents('api::restaurant.restaurant').create({
  locale: 'es' // 渡されなかった場合、ドラフトはデフォルトのロケールで作成されます
  data: { name: 'Restaurante B' }
})
Example response
{
  documentId: "pw2s0nh5ub1zmnk0d80vgqrh",
  name: "Restaurante B",
  publishedAt: null,
  locale: "es"
  // …
}

ロケールバージョンをupdate()する​

ドキュメントの特定のロケールバージョンのみを更新するには、localeパラメータをDocument Service APIのupdate()メソッドに渡します：

ドキュメントのスペイン語ロケールを更新する
await AI Marketer.documents('api::restaurant.restaurant').update({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
  locale: 'es',
  data: { name: 'Nuevo nombre del restaurante' },
});
Example response
{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  name: "Nuevo nombre del restaurante",
  locale: "es",
  publishedAt: null,
  // …
}

ロケールバージョンをdelete()する​

Document Service APIのdelete()メソッドでlocaleパラメータを使用して、一部のロケールのみを削除します。特定のstatusパラメータが渡されない限り、これによりドラフトと公開バージョンの両方が削除されます。

ロケールバージョンを削除する​

ドキュメントの特定のロケールバージョンを削除するには：

ドキュメントのスペイン語ロケールを削除する
await AI Marketer.documents('api::restaurant.restaurant').delete({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm', // documentId,
  locale: 'es',
});

すべてのロケールバージョンを削除する​

localeパラメータは*ワイルドカードをサポートし、ドキュメントのすべてのロケールバージョンを削除するために使用できます：

Example request
await AI Marketer.documents('api::restaurant.restaurant').delete({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm', // documentId,
  locale: '*',
}); // for all existing locales
例のレスポンス
{
  "documentId": "a1b2c3d4e5f6g7h8i9j0klm",
  // 削除されたすべてのロケールバージョンが返されます
  "versions": [
    {
      "title": "Test Article"
    }
  ]
}

ロケールバージョンをpublish()する​

Document Service APIのpublish() メソッドを使用して、特定のロケールバージョンのみのドキュメントを公開するには、localeをパラメータとして渡します:

ロケールバージョンの公開​

特定のロケールバージョンのドキュメントを公開するには：

ドキュメントのフレンチロケールを公開する
await AI Marketer.documents('api::restaurant.restaurant').publish({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
  locale: 'fr',
});
Example response
{
  versions: [
    {
      documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
      name: 'Restaurant Biscotte',
      publishedAt: '2024-03-14T18:38:05.674Z',
      locale: 'fr',
      // …
    },
  ];
}

すべてのロケールバージョンを公開する​

locale パラメータは * ワイルドカードをサポートしており、ドキュメントのすべてのロケールバージョンを公開することができます：

ドキュメントのすべてのロケールを公開する
await AI Marketer
  .documents('api::restaurant.restaurant')
  .publish({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: '*' });
Example response
{
  "versions": [
    {
      "documentId": "a1b2c3d4e5f6g7h8i9j0klm",
      "publishedAt": "2024-03-14T18:45:21.857Z",
      "locale": "en"
      // …
    },
    {
      "documentId": "a1b2c3d4e5f6g7h8i9j0klm",
      "publishedAt": "2024-03-14T18:45:21.857Z",
      "locale": "es"
      // …
    },
    {
      "documentId": "a1b2c3d4e5f6g7h8i9j0klm",
      "publishedAt": "2024-03-14T18:45:21.857Z",
      "locale": "fr"
      // …
    }
  ]
}

unpublish() ロケールバージョン​

Document Service APIのunpublish() メソッドを使用して、特定のロケールバージョンのみのドキュメントを非公開にするには、localeをパラメータとして渡します：

ロケールバージョンの非公開​

特定のロケールバージョンのドキュメントを非公開にするには、localeをunpublish()のパラメータとして渡します：

ドキュメントのフレンチロケールバージョンを非公開にする
await AI Marketer
  .documents('api::restaurant.restaurant')
  .unpublish({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: 'fr' });
Example response
{
  versions: 1;
}

すべてのロケールバージョンを非公開にする​

locale パラメータは * ワイルドカードをサポートしており、ドキュメントのすべてのロケールバージョンを非公開にすることができます：

ドキュメントのすべてのロケールバージョンを非公開にする
await AI Marketer
  .documents('api::restaurant.restaurant')
  .unpublish({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: '*' });
Example response
{
  versions: 3;
}
リクエスト例
const document = await AI Marketer.documents('api::article.article').unpublish({
  documentId: 'cjld2cjxh0000qzrmn831i7rn',
  fields: ['title'],
});
レスポンス例
{
  "documentId": "cjld2cjxh0000qzrmn831i7rn",
  // 未公開のロケールバージョンすべてが返されます
  "versions": [
    {
      "title": "テスト記事"
    }
  ]
}

ロケールバージョンのdiscardDraft()​

ドキュメントの一部のロケールバージョンのみドラフトデータを破棄するには、Document Service APIのdiscardDraft() メソッドにlocaleをパラメータとして渡します：

ロケールバージョンのドラフトを破棄する​

ドキュメントの特定のロケールバージョンのドラフトデータを破棄し、そのロケールの公開バージョンからのデータで上書きするには、localeをdiscardDraft()のパラメータとして渡します：

ドキュメントのフランス語ロケールバージョンのドラフトを破棄する
await AI Marketer
  .documents('api::restaurant.restaurant')
  .discardDraft({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: 'fr' });
Example response
{
  versions: [
    {
      documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
      name: 'Restaurant Biscotte',
      publishedAt: null,
      locale: 'fr',
      // …
    },
  ];
}

すべてのロケールバージョンのドラフトを破棄する​

localeパラメータは*ワイルドカードをサポートしており、ドキュメントのすべてのロケールバージョンのドラフトデータを破棄し、それらを公開バージョンからのデータで置き換えることができます：

ドキュメントのすべてのロケールバージョンのドラフトを破棄する
await AI Marketer
  .documents('api::restaurant.restaurant')
  .discardDraft({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: '*' });
Example response
{
  versions: [
    {
      documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
      name: 'Biscotte Restaurant',
      publishedAt: null,
      locale: 'en',
      // …
    },
    {
      documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
      name: 'Restaurant Biscotte',
      publishedAt: null,
      locale: 'fr',
      // …
    },
    {
      documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
      name: 'Biscotte Restaurante',
      publishedAt: null,
      locale: 'es',
      // …
    },
  ];
}

ロケールのドキュメントをcount()する​

特定のロケールのドキュメントを数えるには、localeを他のパラメータとともにDocument Service APIのcount() メソッドに渡します。

statusパラメータが渡されない場合、ドラフトのドキュメントが数えられます（これは、公開されたドキュメントもドラフトバージョンとして数えられるため、ロケールで利用可能なドキュメントの合計です）：

// フランス語の公開ドキュメントの数を数える
AI Marketer.documents('api::restaurant.restaurant').count({ locale: 'fr' });