API de búsqueda de integraciones
Breve descripción general
Para proporcionar más flexibilidad y abrir la búsqueda empresarial a nuevas capacidades, hemos creado la API de búsqueda de integraciones. La API de integraciones es la forma de integrar los resultados de búsqueda de terceros en el menú de escritorio Enterprise Search.
La API de búsqueda de integraciones te permite conectar integraciones a Enterprise Search para que puedas añadir capacidades de búsqueda y controlar la experiencia en el menú de escritorio.
Este artículo presenta el menú de escritorio: API de búsqueda de integraciones.
Las integraciones de terceros añaden dos capacidades principales al menú de escritorio:
- Búsqueda empresarial: permite a los usuarios descubrir aplicaciones y recursos con una sola búsqueda unificada.
- Widgets de pantalla de inicio: inicia procesos directamente dentro del menú del escritorio y agiliza el acceso a herramientas y recursos de uso común.
¿Cómo funciona?
Para crear una nueva integración conectada a la API de Integraciones, se requieren dos pasos:
- Configuración: crea una nueva integración.
- Runtime: obtiene una solicitud de la API (consulta de búsqueda) y proporciona una respuesta (resultados de búsqueda).
Ambos flujos se explicarán en este documento.
Configuración
Para crear una nueva integración, será necesario proporcionar a WalkMe los siguientes parámetros:
|
Parámetro |
Descripción |
| apiUrl |
El punto final al que los servicios de menú de escritorio enviarán la solicitud de consulta de búsqueda. Necesario |
| apiKey |
El identificador único del servicio autentica el origen de la solicitud. Necesario |
| GUID del sistema |
Ubicado en la pantalla Ajustes Acerca de la aplicación del menú de escritorio>. Necesario |
| appDescription |
Descripción breve de la aplicación, que aparecerá a los usuarios en la página de Integraciones. Ejemplo de un formato adecuado: "Busca en los archivos de Google Drive directamente desde el menú del escritorio". Necesario |
| Nombre personalizado |
Nombre de la integración, que aparecerá en la página de Integraciones, los resultados de búsqueda y el filtro de la aplicación. Necesario |
| Imagen personalizada |
URL del icono que aparecerá en la página de Integraciones, los resultados de búsqueda y el filtro de la aplicación. Necesario |
Para crear una nueva integración, ponte en contacto con tu gerente de éxito del cliente con los parámetros enumerados en la tabla anterior y el GUID del sistema relevante.
En el futuro, esta capacidad se añadirá a la consola de WalkMe y será administrada por el administrador del sistema.
Como se describe a continuación en a. En la siguiente figura, el flujo de configuración comienza en DB (en el futuro se realizará en la consola). Después de proporcionarnos los parámetros de configuración, probamos la integración para asegurarnos de que obtengamos una respuesta adecuada.
Esta prueba se realizará con un "usuario ficticio" creado por nosotros. No requiere ninguna configuración en el servicio externo, ya que será una consulta de búsqueda normal que indicará si el flujo se ha realizado con éxito.
Tiempo de ejecución
El desencadenador del flujo es: el usuario final busca algo en la aplicación del menú de escritorio.
Se generará una llamada a la API al punto final de la API (URL) con la clave de la API proporcionada, de acuerdo con las siguientes condiciones:
- El usuario escribe 3 caracteres o más (o 2 caracteres en chino o japonés).
- El tiempo de espera de búsqueda es de 300 ms (milisegundos) a partir del último carácter escrito (también conocido como "debounce"). Eso significa que el usuario puede escribir letras a un ritmo continuo y que cada letra no activará la búsqueda, sino que comenzará después del tiempo de espera.
Una vez que se active esta consulta de búsqueda, la API de búsqueda de integraciones enviará una llamada de consulta de búsqueda con los parámetros.
Flujo de búsqueda
Consulta de búsqueda
Enviado desde la API de integraciones:
POST <apiURL>/(search)Content-type: application/jsonHeaders:{ Authorization: <apiKey>}Body:{ "user": "user@email.com" "system": "652c91b1ec444c76a313a68f69478b93" "env": "prod" "term": "itay"} |
|
Parámetro |
Descripción |
| usuario | Correo electrónico del usuario |
| WalkMe Menu | GUID del sistema: una cadena de 32 caracteres. |
| env | Tipo del entorno del menú de escritorio. Valores disponibles-
|
| término | Consulta de búsqueda que se está escribiendo en la aplicación del menú de escritorio |
Resultados de la búsqueda
Enviado a la API de integraciones (como una llamada 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" }}] |
Referencia de API
| Atributo | Tipo | Descripción |
| ID | Cadena |
El identificador único del elemento. Necesario |
| título | Cadena |
El nombre del elemento. Necesario |
| descripción | Cadena |
La descripción/resumen del elemento. Si se rellena, el título del resultado de la búsqueda se mostrará en negrita, mientras que la descripción se mostrará debajo. Opcional |
| enlace | URL |
La URL para acceder al elemento una vez haciendo clic en el resultado de la búsqueda. Necesario |
| mimeType | Cadena |
La categoría de filtro en la que se debe mostrar el elemento. Debe ser una coincidencia exacta de una de las siguientes opciones que aparecen en esta lista:
Necesario |
| externalType | Cadena |
El tipo de elemento. Por ejemplo: Artículo, Panel, Caso, etc. Si se rellena, se mostrará en el elemento junto al nombre de la integración. Opcional |
| creado | Fecha y hora |
Se creó el elemento de fecha y hora. Este parámetro no se muestra en la interfaz de usuario, pero se utiliza para fines de clasificación. Opcional |
| modificado | Fecha y hora |
El elemento de fecha y hora se actualizó recientemente. Este parámetro no se muestra en la interfaz de usuario, pero se utiliza para fines de clasificación. Opcional |
| copiar | Cadena |
Si se rellena, se mostrará un botón de copia en el resultado de la búsqueda. Al hacer clic en ese botón, copiará el texto proporcionado (enlace del elemento, nombre, ID, etc.). Por lo general, se rellena con el enlace del elemento. Opcional |
| confianza | Decimal |
Parámetro que se debe utilizar para mostrar la precisión de la respuesta (en porcentaje). Si se rellena, se mostrará en la interfaz de usuario de los resultados de la búsqueda. Opcional |
| fuente | Cadena |
Muestra el origen de la respuesta (por ejemplo: Confluence). Se mostrará en la interfaz de usuario de los resultados de la búsqueda junto a un icono de lupa. Opcional |
| categoría | Cadena |
Parámetro que debe utilizar Ask-AI, para mostrar la categoría del artículo ("breadcrumbs"). Si se rellena, se mostrará en la interfaz de usuario de los resultados de la búsqueda encima del título. Opcional |
| poweredBy | Cadena |
Si se rellena, se mostrará una nota en la interfaz de usuario de los resultados de la búsqueda en la parte inferior derecha. Ten en cuenta que cuando se rellena, el nombre y el icono de la integración no se mostrarán en el resultado. Opcional |
| detalle | Cadena |
Si se rellenan, estos datos se mostrarán en la interfaz de usuario de los resultados de búsqueda (después del nombre de la integración y externalType). Opcional |
| Tiempo relacional | Fecha y hora |
Si se rellenan, estos datos se mostrarán en la interfaz de usuario de los resultados de la búsqueda, al final de la misma. Mostrará un tiempo relacional según la fecha proporcionada frente a la hora actual (por ejemplo, hace 3 días). Opcional |
Restricciones
Los campos de cadena están restringidos a 255 caracteres.
Parámetros: Diseño de interfaz de usuario
Manejo de errores
Aunque en la mayoría de los casos el flujo dará lugar a una respuesta "HTTP 200" con un mensaje de texto plano "ok" que indica que los resultados de búsqueda se mostraron correctamente, deberemos prepararnos para escenarios en los que los intentos de enviar resultados de búsqueda fallarán.
Los errores que aparecen en esta sección se generan en el lado de la API de Integraciones y deben indicar con la mayor precisión posible la causa del error.
La respuesta de la API puede generar errores ("HTTP 400") al recibir solicitudes con errores de formato, cuando se utilizan claves que ya no son válidas o cuando algo verdaderamente excepcional evita que pase a los resultados de búsqueda.
|
Error |
Descripción |
| invalid_structure | Por lo general, indica que la solicitud recibida está mal formada: tal vez el JSON esté estructurado incorrectamente o el texto del mensaje no esté correctamente filtrado. La solicitud no se debe volver a intentar sin corregirla. |
| api_key_invalid | Indica que la clave API que se está abordando no existe o es inválida. La solicitud no se debe volver a intentar sin modificar la clave API. |
| api_url_invalid | Indica que la URL de la API que se está abordando no es válida. La solicitud no se debe volver a intentar sin modificar la URL de la API. |
| title_invalid | Indica que el título, que es un valor obligatorio, no se envió o no está dentro de las restricciones de caracteres. |
| link_invalid | Indica que el enlace, que es un valor obligatorio, no se envió o no está dentro de las restricciones de caracteres. |
| mimeType_invalid | Indica que el mimeType, que es un valor obligatorio, no se envió o no está dentro de las restricciones de caracteres. |
| id_invalid | Indica que el ID, que es un valor obligatorio, no se envió o no está dentro de las restricciones de caracteres. |
Descripción general de la seguridad
La búsqueda empresarial utiliza integraciones de terceros para implementar una "búsqueda federal". Las búsquedas dentro del menú de escritorio están respaldadas por un motor de Procesamiento de Lenguaje Natural (NLP) y una base de datos de gráficos que admite una excelente experiencia de usuario.
El menú de escritorio de Búsqueda empresarial no indexa datos de terceros en una base de datos que se pueda buscar de forma independiente.
El siguiente diagrama de secuencia describe el algoritmo de búsqueda:
Notas técnicas
Para garantizar que la integración del menú de escritorio de ServiceNow funcione correctamente, los clientes deben incluir en la lista de permitidos las siguientes IP:
- QA: 54.229.168.224
- PROD: 52.53.115.147.
- EUPROD: 3.126.219.141