Adición de búsquedas
Las búsquedas son mecanismos de solo lectura que consultan el servicio para obtener una lista de valores que aparecen como una lista desplegable. Las búsquedas pueden basarse en otros elementos de información que ya se han proporcionado en el formulario. La utilización de búsquedas elimina la necesidad de introducir manualmente o recordar los valores asociados a los recursos de la cuenta de terceros, al configurar una acción o un activador.
Las búsquedas se utilizan en acciones y activadores. Para mostrar muchos elementos, las búsquedas utilizan un mecanismo de paginación.
Las búsquedas soportan el filtrado inicial de datos. Por ejemplo, al escribir texto en el campo de búsqueda y pulsar en la flecha, aparece una lista de valores que contienen el texto.
A diferencia de otros elementos, las búsquedas no tienen versiones externas. Cada llamada de búsqueda es una función en el elemento de búsqueda. Como resultado, hay un solo elemento de búsqueda por conector.
Por ejemplo, hay una acción de búsqueda en la siguiente figura. La búsqueda extrae el correo electrónico de Gmail del usuario y estos valores aparecen en ID de mensaje como entrada. Esto es posible porque el esquema especifica que se puede utilizar una búsqueda para este campo.
Para implementar la acción get-mail-details, se necesita el ID de la cuenta de correo electrónico. En el script de búsqueda se utiliza la autenticación de la cuenta de Gmail para buscar todos los correos electrónicos de la cuenta. A continuación, aparece la lista en el formulario de la acción y se puede seleccionar el ID adecuado como una búsqueda.
Para crear una nueva búsqueda, realice lo siguiente:
1. En el símbolo del sistema, ejecute los siguientes comandos:
a. cd <user project root directory>
b. flow add lookup
El nombre de la búsqueda es el nombre del conector y se crea en la carpeta de búsquedas del directorio del proyecto.
Las siguientes opciones están disponibles para el comando.
Opciones | Descripción | Tipo de datos |
|---|---|---|
--version | Permite mostrar el número de versión. | [booleano] |
--help | Permite mostrar la ayuda. | [booleano] |
--parentDir, -d | El directorio padre del proyecto. | [por defecto: "."] |
--logLevel, -1 | Permite definir el nivel de registro. | [por defecto: "info"] |
2. Actualice las propiedades en el fichero index.js.
Un objeto JavaScript de búsqueda debe exportar un único objeto JavaScript. El objeto puede contener cualquier número de métodos. El fichero index.js tiene la siguiente estructura.
function(input, options, output){
return}
return}
 | El código puede ser diferente si el servicio externo utiliza una conexión en lugar de OAuth. |
