カテゴリー閲覧APIを利用することで、IBISEに登録しているカテゴリーの詳細情報を取得することができます。
カテゴリー閲覧APIのエンドポイントと、アクセスする際のHTTPメソッドは以下の通りです。URLに記載されている xxxxxx は、利用しているサブドメインに置き換えてください。
指定パラメータ
- カテゴリー詳細情報を取得する際は、以下の項目をクエリパラメータにて設定することができます。
項目 | キー | 必須/任意 | 型 | デフォルト値 | 説明 |
タイムゾーン | timezone | 任意 | string | 該当アカウントが選択しているタイムゾーン | 'Asia/Tokyo'などのタイムゾーンを表す文字列。これにより出力の日時のタイムゾーンを指定することができます。マスター文字列については こちら を参照ください。 |
閲覧者タイプ | viewer_type | 任意 | string | 'all_users' | カテゴリーを閲覧するユーザーのタイプを選択可能となります。現時点では、'all_users'のみ指定可能。'all_users'を選択の場合、管理者だけが閲覧可能、もしくは、エージェントのみが閲覧可能のカテゴリー情報は見れません。 |
ロケール | locale | 任意 | string | 該当アカウントの選択中のロケール | カテゴリー情報を閲覧する際の言語指定。'JAPANESE', 'ENGLISH', 'TRADITIONAL_CHINESE'のいずれか。 |
- 「公開」ステータスのカテゴリーのみ閲覧ができます。「公開」以外のステータスの記事が指定された場合、HTTPステータスコード 404(Not Found)が返されます。
- ロケールを指定する場合、該当ロケール情報がある場合のみ値が返ります。該当するロケール情報を保持しない場合は、404(Not Found)が返されます。
返り値
- 検索の結果情報(result) と、カテゴリの情報 (category) を JSON形式で返します。
結果情報 (result)
項目 | キー | 型 | 説明 |
APIバージョン | version | string | APIのバージョンを返す。v1なので'1'を返す。 |
カテゴリー情報 (category)
項目 | キー | 型 | 説明 |
カテゴリーID | category_id | number | カテゴリーの識別子 |
カテゴリー名 | name | string | カテゴリー名(指定localeでの表示) |
説明文 | description | string | カテゴリーの説明文(指定localeでの表示)。全文を表示します。 |
URL | url | string | ポータルサイトのカテゴリーページのURLを返します(指定localeでの表示)。ポータルサイト非公開の場合はnullを返します。 |
親カテゴリーID | 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で表示します。 |
エラー時の対処
- エラーが発生した場合、エラー種類を HTTP レスポンスのステータスコードに指定して、レスポンスを返します。
- また、補足のエラーメッセージがある場合は、以下のような形式で JSONでエラーメッセージを返します。errors が配列になっていることに注意してください。
例) timezone=Asia/Ebisu
{
errors: [
{
message: 'invalid timezone value: Asia/Ebisu'
}
]
}
具体例
リクエスト
https://xxxxxx.ibise.com/api/v1/categories/11
?timezone=Asia/Tokyo
&viwer_type=all_users
&locale=JAPANESE
レスポンス
{
result: {
version: '1'
},
category: {
category_id: 11,
name: '運営会社からのお知らせ',
description: '',
url: 'https://faq.ibise.com/ja/categories/11',
parent_category_id: null,
has_child_categories: false,
created_at: '2021-07-01T12:34:56+09:00',
updated_at: '2021-07-02T01:23:45+09:00'
},
}
}