Conexión de datos de la API de REST - Automate_Evolve - Automate_Studio_Manager - Latest

Guía del usuario de Automate Evolve

Product type
Software
Portfolio
Integrate
Product family
Product
Automate > Automate Studio Manager
Automate > Automate Evolve
Version
Latest
Language
Español (España)
Product name
Automate Evolve
Title
Guía del usuario de Automate Evolve
Copyright
2024
First publish date
2018
ft:lastEdition
2024-05-23
ft:lastPublication
2024-05-23T16:32:48.544670

Paso 1: Crear una conexión de API de REST en el ámbito global o de la aplicación

  1. Vaya a Conexiones → Orígenes de datos en el nivel global o de la aplicación.

  2. Defina una nueva conexión de API de REST.

  3. Proporcione la URL base de la API y los detalles de autenticación. Para obtener más información, consulte Crear conexiones de bases de datos.

Paso 2: Crear una conexión de datos de la solución

Siga estos pasos para configurar la conexión de datos según la operación que se requiera (Crear, Leer, Actualizar o Eliminar) y según los datos necesarios del sistema de la API.

  1. Cree una solución de formularios nueva o abra una existente y haga clic en Añadir conexión de datos en el menú de cinta de la solución.

  2. Indique un nombre y seleccione el tipo API de REST. Esto mostrará todos los orígenes de datos del tipo «API de REST» que existan en el ámbito de la aplicación actual o en el ámbito global.

  3. Establezca la URL de API o el extremo de la API de REST:

    1. De forma predeterminada, se muestra la URL base de API, tal y como se ha definido al crear la conexión de datos. Configure esta URL según los requisitos para obtener datos de un extremo específico.

    2. Haga clic en los tres puntos para abrir el generador de URL y añadir las partes de la URL.

    3. En el cuadro de diálogo del generador de URL, añada la URL necesaria para la conexión de datos de esta solución. Puede ser un valor fijo o un valor de campo de formulario o ambas cosas. A continuación, se muestra un ejemplo de cómo obtener detalles específicos del producto de la API de SAP HANA.

      1. URL base definida en la conexión: https://sandbox.api.sap.com/s4hanacloud/sap/opu/odata/sap

      2. Primera parte de la URL para especificar el acceso a la API del producto: /API_PRODUCT_SRV/A_Product/

      3. Segunda parte de la URL para especificar el número de producto de un campo de formulario: ('[/my:myFields/my:Search_Product_Id]') NOTA: Este valor corresponde a la especificación de la API de SAP HANA, es decir, ('<<Product Number>>')

      4. La URL final tendrá el siguiente aspecto:

        https://sandbox.api.sap.com/s4hanacloud/sap/opu/odata/sap/API_PRODUCT_SRV/A_Product/('[/my:myFields/my:Search_Product_Id]')

    El retroceso a la URL de la API definida en la biblioteca de conexiones de datos funciona si no hay una URL de API definida con control (Búsqueda/Consulta/Menú desplegable)

    Si la URL de la API se cambia en la biblioteca de conexiones de datos, también se refleja en la solución en tiempo de ejecución.

    La conexión de datos añadida desde la biblioteca de conexiones de datos no se puede editar a nivel de conexión de datos de la solución. El usuario solo puede editar la URL de la API desde la propiedad de filtro (cláusula Where sin procesar) del control de Búsqueda/Consulta/Menú desplegable.

    Se seguirá la siguiente prioridad:

    • Para conexión de la biblioteca de conexiones de datos

      • La URL de la API definida en el control de Consulta/Búsqueda se respetará primero.

      • Si no se ha definido ninguna URL de API en Consulta/Búsqueda, retrocederá a la URL de API definida a nivel de biblioteca de conexiones de datos.

    • Para la conexión de la solución

      • La URL de la API definida en el control de Consulta/Búsqueda se respetará primero.

      • Si no se ha definido ninguna URL de API en Consulta/Búsqueda, retrocederá a la URL de API definida a nivel de conexión de la solución.

  4. Operaciones de HTTP: La API de REST utiliza el verbo HTTP para especificar que la solicitud es para leer, actualizar, eliminar o crear. Seleccione este campo según el uso actual de la conexión de API. Las operaciones admitidas son las siguientes:

    1. GET: Para obtener datos de la API.

    2. PUT/PATCH: Para actualizar datos.

    3. POST: Para crear datos.

    4. DELETE: Para eliminar datos.

      Nota:
      • Seleccione la operación anterior según la especificación de API del sistema, ya que algunos sistemas pueden no seguir el verbo HTTP estándar, es decir, la operación POST podría consistir en la eliminación de los datos.

      • Complemento del adaptador de conexión de datos: el nodo de ejecutor es compatible con la conexión de datos de la API de REST.

  5. Establezca el esquema de API:

    1. Esquema de entrada: El esquema de entrada es para los datos que se enviarán a la API (por ejemplo, carga útil de solicitud en JSON). Indique el esquema JSON desde un archivo o cópielo directamente en el campo de texto.

    2. Esquema de salida: El esquema de salida es para los datos que se recibirán de la API (por ejemplo, carga útil de respuesta en JSON). Indique el esquema JSON desde un archivo o cópielo directamente en el campo de texto.

      Para obtener más información, consulte los pasos para actualizar el esquema de entrada/salida para la conexión de la API de REST.

    3. Esquema de error: En caso de error o excepción, algunos datos de retorno de API en diferentes esquemas JSON, por ejemplo, el código de estado HTTP (4xxx o 5xxx) se consideran como un error/excepción en la llamada a la API. Indique el esquema JSON desde un archivo o cópielo directamente en el campo de texto.

    4. Encabezado de solicitud: Son los datos de encabezado en formato de pares clave-valor. El encabezado de solicitud es la información que se enviará a la API en la sección de encabezados de solicitud. Indique los encabezados de solicitud esperados según la especificación de API. Además, tanto la clave como el valor pueden configurarse para que se lean desde campos de formulario, desde un valor fijo o desde ambos.

      Ejemplo: Si la autorización del encabezado de la solicitud se establece con el valor – bearer [FormFieldName], en el tiempo de ejecución, si el valor de FormFieldName es 1234, el valor de autorización del encabezado de solicitud será - bearer 1234

      Aquí bearer es un valor fijo y FormFieldName es un campo de formulario.

    5. Encabezado de respuesta: Son los datos de encabezado en formato de pares clave-valor. El encabezado de respuesta es la información que se recibirá de la API como respuesta en la sección de encabezados. Indique los encabezados de solicitud esperados según la especificación de API. El nombre de la clave debe ser un valor fijo/estático proporcionado en el momento del diseño de la solución. El valor será un campo de formulario y dicho campo de formulario se actualizará con el valor según los datos recibidos de la API. Los encabezados de respuesta solo funcionarán con la ejecución del servicio web (control de servicio web o adaptador de conexión de datos).

      Nota sobre los encabezados de solicitud

      A continuación, se describen los detalles de compatibilidad del encabezado por medio del campo de formulario:

      1. Conexión de datos asíncrona: No está marcada la opción Recuperar datos automáticamente al abrir un formulario. Esto no se admite.

      2. Conexión de datos síncrona: Está marcada la opción Recuperar datos automáticamente al abrir un formulario. Solo se admite para los campos de no repetición.

      Nota:
      • Si la conexión de datos de la API de REST (síncrona/asíncrona) se usa en el menú desplegable con el filtro definido y el usuario cambia la conexión de datos, aparece un mensaje de advertencia. Según la selección, el modo de conexión de datos cambia y los filtros se borran. Se abre el cuadro de diálogo de filtro respectivo (filtro de sincronización o filtro de URL de API de REST) donde se consume la conexión de datos de la API de REST.

      • No se muestra ningún mensaje de advertencia si se utiliza la conexión de datos de la API de REST en el menú desplegable sin ningún filtro definido.

      Tipo de datos de campo Carga útil JSON:

      La aplicación puede determinar el tipo de datos de los campos JSON si el esquema JSON especificado en el esquema de Entrada/Salida/Error ha especificado el nombre del Tipo de datos en el valor. Por ejemplo, para especificar el campo CityName como tipo de cadena: {“CityName”:”string”} o para especificar el campo CreatedOn como un Tipo de fecha: {“CreatedOn”:”date”}. A continuación se muestra la tabla de asignación de tipos de campo como referencia:

      Tipo de datos Tipo de campo
      int, bigint Para campos numéricos.
      cadena Para cadenas o campos de texto.
      decimal Para campos decimales.
      bit, bool, true Para campos booleanos.
      date, datetime Para campos de fecha.

      Si no se especifica el tipo de datos, la aplicación intenta predecirlo basándose en el valor indicado. Valor numérico a int (es decir, 0 o 12, etc.), valor decimal a doble (es decir, 12,4 o 9,1, también 0,0 se considerará como int), valor de fecha a fecha. Se recomienda especificar el tipo de datos para obtener resultados más definidos.

      Compatibilidad con matrices

      También se admiten propiedades de tipo matriz. A continuación, se muestra un ejemplo de propiedad de tipo matriz y su notación de tipo de datos. Para las propiedades de tipo matriz, el esquema del formulario se genera como tabla de una sola columna (es decir, sección de repetición con un único campo de formulario)

      [{ "id": "int", "name": "string", "productType": "string", "sizes": ["string"], "otherDetails": { "colors": ["string"], "versions": ["int"] }}]

      Error de coincidencia de tipos fecha al generar campos

      El campo de la API indicado en la carga útil no coincide con el tipo de campo del formulario (principalmente en el caso de fechas y números), es decir, el tipo de campo de la API es una cadena, pero se asigna a un campo de formulario de tipo fecha o viceversa. En estos casos, la conversación de datos puede no ser correcta, ya que la aplicación considerará que los datos recibidos del servidor de API son una cadena, pero el formulario los tratará como una fecha, por lo que pueden producirse errores de coincidencia de datos o errores desconocidos.

      La carga útil JSON proporcionada se procesa distinguiendo entre mayúsculas y minúsculas, y todos los nombres de clave proporcionados se procesan con las mismas mayúsculas y minúsculas que se especifican. Por ejemplo, la aplicación “id”:“int” buscará la clave con las minúsculas del nombre exacto “id” y no podrá procesarse si los datos recibidos son “Id”, “ID”, etc.

    6. Guarde la conexión y aparecerá en Conexiones de datos de la solución.