El objeto de opciones proporciona varios métodos de utilidad que son necesarios para usarlos en búsquedas.
validateDependencies(input.<property name>): permite verificar que la entrada contiene la propiedad especificada.
options.getAccessToken(input.auth, function(err, data) { }): Fetch the access token from the server. input.auth contains a UID that is used to fetch the access token. options.getConnection(input.connection, function(err, data){ }) : Fetch the connection corresponding to the UID contained in the connection property.
Para obtener información sobre un SDK de las API que se pueden utilizar en búsquedas, consulte la sección SDK de conectores de ThingWorx Flow.
En la siguiente tabla se describe cómo se utilizan los argumentos.
Argumento | Uso |
|---|---|
input | Contiene las dependencias configuradas en la búsqueda. |
options | Permite proporcionar métodos de utilidad para extraer el mecanismo de autenticación, token de acceso o conexión, y activar el soporte de paginación. |
output | Llamada que se debe invocar para devolver los resultados a ThingWorx Flow. Sigue la convención de "error primero" del nodo. El resultado debe ser una matriz de objetos JSON. Normalmente, son pares de ID y valor. Es posible añadir campos adicionales si se añade el esquema dinámico. Para obtener más información, consulte la sección sobre la inyección de esquemas dinámicos. El resultado se debe pasar a la llamada (función de salida) y tiene que ser una matriz de objetos JSON que contengan el ID y el valor. Los resultados deben tener el siguiente formato: { [ {"id":"id1","value":"value1"}, {"id":"id2","value":"value2"}, ], “next_page”: true } |
Para obtener un ejemplo de la adición de búsquedas, consulte el Tutorial B.
Inyección de esquema dinámico
Si hay un esquema fijo de entrada y salida para una acción, se crea una limitación al generar acciones con abundante funcionalidad. El esquema de entrada y salida para una acción se puede actualizar en función de las elecciones del usuario al cargar una búsqueda o al seleccionar un valor de la búsqueda. Por consiguiente, el formulario se actualiza para que coincida con el esquema de entrada actualizado que conserva los valores actuales. Además, los campos de salida disponibles para la asignación en la siguiente acción se actualizan para que coincidan con el esquema de salida actualizado.
Las actualizaciones en el esquema de entrada y salida para una acción se pueden realizar en la interfaz de procesamiento del resultado de la búsqueda.
Se puede inyectar el esquema dinámico mientras se devuelven los resultados de la búsqueda o se puede añadir otra función a la búsqueda a través del atributo onSelect (para la opción seleccionada). Cuando se inyecta en el momento de la carga de la búsqueda, la inyección de esquema dinámico necesita el esquema para todos los valores de búsqueda.
| | Para algunas cosas, es posible realizar una inyección multinivel, mediante dos búsquedas consecutivas. La inyección multinivel puede incorporar con restricciones, pero no puede quitar. |
La forma de añadir el esquema de entrada que muestra el formulario es utilizar los atributos schema, parent y append en el resultado JSON para la búsqueda junto al ID y value. De manera similar, utilice outSchema, outAppend y outParent para añadir el esquema de salida, que aparece como el esquema de salida de la acción cuando se abre la acción conectada. Normalmente, append u outAppend y parent u outParent se utilizan juntos al incorporar el esquema proporcionado al padre indicado a fin de ampliar las propiedades. Si no se utiliza append, el esquema se reemplaza por el esquema recién añadido.
El atributo parent u outParent es el ID del elemento de esquema (debe ser del tipo object) del esquema respectivo. En ausencia de los atributos parent u outParent, el contexto por defecto para la actualización es la raíz del esquema respectivo. La actualización del esquema tiene lugar en el ámbito de los objetos parent u outParent, mediante la combinación o reemplazo en ausencia de append/outAppend de las propiedades que se proporcionan en el esquema de inyección con las propiedades existentes.
También se puede utilizar el atributo userSelected en el esquema de salida que se inyecta. Se utiliza para inyectar un esquema por defecto con el valor false y reemplazarlo por un subconjunto, valor true, cuando se seleccionan opciones en el formulario. Si se quitan todos los atributos userSelected = true cuando se borra un elemento de matriz del formulario, el esquema revierte al valor por defecto.
Por ejemplo, para el conector de OData, defina el esquema de inyección de entrada y salida, tal como se muestra en la siguiente figura:
El esquema de inyección de entrada para OData es el siguiente:
"schema": {
"Properties": {
"type": "object",
"title": "Properties",
"properties": {
"AirlineCode": {
"type": "string",
"title": "AirlineCode",
"minLength": 1
},
"Name": {
"type": "string",
"title": "Name",
"minLength": 1
}
}
}
}
"Properties": {
"type": "object",
"title": "Properties",
"properties": {
"AirlineCode": {
"type": "string",
"title": "AirlineCode",
"minLength": 1
},
"Name": {
"type": "string",
"title": "Name",
"minLength": 1
}
}
}
}
El esquema de inyección de salida para OData es el siguiente:
"outSchema": {
"properties": {
"Airlines": {
"type": "array",
"title": "Airlines",
"displayTitle": "Airlines",
"items": {
"type": "object",
"properties": {
"AirlineCode": {
"title": "AirlineCode",
"type": "string",
"userSelected": false
},
"Name": {
"title": "Name",
"type": "string",
"userSelected": false,
"visible": true
}
}
}
}
}
}
"properties": {
"Airlines": {
"type": "array",
"title": "Airlines",
"displayTitle": "Airlines",
"items": {
"type": "object",
"properties": {
"AirlineCode": {
"title": "AirlineCode",
"type": "string",
"userSelected": false
},
"Name": {
"title": "Name",
"type": "string",
"userSelected": false,
"visible": true
}
}
}
}
}
}
Como se sugiere en el ejemplo anterior, se pueden fijar algunos parámetros en la interfaz de usuario de asignación en el esquema de salida inyectado dinámicamente mediante la definición de la siguiente propiedad: visible = true.
Para internacionalizar el esquema dinámico de entrada y salida, consulte la sección Soporte de internacionalización para conectores.
Paginación
Las búsquedas soportan la paginación, es decir, la capacidad de producir muchas páginas de resultados. Cada invocación produce una sola página de resultados. En la interfaz de usuario, se puede recuperar la página pulsando en "Más resultados" de la lista. Los objetos de entrada y opciones contienen métodos y propiedades para gestionar la paginación.
• options.getNextPage(boolean): se utiliza en la paginación para devolver el URL y extraer la página siguiente. Este URL se debe definir en la propiedad "next_page" del objeto de resultados para que la paginación funcione correctamente. Si no se deben devolver más páginas, defina esta propiedad en falso.
• options.maxResults: se utiliza con la paginación para obtener el número máximo de resultados que se devuelven a la vez.
• input.page: el número de página actual.
• input.searchById: permite buscar por ID.
• input.searchByValue: permite buscar por valor.
Las búsquedas por ID y valor están disponibles si la búsqueda tiene el señalizador de válido para búsquedas definido en verdadero. Para ver un ejemplo de búsqueda, consulte las secciones anteriores. Estas propiedades ayudan a reducir la búsqueda al buscar en el sistema de destino los elementos que coinciden con el ID o el valor.
| | El ID y el valor pueden hacer referencia a distintos campos del sistema de destino. |