統合検索API
概要
より高い柔軟性を提供し、エンタープライズ検索に新たな機能を設けるために、統合検索API作成しました。 統合APIは、サードパーティーの検索結果をWorkstationエンタープライズ検索に統合する方法です。
統合検索APIでは、統合をエンタープライズ検索に接続できるため、Workstationのエクスペリエンスを制御する検索機能を追加できます。
この記事では、Workstation - 統合検索APIを紹介します。
サードパーティの統合は、WalkMe Workstationに2つの主要な機能を追加します-
- エンタープライズ検索 - これを使用すると、ユーザーは単一の統一した検索を使用してアプリケーションやリソースを発見できます。
- ホーム画面ウィジェット - Workstation内で直接プロセスを開始し、一般的に使用されるツールとリソースへのアクセスを合理化します。
動作の仕組み
統合APIに接続された新しい統合を作成するには、2つのステップが必要です-
- セットアップ- 新しい統合を作成します。
- ランタイム- API（検索クエリ）から要求を取得し、応答（検索結果）を提供します。
両方のフローについて、このドキュメントで説明します。
セットアップ
新しい統合を作成するには、WalkMeに以下のパラメータを提供する必要があります：
|
パラメータ |
説明 |
| apiUrl |
Workstationサービスへのエンドポイントが、検索クエリ要求を送信します。 必須 |
| apiKey |
サービスの一意の識別子が要求ソースを認証します。 必須 |
| システムGUID |
Workstationアプリの設定>詳細情報画面にあります。 必須 |
| appDescription |
アプリの一行説明文です。これは統合ページでユーザーに表示されます。 適切なフォーマットの例- 「Workstationから直接Googleドライブのファイルを検索します」 必須 |
| customName |
統合の名前です。統合ページ、検索結果、アプリのフィルターに表示されます。 必須 |
| customImage |
統合ページ、検索結果、アプリのフィルターに表示されるアイコンのURLです。 必須 |
新しい統合を作成するには、上記の表に記載されているパラメータと関連するシステムGUIDをカスタマーサクセスマネージャーに問い合わせます。
将来的に、この機能はWalkMeコンソールに追加され、システム管理者が管理します。
以下の図で 説明されている通り、セットアップフローはDBで開始されます（将来的にはコンソールで実行されます）。 セットアップパラメーターを提供後、弊社で統合をテストして適切な応答を得ていることを確認します。
このテストは、弊社側で作成された「ダミーユーザー」で実行されます。 フローが正常に完了したかどうかを示す通常の検索クエリ呼び出しであるため、外部サービス側の設定やセットアップは必要ありません。
ランタイム
フローのトリガーは、エンドユーザーがWorkstationアプリで何かを検索した際に発生します。
APIコールは、以下の条件に従って、提供されたAPIキーでAPIエンドポイント（URL）に生成されます-
- ユーザーが3文字以上入力（中国語/日本語の場合は2文字）。
- 検索タイムアウトは、最後の文字入力（デバウンスとも呼ばれます）から300ミリ秒です。 つまり、ユーザーは連続で文字を入力しても、1文字ごとに検索をトリガーしませんが、タイムアウト後に検索が開始されます。
この検索クエリがトリガーされると、統合検索APIはパラメータ付きの検索クエリ呼び出しを送信します。
検索フロー
検索クエリ
統合APIから送信：
POST <apiURL>/(search)Content-type: application/jsonHeaders:{ Authorization: <apiKey>}Body:{ "user": "user@email.com" "system": "652c91b1ec444c76a313a68f69478b93" "env": "prod" "term": "itay"} |
|
パラメータ |
説明 |
| user | ユーザーのメール |
| システム | システムGUID - 32文字の文字列 |
| env | Workstation環境のタイプです。 利用可能な値-
|
| term | Workstationアプリに入力されている検索クエリ |
検索結果
統合APIに向けて送信されます（POSTコールとして）：
Body:[{ "id": "b2f8510d-9547-4d53-978f-6fc24371c113", "title": "Creating a user", "description": "WalkMe does not collect personally identifiable information (PII) other than IP addresses in logs for security purposes, end users' approximate geolocation (country and city in which they are located) and masked IP addresses for the ongoing operation of the WalkMe system.", "mimeType": "Answers", "externalType": "Article", "created": "2022-01-30T14:35:16.57Z", "modified": "2022-01-30T14:37:07.40Z", "source": "confluence", "category": "Gitlab Service User creation and configuration", "detail": "Account Management", "relationaltime": "2022-01-30T14:35:16.57Z" }}] |
APIリファレンス
| 属性 | タイプ | 説明 |
| id | String（文字列） |
アイテムの一意の識別子です。 必須 |
| タイトル | String（文字列） |
アイテムの名前です。 必須 |
| description | String（文字列） |
アイテムの説明/概要です。 入力すると、検索結果のタイトルは太字で表示され、説明がその下に表示されます。 オプション |
| link | URL |
検索結果をクリックすると、アイテムにアクセスするURLです。 必須 |
| mimeType | String（文字列） |
アイテムを表示すべきフィルターカテゴリです。 以下のリストにあるオプションのどれかと完全一致する必要があります。
必須 |
| externalType | String（文字列） |
アイテムタイプです。 例 - 記事、ダッシュボード、Caseなど 入力すると、統合名の横にあるアイテムに表示されます。 オプション |
| created | 日付時刻 |
アイテムが作成された日付と時刻です。 このパラメータはUIには表示されませんが、ソート目的で使用されます。 オプション |
| modified | 日付時刻 |
アイテムが直近で更新された日付と時刻です。 このパラメータはUIには表示されませんが、ソート目的で使用されます。 オプション |
| copy | String（文字列） |
入力すると、検索結果にコピーボタンが表示されます。 ボタンをクリックすると、提供されたテキスト（アイテムリンク、名前、IDなど）をコピーします。 通常、アイテムのリンクが入力されます。 オプション |
| confidence | Decimal（数値） |
応答の精度（パーセンテージ）を表示するために使用されるパラメータです。 入力すると、検索結果UIに表示されます。 オプション |
| source | String（文字列） |
応答のソース（例：Confluence）を表示します。 検索結果UIで虫眼鏡アイコンの横に表示されます。 オプション |
| category | String（文字列） |
Ask-AIが記事のカテゴリ（「パンくず」）を表示するために使用するパラメータです。 入力すると、タイトルの上の検索結果UIに表示されます。 オプション |
| poweredBy | String（文字列） |
入力すると、右下の検索結果UIにメモが表示されます。 入力しても、統合名とアイコンが結果に表示されないことに注意してください。 オプション |
| detail | String（文字列） |
入力すると、このデータは検索結果UI（統合名とexternalTypeの後）に表示されます。 オプション |
| relationalTime | 日付時刻 |
入力すると、このデータは検索結果UIの最後に表示されます。 提供された日付と現在時刻（例：3日前）に従って、比較した時刻が表示されます。 オプション |
制限
文字列フィールドは255文字に制限されています。
パラメータUIデザイン
Error Handling（エラー処理）
ほとんどの場合、フローでは、検索結果が表示されたことを示す「HTTP 200」と平文のokで応答しますが、検索結果の送信が失敗するシナリオに備える必要があります。
このセクションに表示されるエラーは、統合API側で生成されており、エラーの原因を可能な限り正確に表示しているはずです。
API応答は、不正なリクエストを受け取ったとき、有効ではなくなったキーが使用されたとき、例外により検索結果に到達できなかったときに、エラー（「HTTP 400」）の応答を行います。
|
エラー |
説明 |
| invalid_structure | 通常、受信した要求のフォームに問題があることを示します。JSONが正しく構造化されていないか、メッセージテキストが適切にエスケープされていない可能性があります。 リクエストは、修正なしで再試行しないでください。 |
| api_key_invalid | 提供されているAPIキーが存在しないか、無効であることを示します。 APIキーの変更なしでリクエストを再試行しないでください。 |
| api_url_invalid | 提供されたAPI URLが無効であることを示します。 API URLの変更なしでリクエストを再試行しないでください。 |
| title_invalid | 必須値であるタイトルが送信されていないか、文字制限内に含まれていないことを示します。 |
| link_invalid | 必須値であるリンクが送信されていないか、文字制限内に含まれていないことを示します。 |
| mimeType_invalid | 必須値であるmimeTypeが送信されていないか、文字制限内に含まれていないことを示します。 |
| id_invalid | 必須値であるIDが送信されていないか、文字制限内に含まれていないことを示します。 |
セキュリティ概要
エンタープライズサーチはサードパーティーの統合を使用して「federal search」を実装します。 Workstation内の検索は、NLPエンジンと優れたユーザーエクスペリエンスをサポートするグラフデータベースによって支えられています。
Workstationエンタープライズサーチは、独立した検索が可能なデータベースにサードパーティーデータの索引を作りません。
検索アルゴリズムを表した以下のシーケンスダイアグラムをご覧ください。
技術的なノート
WorkstationのServiceNow統合が正しく動作するようにするには、顧客は以下のIPをホワイトリストに登録する必要があります：
- QA: 54.229.168.224
- PROD: 52.53.115.147
- EUPROD: 3.126.219.141