Edición de una conexión de datos (API de REST):

Si la conexión de datos se está utilizando, solo se podrán editar las siguientes propiedades.

  • URL

  • Encabezados de solicitud/respuesta

Paso 3: Asignación de la conexión de datos de la solución de API con los campos de formulario

Este paso sirve para asignar los campos de datos de la conexión de datos de la solución de API a los campos de formulario. Es igual que la asignación de los campos de la conexión de servicio web o de datos de referencia con los campos de formulario.

A continuación, se indican los pasos para asignar la conexión de datos de la solución de API con los campos de formulario:

  1. Haga clic con el botón secundario en la conexión de datos de la solución y elija la opción Crear campos de formulario.

  2. En el cuadro de diálogo Asignación de campos, indique la siguiente información:

    1. Descripción: Nota de texto para esta asignación.

    2. Nombre de grupo: Nombre del grupo para los campos del esquema del formulario. Todos los campos de formulario se crearán únicamente en este grupo.

    3. Nombre de servicio web: Nombre de asignación que se utilizará en el control de formulario o en los complementos.

    4. Haga clic en Siguiente en este cuadro de diálogo.

  3. El cuadro de diálogo Parámetros de asignación de campos mostrará todos los campos de la conexión de datos de la solución de API y los campos de formulario, de manera similar a lo que se muestra en el cuadro de diálogo Asignación de campos de servicio web.

  4. Revise o cambie el tipo de campo de formulario o la longitud máxima según los requisitos.

  5. Haga clic en Aceptar para finalizar la asignación.

