[InterSystems IRIS por primera vez] Interoperabilidad: Crear componentes (Business Operations)

Este artículo es una continuación de esta publicación.

En ese artículo revisamos cómo crear y definir mensajes que se utilizan para enviar y recibir datos entre componentes.

En este artículo, explicaré cómo crear una business operation a partir de los métodos para crear componentes.

• Producción
• Mensaje（artículo anterior）
• Componentes
  • Business Services
  • Business Processes
  • Business Operations

Revisaremos rápidamente el código al referirnos a la muestra.。

Nota: BS significa "Business Service", BP significa "Business Process" y BO significa "Business Operation".

Hay que escribir ObjectScript en Business Services y Business Operations y se pueden crear en VSCode o en Studio. Los Business Processes también se pueden llevar a cabo en el Portal de Administración.

No hay un orden particular para crearlos, pero el sitio externo al que se conectará es un sitio público y puede utilizarse inmediatamente en este ejemplo. En este caso, es conveniente comenzar con la business operation para que las pruebas sean más fáciles.

Después de crear los componentes, hay una página de prueba en la producción para los business processes y las business operations. Sin embargo, las pruebas están desactivadas de forma predeterminada en la definición de la producción, para evitar pruebas aleatorias en el entorno de producción.

Para saber más sobre cómo permitir las "Pruebas activadas" en la producción, utiliza la siguiente configuración (la producción de muestra se ha configurado como "Pruebas activadas" de forma anticipada):

1)　Business Operations

En el ejemplo, aparecen dos tipos de business operations.

Una de las operaciones consiste en transmitir el nombre de la ciudad a una API web externa mediante REST y solicitar que se obtenga la información meteorológica. La otra operación consiste en dar la información meteorológica y el nombre del producto comprado a la base de datos de InterSystems IRIS y solicitar el proceso actualizado.

1)-1 Business Operations de REST

Comencemos creando una operación que llame a una API web externa por medio de REST.

Esta operación inicia el método GetKion() cuando se introduce un mensaje Start.Request, consulta a un sitio externo y devuelve la información meteorológica en un mensaje Start.Response.

Consulta aquí los detalles del código.

Para crear una business operation para REST, deberá heredarla de EnsLib.REST.Operation.

Class Start.GetKionOperation Extends EnsLib.REST.Operation

La herencia de esta clase ofrece los siguientes métodos en IRIS que coinciden con los métodos de HTTP. Consulta la documentación para obtener más información.

• GetURL(): se utiliza para las operaciones GET de HTTP.
• PostURL(): se utiliza en las operaciones POST de HTTP.
• PutURL(): se utiliza en las operaciones PUT de HTTP.
• DeleteURL(): se utiliza en las operaciones DELETE de HTTP.

Para REST, utiliza el adaptador EnsLib.HTTP.OutboundAdapter. Establece el nombre del adaptador en el parámetro ADAPTER y la propiedad Adapter, como se muestra en el ejemplo.

El parámetro INVOCATION configura la Fila.

Parameter ADAPTER = "EnsLib.HTTP.OutboundAdapter";

Property Adapter As EnsLib.HTTP.OutboundAdapter;

Parameter INVOCATION = "Queue";

Es necesario especificar la clave de la API OpenWeather que se obtendrá en el momento de la ejecución. Hay una forma de mostrar la configuración que varía según el entorno en la configuración de la producción.

El procedimiento es el siguiente:

1. Define las propiedades
2. Especifica el nombre de la propiedad que se creó en el parámetro SETTINGS (si hay varias propiedades, sepáralas con comas). De manera opcional, también se puede especificar una categoría (utilizando “property name: category name”).

A continuación se muestra un código de ejemplo.

/// APIキーを指定します
Property appid As %String;
/// specify lang option for OpenWeather API (default = ja = japanese)
Property lang As %String [ InitialExpression = "ja" ];

Parameter SETTINGS = "lang:OpenWeatherMap,appid:OpenWeatherMap";

La página de Configuración de la producción se muestra lo siguiente. La descripción que aparece en la línea inmediatamente anterior a la definición de la propiedad también se muestra en la página de configuración de la producción, como se muestra en la figura.

Después, revisaremos el mapa de mensajes, que es un escenario esencial para business operations.

