カテゴリー検索API

山崎 翔平

2021-10-16T08:16:59.037Z

カテゴリー検索APIを利用することで、IBISEに登録しているカテゴリーを検索することができます。

カテゴリー検索APIのエンドポイントと、アクセスする際のHTTPメソッドは以下の通りです。URLに記載されている xxxxxx は、利用しているサブドメインに置き換えてください。

URLHTTPメソッド
https://xxxxxx.ibise.com/api/v1/categories/searchGET

指定パラメータ

  • カテゴリーを検索する際は、以下の項目をクエリパラメータにて設定することができます。
項目キー必須/任意デフォルト値説明
親カテゴリIDparent_category_id任意numbernull該当する親カテゴリーID。
親カテゴリ限定only_parent任意booleanfalseこのフラグをtrueにすると、第一階層のカテゴリーのみがヒットします。
タイムゾーンtimezone任意string該当アカウントが選択しているタイムゾーン'Asia/Tokyo'などのタイムゾーンを表す文字列。これにより出力の日時のタイムゾーンを指定することができます。マスター文字列については こちら を参照ください。
閲覧者タイプviewer_type任意string'all_users'カテゴリーを閲覧するユーザーのタイプを選択できます。現時点では、'all_users'のみ選択可能です。'all_users'を選択の場合、管理者だけが閲覧可能、もしくは、エージェントのみが閲覧可能のカテゴリー情報はヒットしません。
ロケールlocale任意string該当アカウントの選択中のロケールカテゴリー情報を閲覧する際の言語指定です。'JAPANESE', 'ENGLISH', 'TRADITIONAL_CHINESE'のいずれかになります。
ページ番号page任意number1取得するページ番号を指定します。
  • 検索対象となるのは「公開」ステータスのカテゴリのみとなります。
  • タイムゾーンの文字列マスタは、こちらを参照ください (TODO)
  • parent_category_id を指定し、only_parent=trueを指定した場合、常に0件のカテゴリーを返します。
  • ロケールを指定した場合、該当ロケールを持たないカテゴリーは、検索にヒットしません。

返り値

  • 検索の結果情報(result) と、カテゴリの一覧情報 (categories) を JSON形式で返します。

結果情報 (result)

項目キー説明
総カテゴリー数total_countnumber条件に該当するカテゴリー総数
取得件数num_categoriesnumber今回取得したカテゴリー数
現在のページ番号current_pagenumber現在のページ番号
最終ページ番号last_pagenumber最終ページ番号
APIバージョンversionstringAPIのバージョンを返す。v1なので'1'が返ります。

カテゴリー情報 (categories)

項目キー説明
カテゴリーIDcategory_idnumberカテゴリーの識別子
カテゴリー名namestringカテゴリー名(指定localeでの表示)
説明文descriptionstringカテゴリーの説明文(指定localeでの表示)。先頭300文字だけ表示され、300文字以上ある場合は、末尾に'...'が付きます。
URLurlstringポータルサイトのカテゴリーページURLを返す(指定localeでの表示)。ドメインマッピングをしている場合は、独自ドメインのURLが返ります。
親カテゴリーparent_category_idnumber親カテゴリーのID。親がいない場合はnullを返します。
子カテゴリの有無has_child_categoriesboolean子カテゴリを持つ場合はtrue, ない場合はfalseを返します。
ロケールlocalestringカテゴリー名や説明文の出力で利用しているロケールを表示。
作成日時created_atstringISO 8601のフォーマットで、指定timezoneで表示。
更新日時updated_atstringISO 8601のフォーマットで、指定timezoneで表示。
  • 1ページあたりのカテゴリー件数は、10件 となります。
  • page 指定が、last_page よりも大きい値を指定した場合、該当件数は0となり、カテゴリー情報は空の配列が返されます。

エラー時の対処

  • エラーが発生した場合、エラー種類を HTTP レスポンスのステータスコードに指定して、レスポンスを返します。
  • また、補足のエラーメッセージがある場合は、以下のような形式で JSONでエラーメッセージを返します。errors が配列になっていることに注意してください。
例) parent_category_id=aaaa (他のパラメータの場合も同様)
{
    errors: [
        {
             message: 'invalid parent_category_id value. parent_category_id:aaaa'
        }
    ]
}

具体例

リクエスト

https://xxxxxx.ibise.com/api/v1/categories/search
  ?only_parent=true
  &timezone=Asia/Tokyo
  &viwer_type=all_users
  &locale=JAPANESE

レスポンス

{
  result: {
    total_count: 58,
    num_categories: 10,
    current_page: 1,
    last_page: 1,
    version: '1'
  },
  categories: [
    {
      category_id: 11,
      name: '運営会社からのお知らせ',
      description: '',
      url: 'https://faq.ibise.com/ja/categories/11',
      parent_category_id: null,
      has_child_categories: false,
      locale: 'JAPANESE',
      created_at: '2021-07-01T12:34:56+09:00',
      updated_at: '2021-07-02T01:23:45+09:00'
    },
    {
      category_id: 23,
      name: 'よく閲覧されている記事',
      description: '',
      url: 'https://faq.ibise.com/ja/categories/23',
      parent_category_id: null,
      has_child_categories: false,
      locale: 'JAPANESE',
      created_at: '2021-07-02T12:34:56+09:00',
      updated_at: '2021-07-02T01:23:45+09:00'
    },
    ...
  ]
}
お問い合わせ