La asignación de cualquier campo de esquema con un tipo diferente de campo de formulario debe realizarse en el diálogo Asignación de campos. El cambio del Tipo de campo de formulario desde Propiedades no cambiaría el Tipo de datos en WSDL.

Por ejemplo:

En el caso de un método GET API, hay un Campo de fecha en el esquema de salida y su Tipo de datos es una cadena. El usuario debe seleccionar Tipo de fecha en el cuadro de diálogo Asignación de campos.

Nota: La asignación del selector de fecha al campo de texto y el cambio posterior del Tipo a la Fecha en las Propiedades del campo no mostrará los resultados esperados.

Paso 4: Diseño del formulario

Diseñe el formulario con los campos creados y asignados a la conexión de datos de la solución de API. Coloque también los controles de formulario (por ejemplo, servicio web, búsqueda, consulta o lista desplegable) que ejecutarán la conexión de datos de la API.

  1. Diseñe los campos de formulario en la vista de formulario.

  2. Coloque el control de servicio web y de botón en la vista de formulario. Configure el control de servicio web y el control de botón para ejecutar la conexión de datos de la solución de API al hacer clic en ese botón.

  3. Implementar la solución.

Nota: La conexión de datos de la solución de API tendrá el mismo diseño que las demás conexiones de datos y podrá utilizarse con los controles de formulario y los complementos compatibles.