La definición anterior permite que el método GetKion() funcione cuando se envíe el mensaje Start.Request.

En el método GetKion(), el nombre de la ciudad puede obtenerse a partir de la propiedad Area para solicitar mensajes transmitidos como información de entrada.

Estableciendo el nombre de la ciudad como parámetro de la URL publicada por la API web externa y llamándolo, se puede obtener la información meteorológica.

La configuración del servidor HTTP y de la URL se realiza en la página de Producción del Portal de Administración. Para obtener la configuración, utiliza la propiedad del Adapter que le proporciona el adaptador de salida de HTTP.

Ejemplo) para especificar una URL, utiliza ..Adapter.URL

Utiliza el método GetURL() que proporcionan las business operations de REST para llamar a un sitio externo. El primer parámetro es la URL que se ejecutará (es decir, la URL que se especifica en los parámetros requeridos como el nombre de la ciudad). El segundo parámetro es la respuesta de HTTP con parámetros transmitidos como referencia.

Como la información meteorológica se almacena en formato JSON en la respuesta HTTP, la operación se completa cuando los datos se registran en el mensaje de respuesta (=pResponse).

El nombre de la clase de los mensajes de respuesta se especifica en el segundo parámetro del método creado cuando se transmite la referencia.

Method GetKion(pRequest As Start.Request, Output pResponse As Start.Response) As %Status

Para devolver un mensaje de respuesta a la persona que lo llama, crea una instancia del mensaje de respuesta, almacénalo en la segunda variable del parámetro (pResponse), y establece la información necesaria en las propiedades.

set pResponse.AreaDescription=weatherinfo.weather.%Get(0).description
set pResponse.KionMax=weatherinfo.main."temp_max"
set pResponse.KionMin=weatherinfo.main."temp_min"
set pResponse.Area=weatherinfo.name
// this code is fit to Japan time because weatherinfo.dt is UTC
set unixEpochFormat=weatherinfo.dt+32400
set dt=$system.SQL.Functions.DATEADD("s",unixEpochFormat,"1970-01-01 00:00:00")
set pResponse.AreaPublicTime=dt

Como las respuestas HTTP de los sitios externos se devuelven en formato JSON, el flujo que podría obtenerse de la respuesta HTTP se utiliza para convertirla en un objeto dinámico que sea cómodo para llevar a cabo operaciones JSON dentro de IRIS.

set weatherinfo={}.%FromJSON(tHttpResponse.Data)

El siguiente es un ejemplo de una cadena JSON de respuesta:

{
    "coord": {
        "lon": 135.5022,
        "lat": 34.6937
    },
    "weather": [
        {
            "id": 803,
            "main": "Clouds",
            "description": "broken clouds",
            "icon": "04d"
        }
    ],
    "base": "stations",
    "main": {
        "temp": 11.38,
        "feels_like": 8.33,
        "temp_min": 11,
        "temp_max": 12.22,
        "pressure": 1007,
        "humidity": 62
    },
    "visibility": 10000,
    "wind": {
        "speed": 2.57,
        "deg": 220
    },
    "clouds": {
        "all": 75
    },
    "dt": 1611820991,
    "sys": {
        "type": 1,
        "id": 8032,
        "country": "JP",
        "sunrise": 1611784750,
        "sunset": 1611822143
    },
    "timezone": 32400,
    "id": 1853909,
    "name": "Osaka",
    "cod": 200
}

La temperatura máxima, mínima y el tiempo se pueden obtener de la siguiente manera:

set pResponse.AreaDescription=weatherinfo.weather.%Get(0).description
set pResponse.KionMax=weatherinfo.main."temp_max"
set pResponse.KionMin=weatherinfo.main."temp_min"

Si quieres saber más sobre la manipulación de JSON en IRIS, consulta la documentación.

Ahora, utilizaremos la herramienta para realizar pruebas de producción para ver si podemos obtener la información meteorológica de forma correcta.

Abre la página de Producción (Management Portal> Interoperability> Configuration> Production), haz clic en Start.GetKionOperation y, a continuación, haga clic en el botón "Test" en la pestaña "Action".

Especifica un nombre de ciudad (Naha, Sapporo, Nagano, Shinjuku, etc.) en Area, y haz clic en el botón “Run Test Service”.

