Postmanを使ってFederated Search API経由で外部コンテンツのインデックス情報をインポートする

横断検索（Federated Search）はCustomer Hubの強力な機能の一つです。

Customer Community内の各種コンテンツ（QA、ディスカッション、ナレッジベース、アイディア、イベント、製品アップデート）のみならず、Customer Communityの外のコンテンツでさえも、検索の対象とすることができます。

それにより、Customer Community内で欲しい情報が見つかりやすくなり、この中だけでお客様の悩みが解決する可能性が高まり、お客様がセルフサービスで習熟を高めていくことができるようになります。

横断検索で外部のツール（サイト）の情報も検索対象とするために、Gainsightでは主要なツールとのコネクタを提供しています。2024年11月現在以下の製品とのコネクタを提供しています。

• Zendesk（Guide Help Center）
• Salesforce（Knowledge Base）
• Skilljar
• Thought Industries

それ以外のツールで作られたヘルプサイトや、ブログサイト、等の場合は、API経由でコンテンツのインデックス情報を連携しておくことで検索対象とすることが可能です。

API経由と聞くと、ハードルが高いと感じられるかもしれません。

当然、ブログ記事が追加されるたびに自動的にAPI経由でCustomer Hubにも情報が連携される、といったことをしようとすると技術的な知識が必要になってきます。

そこまで自動化できなくても、月に一回程度、リストを作って手動で連携できればいい、という場合は、カンタンな方法があります。

それがこの記事で紹介するす、Postmanというツールを使った方法です。

Postmanは様々なタイプのAPIを呼び出すことができる便利なツールで、無料で使用できます。

他のツールを使ってるよ、という方はこの記事を参考にしながら同様の設定をしてみてください。

1. 検索対象にしたい外部コンテンツのリストを準備

外部コンテンツを横断検索の対象にするために、事前にコンテンツの情報を登録しておくのですが、以下がその情報になります。

• title：コンテンツのタイトル
• content：中身。改行を取り除いた文章。この中身が検索対象となり、さらにスマートアシスタント（AI）が検索結果のサマリーを作るために読み込みます。
• url：コンテンツのURL
• source：ソース名。blog、column、whitepaper、等。ここで設定したものが検索結果のカテゴリとして使われます。小文字の英文字しか使えません。

上記が検索結果にどのように現れるかというイメージが以下です。

sourceは、APIで渡す文字列は小文字の英文字のみ可ですが、表示させる際にカスタマイズできます（日本語もOK）。

contentはここで連携した内容が検索対象になります。リンク先の情報を見にいくわけではないので、またAIがサマリを作成する対象も、この連携された内容がベースになります。

これらの情報をスプレッドシートなどにまとめておきます。

2. APIの接続のための各種パラメータを取得する

こちらの記事を参照して以下のパラメータを取得してください。

• APIベースURL
• Client ID
• Client Secret

3. Postmanで新規コレクションを作成し、認証の設定をする

Postmanを開き、新規にコレクションを作成し、Variablesタブにて、ClientIDとClientSecretを変数として登録し、保存。

Authorizationタブにて、Auth TypeでOAuth 2.0を選択

下にスクロールし、以下を設定

入力できたら、オレンジ色の【Get New Access Token】ボタンをクリック。

以下の画面が出たら【Use Token】をクリック。

AuthorizationタブのCurrent Tokenにトークン値が入っていることを確認し、

Auto-refresh Tokenをオンにする。

この設定により、トークンが無効になると新しいトークンが自動的に取得されるようになります。

4. インデックス情報のインポート

認証の設定ができたら、次にコンテンツを登録するためのリクエストを作成します。

コレクションの中にPOSTタイプのリクエストを作成します。

エンドポイントURL：[ベースURL]/external-content/index

リクエストの中のAuthorizationタブは、Auth Typeを Inherit auth from parentを選択。その他はそのままで大丈夫です。2で設定したコレクションの認証設定が引き継がれます。

Bodyタブに実際のインデックス情報をセットします。

RawタイプのJSONを選択し、こちらにあるように、以下のフォーマットで情報をセットします。

{
  "batch": [
    {
      "title": "string",
      "content": "string",
      "url": "string",
      "source": "string"
    }
  ]
}

以下サンプルです。

Sendボタンをクリックして、Responseが「1」となれば成功です。

早速検索で結果に出てくるかチェックしてみましょう。

5. その他

上記４では、1件のコンテンツをインポートする例を解説しましたが、配列で入れれば複数コンテンツを一度に入れることが可能です。

一度に沢山のコンテンツを入れるのであれば、１のリストをCSVにして、それをJSONに変換するツールなどでJSONにして貼り付けると便利ですね。
1度のコールで遅れる容量が５MBという制限があるので気をつけましょう。

また、入れるだけでなく、以下もPostmanを使ってAPIから操作できるので、コレクションの中にリクエストとして設定しておくと、何かと便利かと思います。

・特定のコンテンツを削除する（検索対象から外す）

・全てのコンテンツを削除する