Paso 5: Probar la conexión de datos de la solución de API

Inicie el formulario y ejecute la conexión de datos de la solución de API.

  1. Inicie el formulario.

  2. Haga clic en el botón configurado para ejecutar la conexión de datos de la solución de API.

  3. El formulario ejecutará la API y mostrará los datos de respuesta en los campos de formulario asignados.

    Al usar la función Conexión de datos en la solución de formularios para descargar los datos en el Formulario de Evolve, puede:

    • Descargar los datos sobre las acciones del usuario en el Formulario.
    • Descargar los datos en segundo plano utilizando el complemento Adaptador de conexión de datos.

    Se recomienda diseñar una solución que no descargue un gran volumen (más de 1000 registros) de datos en el formulario. Guardar un volumen tan alto de datos en el formulario puede provocar un elevado uso de recursos de RAM o CPU. Esto puede afectar otras funciones de la aplicación, y provocar una respuesta lenta o un retraso en el procesamiento de las tareas.

    Por ejemplo, en los Campos de formulario, el parámetro de entrada para la consulta debe establecerse de manera que la consulta nunca devuelva más de 1000 registros. Para ello, puede hacer que el parámetro de entrada sea obligatorio. Si está utilizando una API de REST y dicha API admite la devolución del número máximo de registros para cualquier consulta o filtro (como la API OData, que generalmente tiene los parámetros count o $count), dicho parámetro debe establecerse con algún valor límite (menos de 1000) en el momento del diseño de la solución. De esta forma, si el usuario final del formulario proporciona involuntariamente un filtro o una entrada incorrectos, no devolverá miles de registros.

Ejemplo de API que devuelve productos

Especificación de API

La API con el extremo «http://globalsystem/api/Product» devuelve productos en formato JSON utilizando el verbo HTTP o la operación GET. Se puede acceder a la API con el código de clave proporcionado, que debe enviarse por medio del encabezado de solicitud en el nombre de clave accesskey. El extremo de URL de API tiene una dirección base para todas las API y también una parte de URL específica para devolver productos. es decir, la parte de la URL base es: “http://globalsystem/api” y la parte de la URL del producto es “/Product”. Esta API devuelve uno o más productos. A continuación, encontrará un ejemplo:

Respuesta de API que muestra los detalles de dos productos. Es una matriz de JSON.

[  { "id": 1, "name": "100-100", "productType": "A1", "weightUnit": "W1", "netWeight": 90, "grossWeight": 100, "validityStartDate": "2020-10-03T10:28:45.892275+05:30" }, { "id": 2, "name": "100-200", "productType": "A1", "weightUnit": "W1", "netWeight": 100, "grossWeight": 150, "validityStartDate": "2019-08-30T10:28:46.3904638+05:30" } ]

Paso 1:

  1. Añada una conexión nueva, ya sea en el nivel de la aplicación o en el nivel global, con la URL base: “http://globalsystem/api” y con el tipo de autenticación como encabezado HTTP, es decir, añada un encabezado con el nombre de clave accesskey y el valor debe ser la clave de acceso válida recibida del sistema. Indique el nombre de la conexión como «GlobalSystemAPI».

Paso 2:

  1. Cree una solución nueva y añada una conexión de datos de API de REST con el nombre de conexión «GlobalSystemAPI», tal como se ha creado en el paso 1.

  2. Establezca el nombre de la conexión de datos en «conProductGlobalSystem».

  3. Establezca la URL de API como API de producto añadiendo la parte de la URL «/Product» mediante el generador de URL.

  4. Establezca la operación GET.

  5. No es necesario establecer ningún esquema de entrada, ya que la API no espera ninguna carga útil.

  6. Establezca el esquema de salida de un solo producto, ya que la conexión solo necesita el esquema y no la salida exacta con los datos de varios productos. Establezca el tipo de campo (tipo de datos), que se espera que sea un campo de formulario de Composer. Hay dos maneras de añadir los detalles del esquema a la API. Guarde este esquema en un archivo y después navegue al archivo o indique el esquema directamente como texto. A continuación, se muestra un ejemplo de esquema (matriz de productos).

    Ejemplo de esquema

    [ { "id": “int”, "name": "string", "productType": "string", "weightUnit": "string", "netWeight": “decimal”, "grossWeight": “decimal”, "validityStartDate": "date" } ]
    Nota: El esquema anterior es una matriz de datos que se devolverá como respuesta de la API. Asimismo, es una especificación de formato JSON estándar. También especifica cada tipo de campo que utilizará Composer al crear los campos de formulario.
    Nota: Si el valor de una clave concreta en el esquema anterior espera que se devuelvan varios valores (una matriz de valores separados por comas), ello también puede gestionarse y los tipos de datos existentes serán suficientes para ese propósito. Un ejemplo de valor de matriz recibido como respuesta para una «clave» en el esquema podría ser: [«valor_1», «valor_2», «valor_3»], lo que puede considerarse como datos de tipo «cadena».
  7. Guarde la conexión.

