統合検索API
概要
より柔軟性を提供し、エンタープライズ検索を新しい機能に開くために、統合検索APIを作成しました。 統合APIはサードパーティー検索結果をWorkstationエンタープライズ検索に統合する方法です。
統合検索APIを使用すると、統合をエンタープライズ検索に接続できるため、検索機能を追加してWorkstationのエクスペリエンスを制御できます。
この文書では、「Workstation - 統合検索API」について説明します。
サードパーティーの統合はWalkMe Workstationに2つの主な機能を追加します-
- エンタープライズ検索-1つの統合検索で、ユーザーはアプリケーションとリソースを発見することができます。
- ホーム画面ウィジェット-Workstation内で一般的に使用されるツールやリソースへのアクセスを合理化することによって直接プロセスを開始します。
仕組み
統合APIに接続された新しい統合を作成するには、2つのステップが必要です-
- セットアップ- 新しい統合を作成します。
- 実行時間- API（検索クエリ）からリクエストを取得し、レスポンス（検索結果）を提供します。
両方のフローについてこのドキュメントで説明します。
セットアップ
新しい統合を作成するには、WalkMeに以下のパラメータを提供することが必要です：
|
パラメータ |
説明 |
| apiUrl |
そのWorkstationサービスのエンドポイントは、検索クエリ要求を送信します。 必須 |
| apiKey |
あなたのサービスの一意の識別子は、リクエストソースを認証します。 必須 |
| システムGUID |
>画面についてのWorkstationアプリの設定にあります。 必須 |
| appDescription |
アプリのワンライナーの説明は、統合ページのユーザーに表示されます。 適切なフォーマットの例- 「Workstationから直接Googleドライブファイルを検索します。」 必須 |
| customName |
統合の名前は統合ページ、検索結果、アプリのフィルタに表示されます。 必須 |
| customImage |
統合ページ、検索結果、アプリのフィルタに表示されるアイコンのURL。 必須 |
新しい統合を作成するには、上記の表に記載されたパラメータと関連するシステムGUIDでカスタマーサクセスマネージャに連絡をとってください。
将来的には、この機能はWalkMeコンソールに追加され、システム管理者によって管理されます。
a.で以下のように説明します。 以下の図に、セットアップフローはDBで開始されます（将来はConsoleで実行されます）。 セットアップパラメータを提供した後、適切なレスポンスを取得することを確認するために統合をテストします。
このテストは、私たちの側で作成された「ダミーユーザー」で実行されます。 フローが正常に完了したかどうかを示す検索クエリ呼び出しであるため、外部サービス側の設定やセットアップは必要ありません。
実行時間
フローのトリガーは、Workstationアプリでエンドユーザーが何かを検索します。
API呼び出しは、以下の条件に従って提供されたAPIキーでAPIエンドポイント（URL）に生成されます-
- ユーザーは3文字以上（または中国語/日本語の2文字）を入力します。
- 検索タイムアウトは、入力された最後の文字（Debounceとも呼ばれます）から300ms (ミリ秒) です。 つまり、ユーザーは連続したペースで文字を入力でき、各文字は検索をトリガーしませんが、タイムアウト後に開始します。
検索クエリがトリガされると、統合検索APIはパラメーターで検索クエリ呼び出しを送信します。
検索フロー
検索クエリ
統合APIから送信されます：
POST <apiURL>/(search)Content-type: application/jsonHeaders:{ Authorization: <apiKey>}Body:{ "user": "user@email.com" "system": "652c91b1ec444c76a313a68f69478b93" "env": "prod" "term": "itay"} |
|
パラメータ |
説明 |
| User（ユーザー） | ユーザーのEメール |
| システム | システム GUID-32文字の文字列 |
| env | Workstation環境のタイプ。 利用可能な値-
|
| ターム | 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（文字列） |
アイテムの一意の識別子 必須 |
| title | String（文字列） |
アイテムの名前 必須 |
| 説明 | String（文字列） |
アイテムの説明/サマリー 入力すると、検索結果タイトルは太字で表示され、説明は下に表示されます。 オプション |
| リンク | URLの基になるURLルールは、 |
検索結果をクリックすると、アイテムにアクセスするURL 必須 |
| mimeType | String（文字列） |
アイテムが表示されるフィルターカテゴリ このリストに表示される以下のオプションのいずれかの正確な一致である必要があります-
必須 |
| externalType | String（文字列） |
アイテムタイプ 例えば、記事、ダッシュボード、ケースなど 入力すると、統合名の隣のアイテムに表示されます。 オプション |
| Created（作成日） | 日時 |
日付と時刻アイテムが作成されました。 このパラメーターはUIに表示されませんが、ソート目的で使用されます。 オプション |
| 変更済み | 日時 |
日付と時刻アイテムは最近更新されました。 このパラメーターはUIに表示されませんが、ソート目的で使用されます。 オプション |
| コピー | String（文字列） |
入力すると、検索結果にコピーボタンが表示されます。 そのボタンをクリックすると、提供されたテキスト（アイテムリンク、名前、IDなど）をコピーします。 通常、アイテムのリンクで入力されます。 オプション |
| 信頼 | 小数点 |
レスポンス（パーセント）の精度を表示するために使用するパラメータ 入力すると、検索結果UIに表示されます。 オプション |
| ソース | String（文字列） |
レスポンスソースを表示します（- Confluenceなど）。 虫眼鏡アイコンの隣の、検索結果に表示されます。 オプション |
| カテゴリ | String（文字列） |
Ask-AIで使用するパラメータで、記事のカテゴリ（「パン粉」）を表示します。 入力すると、タイトルの上にある検索結果UIに表示されます。 オプション |
| poweredBy | String（文字列） |
入力すると、右下の検索結果UIにメモが表示されます。 入力すると、結果に統合名とアイコンが表示されないことに注意してください。 オプション |
| 詳細 | String（文字列） |
入力すると、このデータは検索結果UIに表示されます（統合名とexternalTypeの後）。 オプション |
| relationalTime | 日時 |
入力すると、このデータは検索結果UIの最後に表示されます。 VS現在時刻が提供した日時に従って関係時間が表示されます（例：- 3日前）。 オプション |
制限
文字列フィールドは255文字に制限されます。
パラメータUIデザイン
Error Handling（エラー処理）
ほとんどの場合、フローはプレーンテキストOKで「HTTP 200」レスポンスという結果を招き、検索結果が正常に表示されたことを示しますが、検索結果を送信しようとする試みが失敗するシナリオに備える必要があります。
このセクションで表示されるエラーは、統合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エンタープライズサーチは、独自に検索可能なデータベースにサードパーティーデータの索引を作りません。
検索アルゴリズムを表した以下のシーケンスダイアグラムをご覧ください。