Aquí puedes ver los resultados de la prueba, con las temperaturas máximas y mínimas y el tiempo registrado.

Continúa para saber cómo utilizar la página Trace.

Al seleccionar un rectángulo horizontal como en la pantalla izquierda hace que la información en la pantalla derecha, se modifique.

Los mensajes que se envían y reciben durante el proceso de integración del sistema se guardan automáticamente en la base de datos. Mediante la página de mensajes de Visual Trace, se puede ver en detalle qué mensajes se enviaron a qué componentes en orden cronológico y si hubo respuesta o no.

Además, si se produce un error

"Se produjo un error al enviar/recibir/recibir □ mensaje al componente de ○ a △".

aparecerá una marca roja donde se produjo el error para que se pueda ver. Por supuesto, además del seguimiento, también tenemos una página para registrar eventos. (Management Portal > [Interoperability] > [View] > [Event Log])

Seguimos. Vamos a revisar la operación para solicitar una actualización a la base de datos.

1)-2 Business Operations que solicitan actualizaciones a la base de datos

La muestra ofrece dos tipos de operaciones: Start.SQLInsertOperation y Start.InsertOperation.

Cada una de ellas es una operación para solicitar una actualización de la base de datos, pero Start.SQLInsertOperation utiliza el adaptador de salida de SQL, mientras que Start.InsertOperation no tiene ningún adaptador.

La diferencia entre ambos es

se asume que se accede mediante conexiones ODBC/JDBC a la operación que utiliza el adaptador de salida SQL, por lo que el destino de la conexión a la base de datos puede cambiarse en la configuración de la producción.

Para las operaciones que no utilizan adaptadores, se asume que el destino de la actualización de la BD es una base de datos dentro del rango de visibilidad de la configuración de producción y que no se produce ningún cambio en el destino de la conexión.

La base de datos IRIS puede utilizarse para almacenar datos arbitrarios durante la integración del sistema. Sin embargo, supongamos que la configuración del sistema cambia por cualquier razón unos años más tarde, y surge la necesidad de conectarse a una base de datos ubicada en un servidor diferente. En ese caso, la operación sin el adaptador no podrá continuar .

En cambio, las operaciones que utilizan el adaptador de salida SQL pueden funcionar si no hay cambios que procesen el contenido de las especificaciones del destino (si no hay ningún problema con la sentencia SQL que se ejecutará, puede conectarse con bases de datos de diferentes productos).

Durante la integración del sistema, puede haber casos en los que la información de la conexión cambia debido a razones externas al sistema. Por ello, es vital poseer un diseño que pueda responder con flexibilidad a los cambios. Por esta razón, se recomienda crear componentes que soporten conexiones externas de una forma libre de acoplamientos.

Sin embargo, supongamos que no hay ningún cambio en la configuración en el futuro. En ese caso, se podrá acceder a la base de datos en IRIS sin utilizar la conexión ODBC/JDBC, por lo que se podrá optar por utilizar el adaptador o no, dependiendo del tipo de uso.

Vamos a ver el código Start.SQLInsertOperation que utiliza el adaptador.

El adaptador que se utiliza en el ejemplo es un adaptador de salida SQL, que permite solicitar a la base de datos que ejecute sentencias SQL. Distintos adaptadores ofrecen diferentes métodos. Consulta la documentación para más detalles sobre los métodos que proporcionan los adaptadores.

Después, revisa el código de Start.InsertOperation, sin utilizar el adaptador.

Tanto si se utiliza un adaptador como si no, se requiere el mapa de mensajes y las definiciones de los métodos de la operación. Si no se utiliza un adaptador, no se necesita definir “Paramter” y “Property” para el adaptador.

Business Operations sin adaptadores: En Start.InsertOperation, SQL se ejecuta usando ObjectScript (el comentario de la afirmación es el proceso de actualización en las operaciones de objetos).

La implementación es satisfactoria si la base de datos que se actualiza no se separa de IRIS.

Descubrimos que las operaciones que utilizan adaptadores ofrecen un método fiable para solicitar el procesamiento desde el destino. También confirmamos que es posible crear operaciones sin utilizar adaptadores y escribir código de forma libre para ellas.

En el siguiente artículo, me gustaría explicar cómo crear un business process que llame a las operaciones para obtener información meteorológica y actualizar la base de datos en el orden correcto.