カテゴリー検索APIを利用することで、IBISEに登録しているカテゴリーを検索することができます。
カテゴリー検索APIのエンドポイントと、アクセスする際のHTTPメソッドは以下の通りです。URLに記載されている xxxxxx は、利用しているサブドメインに置き換えてください。
指定パラメータ
- カテゴリーを検索する際は、以下の項目をクエリパラメータにて設定することができます。
項目 | キー | 必須/任意 | 型 | デフォルト値 | 説明 |
親カテゴリID | parent_category_id | 任意 | number | null | 該当する親カテゴリーID。 |
親カテゴリ限定 | only_parent | 任意 | boolean | false | このフラグをtrueにすると、第一階層のカテゴリーのみがヒットします。 |
タイムゾーン | timezone | 任意 | string | 該当アカウントが選択しているタイムゾーン | 'Asia/Tokyo'などのタイムゾーンを表す文字列。これにより出力の日時のタイムゾーンを指定することができます。マスター文字列については こちら を参照ください。 |
閲覧者タイプ | viewer_type | 任意 | string | 'all_users' | カテゴリーを閲覧するユーザーのタイプを選択できます。現時点では、'all_users'のみ選択可能です。'all_users'を選択の場合、管理者だけが閲覧可能、もしくは、エージェントのみが閲覧可能のカテゴリー情報はヒットしません。 |
ロケール | locale | 任意 | string | 該当アカウントの選択中のロケール | カテゴリー情報を閲覧する際の言語指定です。'JAPANESE', 'ENGLISH', 'TRADITIONAL_CHINESE'のいずれかになります。 |
ページ番号 | page | 任意 | number | 1 | 取得するページ番号を指定します。 |
- 検索対象となるのは「公開」ステータスのカテゴリのみとなります。
- タイムゾーンの文字列マスタは、こちらを参照ください (TODO)
- parent_category_id を指定し、only_parent=trueを指定した場合、常に0件のカテゴリーを返します。
- ロケールを指定した場合、該当ロケールを持たないカテゴリーは、検索にヒットしません。
返り値
- 検索の結果情報(result) と、カテゴリの一覧情報 (categories) を JSON形式で返します。
結果情報 (result)
項目 | キー | 型 | 説明 |
総カテゴリー数 | total_count | number | 条件に該当するカテゴリー総数 |
取得件数 | num_categories | number | 今回取得したカテゴリー数 |
現在のページ番号 | current_page | number | 現在のページ番号 |
最終ページ番号 | last_page | number | 最終ページ番号 |
APIバージョン | version | string | APIのバージョンを返す。v1なので'1'が返ります。 |
カテゴリー情報 (categories)
項目 | キー | 型 | 説明 |
カテゴリーID | category_id | number | カテゴリーの識別子 |
カテゴリー名 | name | string | カテゴリー名(指定localeでの表示) |
説明文 | description | string | カテゴリーの説明文(指定localeでの表示)。先頭300文字だけ表示され、300文字以上ある場合は、末尾に'...'が付きます。 |
URL | url | string | ポータルサイトのカテゴリーページURLを返す(指定localeでの表示)。ドメインマッピングをしている場合は、独自ドメインのURLが返ります。 |
親カテゴリー | parent_category_id | number | 親カテゴリーのID。親がいない場合はnullを返します。 |
子カテゴリの有無 | has_child_categories | boolean | 子カテゴリを持つ場合はtrue, ない場合はfalseを返します。 |
ロケール | locale | string | カテゴリー名や説明文の出力で利用しているロケールを表示。 |
作成日時 | created_at | string | ISO 8601のフォーマットで、指定timezoneで表示。 |
更新日時 | updated_at | string | ISO 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'
},
...
]
}