記事検索API

山崎 翔平

2021-10-20T06:44:13.705Z

記事検索APIを利用することで、IBISEに登録している記事を検索することができます。

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

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

指定パラメータ

  • 記事を検索する際は、以下の項目をクエリパラメータにて設定することができます。
項目キー必須/任意型デフォルト値説明
カテゴリーIDcategory_id任意numbernull該当するカテゴリーID。
キーワードkeyword任意stringnullキーワード検索を行う場合のキーワード指定。
タイムゾーンtimezone任意string該当アカウントが選択しているタイムゾーン'Asia/Tokyo'などのタイムゾーンを表す文字列。これにより出力の日時のタイムゾーンを指定することができます。マスター文字列については こちら を参照ください。
閲覧者タイプviewer_type任意string'all_users'記事を閲覧するユーザーのタイプを選択できます。現時点では、'all_users'のみ選択可能です。'all_users'を選択の場合、管理者だけが閲覧可能だったり、エージェントのみが閲覧可能の記事情報はヒットしません。
ロケールlocale任意string該当アカウントの選択中のロケール記事情報を閲覧する際の言語指定。'JAPANESE', 'ENGLISH', 'TRADITIONAL_CHINESE'のいずれかになります。
ページ番号page任意number1取得するページ番号を指定します。
  • 検索対象となるのは「公開」ステータスの記事のみとなります。
  • カテゴリーIDを指定した時、該当カテゴリ直下の記事、および、該当カテゴリの全ての子カテゴリの直下の記事がヒットします。
  • 記事は、ポータルサイトの記事一覧と同様、優先度の高い順 > IDの小さい順 の順序となります。
  • 1ページ当たりの記事件数は、10件となります。

返り値

  • 検索の結果情報(result) と、記事の一覧情報 (articles) を JSON形式で返します。

結果情報 (result)

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

記事情報 (articles)

項目キー型説明
記事IDarticle_idnumber記事の識別子
カテゴリーIDcategory_idnumber記事が所属するカテゴリーのID
カテゴリー情報categoryany記事が所属するカテゴリー情報。カテゴリー一覧APIが返す項目に従います。
記事タイトルtitlestring記事タイトル(指定localeでの表示)
記事本文bodystring記事の本文(指定localeでの表示)。markdownをhtml化してさらにhtmlタグを除外したもので、先頭300文字だけ表示されます。300文字以上ある場合は、末尾に'...'が付きます。
URLurlstringポータルサイトの記事ページのURLを返します（指定localeでの表示）。ポータルサイト非公開の場合はnullを返します。
ロケールlocalestring記事のタイトルなどの出力で利用しているロケールを表示。
公開日時published_atstringISO 8601のフォーマットで、指定timezoneで表示。
作成日時created_atstringISO 8601のフォーマットで、指定timezoneで表示。
更新日時updated_atstringISO 8601のフォーマットで、指定timezoneで表示。

エラー時の対処

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

具体例

リクエスト

https://xxxxxx.ibise.com/api/v1/articles/search
  ?category_id=11
  &status=open
  &timezone=Asia/Tokyo
  &viwer_type=all_users
  &locale=JAPANESE
  &page=1

レスポンス

{
  result: {
    total_count: 8
    num_articles: 8
　　　　　　　　current_page: 1,
    last_page: 1,
    version: '1'
  },
  articles: [
    {
      article_id: 200,
      category_id: 11,
      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'
      },
      title: 'IBiSEお客様限定_8月活用セミナーのお知らせ',
      body: '8月19日IBiSE活用セミナーを開催します！オンライン開催になりますのでお気軽にご参加ください！日時：8月19日（木）10:00-11:00内容：①新サポート制度：IBiSEサポートメンバーシップのご案内②特集：夏の宿題！？FAQ文章作成のコツ教えます！③いただいたお問い合わせについてピックアップ解説お申し込みはコチラ：',
      url: 'https://faq.ibise.com/ja/articles/199',
      locale: 'JAPANESE',
      published_at: '2021-07-01T12:34:56+09:00',
      created_at: '2021-07-01T12:34:56+09:00',
      updated_at: '2021-08-10T09:10:47+09:00'
    },
    ...
  ]
}
お問い合わせ