Paso 3: Asignación de la conexión de API con campos de formulario

  1. Haga clic con el botón secundario en la conexión creada anteriormente «conProductGlobalSystem» en el árbol de soluciones y elija «Crear campos de formulario». Asigne a esta asignación o servicio web el nombre «ProductGlobalSystemWS» y siga los pasos para crear los campos de formulario.

Paso 4: Diseño del formulario

  1. Coloque los campos de formulario creados en el paso 3 en una vista de formulario.

  2. Añada un control de botón y etiquételo con «Obtener productos».

  3. Añada un control de servicio web y seleccione el nombre de la asignación o el servicio web «ProductGlobalSystemWS». Configúrelo para que se ejecute al «invocar el botón» y seleccione el botón añadido anteriormente.

  4. Implementar la solución.

Nota:

  • La solicitud de URL desde el campo de solución no se admite directamente en las plantillas de formulario. El usuario debe crear un borrador o una tarea para usarlo.

  • En el caso de Controles de formulario como Consulta, Búsqueda, Menú desplegable o PR, solo estará disponible la sección más externa del esquema. Por lo tanto, las conexiones de datos mostrarán solo el conjunto de campos más externo como columnas.

Paso 5: Prueba de la conexión de API de REST

  1. Inicie la plantilla de formulario y haga clic en el botón Obtener productos. Obtendrá todos los productos y el resultado debería verse en una tabla.

Manejo de fecha y hora en la integración de API de REST:

Operación POST/PATCH/PUT

Caso 1 A>Fecha de registro mediante el control de selector de fecha

Cuando se utiliza el control Selector de fecha, el usuario debe introducir la fecha en el formato establecido en el control Selector de fecha, con independencia del formato de fecha (ISO/tics) establecido en la API de Rest DC

Caso 1 B>Parte de la hora en el control de selector de fecha

La parte de tiempo se pierde al realizar la contabilización usando el control Selector de fecha.

Caso 2 A>Fecha de contabilización mediante campo de texto

Cuando se utiliza el Campo de texto, por ejemplo, el esquema tiene un campo de fecha, pero en la ventana de asignación de campos Crear, el campo de fecha está asignado al tipo Campo de texto. Aquí debe establecerse el formato correcto aceptado por la API.

• Para tics: el usuario debe introducir el valor en formato de tics. Ejemplo: /Date(1595808000000)/ .

• Para ISO: el usuario debe introducir la fecha según el formato ISO. Ejemplo: aaaa-mm-dd.

Caso 2 B>La parte de la hora y la zona horaria utilizan un campo de texto

Al utilizar el Campo de texto, la parte de la hora no se perderá. También se respetará la zona horaria, si se proporciona el valor de la fecha junto con el desplazamiento. Ejemplo: si proporciona un valor como 2021-03-31T01:01:13.8366463+05:30, se contabilizará la fecha en el sistema junto con la zona horaria.

Operación GET

Caso 1 A> Obtención de fecha en el control de selector de fecha

En este caso, la fecha se establecerá según el formato de Selector de fecha, sin importar el formato de fecha (tics/ISO) establecido en la conexión de datos de la API de Rest.

Caso 1 B> Parte de la hora y zona horaria

La parte de la hora se perderá. La fecha se devolverá siempre en formato UTC.

Caso 2 A>Obtención de fecha en el campo de texto

En este caso, la fecha se establecerá según el Formato de fecha de la conexión de datos de la API de Rest. Ejemplo: para tics, la fecha se establecerá como /Date(1595808000000)/ y para ISO, la fecha se establecerá como aaaa-mm-dd hh:mm:ss.

Caso 2 B->La parte de la hora y la zona horaria utilizan un campo de texto

La fecha se devolverá siempre en formato de la zona horaria UTC.

Ejemplo: si la fecha se ha publicado como 2021-03-31T00:00:00.0000000+05:30 (zona horaria de la India), en la operación GET, la fecha se devolverá como 2021-03-30 (es decir, la zona horaria UTC)