Utilización de las API REST de z/OS Connect
z/OS® Connect proporciona un conjunto de API RESTful que puede utilizar para descubrir servicios, comprobar el estado de servicios, iniciar o detener servicios, obtener estadísticas y demás operaciones.
Acerca de esta tarea
Puede utilizar las API REST de z/OS Connect desde un cliente que se ejecute en un entorno web, móvil o de nube.
Procedimiento
- Descubra los servicios en la configuración de z/OS Connect.
Ejemplo de la solicitud HTTP GET:
https://host:puerto/zosConnect/services
Ejemplo de la carga útil de JSON que se ha devuelto:
{ zosConnectServices: [ { ServiceName: "recordOpsCreate" ServiceDescription: "Creates a new record" ServiceProvider: "SAMPLE-1.0" ServiceURL: "https://host:port/zosConnect/services/recordOpsCreate" }, { ServiceName: "recordOpsDelete" ServiceDescription: "Deletes an existing record" ServiceProvider: "SAMPLE-1.0" ServiceURL: "https://host:port/zosConnect/services/recordOpsDelete" } ] }
- Recupere los datos de configuración de un servicio. Ejemplo de la solicitud HTTP GET:
https://host:puerto/zosConnect/services/recordOpsCreate
La salida se devuelve en dos partes: la primera parte contiene los parámetros de configuración de z/OS Connect y la segunda parte tiene la configuración que ha devuelto la implementación del proveedor de servicios. A continuación se ofrece un ejemplo de la carga útil de JSON que se ha devuelto:
{ zosConnect: { serviceName: "recordOpsCreate" serviceDescription: "Creates a new record" serviceProvider: "SAMPLE-1.0" serviceURL: "https://host:port/zosConnect/services/recordOpsCreate" serviceInvokeURL: "https://host:port/zosConnect/services/recordOpsCreate?action=invoke" dataXformProvider: "jsonByte-1.0" }, recordOpsCreate: { targetProgram: "CREATREC" timeout: "300ms" } }
- Recupere el estado de un servicio. Ejemplo de la solicitud HTTP GET:
https://host:puerto/zosConnect/services/recordOpsCreate?action=status
Ejemplo de la carga útil de JSON que se ha devuelto.
{ zosConnect: { serviceName: "recordOpsCreate" serviceDescription: "Creates a new record" serviceProvider: "SAMPLE-1.0" serviceURL: "https://host:port/zosConnect/services/recordOpsCreate" serviceInvokeURL: "https://host:port/zosConnect/services/recordOpsCreate?action=invoke" dataXformProvider: "jsonByte-1.0" serviceStatus: "Started" } }
- Recupere el esquema de solicitud. Ejemplo de la solicitud HTTP GET:
https://host:puerto/zosConnect/services/recordOpsCreate?action=getRequestSchema
Ejemplo de la carga útil de JSON que se ha devuelto.
{ <El esquema de solicitud tal como lo ha devuelto el transformador de datos configurados> }
- Recupere el esquema de respuesta. Ejemplo de la solicitud HTTP GET:
https://host:puerto/zosConnect/services/recordOpsCreate?action=getResponseSchema
Ejemplo de la carga útil de JSON que se ha devuelto.
{ <El esquema de solicitud tal como lo ha devuelto el transformador de datos configurados> }
- Recupere las estadísticas.
Las estadísticas incluyen datos de z/OS Connect para un servicio como, por ejemplo, InvokeRequestCount, y TimeOfRegistrationWithZosConnect, junto con otras estadísticas que ha devuelto el proveedor de servicios utilizando la implementación de la SPI getStatistics() en el proveedor. Las estadísticas para un servicio determinado se pueden recuperar a través de /zosConnect/operation o una llamada action= request. Las solicitudes de /zosConnect/operations ofrecen mayor flexibilidad porque el producto puede recuperar estadísticas para todos los servicios. Si se ha habilitado el interceptor de autorización, el producto devolverá las estadísticas solamente para aquellos servicios que el usuario pueda solicitar. Consulte la documentación sobre la seguridad de z/OS Connect para obtener más detalles.
Ejemplo de la solicitud HTTP GET para que devuelva estadísticas utilizando action=getStatistics:
https://host:puerto/zosConnect/services/recordOpsCreate?action=getStatistics
Ejemplo de la carga útil de JSON que se ha devuelto.
{ recordOpsCreate: { ServiceProvider: "SAMPLE-1.0" InvokeRequestCount: 100 TimeOfRegistrationWithZosConnect: "xxx-xx-xx xx:xx:xx:xxx xxx" ServiceStatistics: { <Pares del valor de nombre JSON que muestran información estadística que ha devuelto el servicio> } } }
- La recuperación de estadísticas para un servicio también se puede llevar a cabo utilizando la API REST
zosConnect/operations/getStatistics.
La información devuelta incluye las estadísticas para todos los servicios que puede solicitar el usuario actual.
Ejemplo de la solicitud HTTP GET utilizando /zosConnect/operation/getStatistics:
https://host:puerto/zosConnect/operations/getStatistics
Ejemplo de la carga útil de JSON que se ha devuelto.
{ zosConnectStatistics: [ { recordOpsCreate: { ServiceProvider: "SAMPLE-1.0" InvokeRequestCount: 100 TimeOfRegistrationWithZosConnect: "xxx-xx-xx xx:xx:xx:xxx xxx" ServiceStatistics: { <Pares del valor de nombre JSON que muestran información estadística que ha devuelto el servicio> } } }, { recordOpsDelete: { ServiceProvider: "SAMPLE-1.0" InvokeRequestCount: 100 TimeOfRegistrationWithZosConnect: "xxx-xx-xx xx:xx:xx:xxx xxx" ServiceStatistics: { <Pares del valor de nombre JSON que muestran información estadística que ha devuelto el servicio> } } } ] }
Si no hay servicios registrados con z/OS Connect, la salida se parecerá a la siguiente:
{ zosConnectStatistics:[] }
- Recupere las estadísticas para todos los servicios que se han definido para un proveedor de servicios específico utilizando la API REST
zosConnect/operations/getStatistics.
Ejemplo de la solicitud HTTP GET:
https://host:puerto/zosConnect/operations/getStatistics?provider=SAMPLE-1.0
Formato/Salida de ejemplo:
{ recordOpsCreate: { ServiceProvider: "SAMPLE-1.0" InvokeRequestCount: 100 TimeOfRegistrationWithZosConnect: "xxx-xx-xx xx:xx:xx:xxx xxx" ServiceStatistics: { .. Pares del valor de nombre JSON que muestran información estadística que ha devuelto el servicio. } } }
- Recupere las estadísticas para un solo servicio utilizando la API REST zosConnect/operations/getStatistics?service=<service
name>. Esta operación equivale a especificar action=getStatistics en un servicio. Solicitud HTTP GET en:
https://host:puerto/zosConnect/operations/getStatistics?service=recordOpsCreate
Ejemplo de la carga útil de JSON que se ha devuelto:
{ recordOpsCreate: { ServiceProvider: "SAMPLE-1.0" InvokeRequestCount: 100 TimeOfRegistrationWithZosConnect: "xxx-xx-xx xx:xx:xx:xxx xxx" ServiceStatistics: { <Pares del valor de nombre JSON que muestran información estadística que ha devuelto el servicio> } } }
- Detenga los servicios de z/OS Connect utilizando una solicitud HTTP POST o PUT
con action=stop, o inicie los servicios utilizando
HTTP POST o PUT con la serie de consulta action=start.
Las acciones de detención e inicio no requieren carga útil. Si se proporciona una, se hará caso omiso. Un usuario puede recuperar el estado de un servicio de z/OS Connect utilizando HTTP GET en el nombre de servicio con la serie de consulta action=status para recuperar el estado del servicio. Si se ha habilitado el interceptor de autorización que proporciona z/OS Connect, el usuario que solicita el estado o el cambio de estado debe estar en el grupo de operadores o administradores necesario para el servicio. Para cada caso, z/OS Connect invoca a la SPI del proveedor de servicios para notificarle que se han solicitado esas acciones. Los nombres de método que se hallan en la SPI para estas acciones son stop(), start() y status().
Nota: z/OS Connect no persiste ningún estado que esté relacionado con el servicio y, en cambio, lo delega al proveedor de servicios.El proveedor de servicios puede enviar respuestas distintas a las de detención o inicio. z/OS Connect permite que se devuelva un estado personalizado.
Ejemplo de la detención de un servicio utilizando HTTP POST o PUT:
https://host:puerto/zosConnect/services/recordOpsCreate?action=stop
Ejemplo de la carga útil de JSON que se ha devuelto:
{ zosConnect: { serviceName: "recordOpsCreate" serviceDescription: "Creates a new record" serviceProvider: "SAMPLE-1.0" serviceURL: "https://host:port/zosConnect/services/recordOpsCreate" serviceInvokeURL: "https://host:port/zosConnect/services/recordOpsCreate?action=invoke" dataXformProvider: "jsonByte-1.0" serviceStatus: "Stopped" } }
- Ejemplo del inicio de un servicio utilizando HTTP POST o PUT:
https://host:puerto/zosConnect/services/recordOpsCreate?action=start
Ejemplo de la carga útil de JSON que se ha devuelto:
{ zosConnect: { serviceName: "recordOpsCreate" serviceDescription: "Creates a new record" serviceProvider: "SAMPLE-1.0" serviceURL: "https://host:port/zosConnect/services/recordOpsCreate" serviceInvokeURL: "https://host:port/zosConnect/services/recordOpsCreate?action=invoke" dataXformProvider: "jsonByte-1.0" serviceStatus: "Started" } }
- Invoque servicios utilizando la serie de consulta de z/OS Connect: action=invoke, que ejecuta el método
invoke() de implementación de la SPI del proveedor de servicios.
El ejemplo en este paso ejecuta el método de invocación para el servicio denominado recordOpsCreate y pasa una carga útil de objeto JSON al cuerpo de la solicitud.
El método de invocación de z/OS Connect admite una carga útil de entrada en formato de objeto JSON para esta solicitud. En el ejemplo de código, se supone que z/OS Connect ha buscado el proveedor de servicio y ha identificado una referencia de servicio para el servicio denominado SAMPLE-1.0. También hay una referencia a la transformación de datos en la definición de servicios de z/OS Connect con un proveedor denominado jsonByte-1.0. Teniendo esto en cuenta, cuando el método de invocación del proveedor de servicios obtiene el control y llama al método getBytes(), la implementación de la transformación de datos toma el control y convierte la carga útil de la solicitud de JSON a una matriz de bytes y la devuelve al proveedor de servicios.
Si el URL con el que venía la solicitud de la acción de invocación contiene parámetros de entrada, estos parámetros, junto con otra información de solicitud HTTP, pasarán al proveedor de servicios utilizando la interfaz SPI com.ibm.wsspi.zos.connect.HttpZosConnectRequest que proporciona z/OS Connect. Los interceptores procesados para acciones u operaciones también reciben la información de solicitud HTTP a través del mismo objeto.
Otro estilo de invocación que admite z/OS Connect proporciona una forma de definir un URI definido por el usuario como invokeURI en la definición de servicios de z/OS Connect. Con este estilo, la solicitud HTTP no es necesario que contenga zosConnect/services y puede ser, en cambio, una serie definida por el usuario.
Cuando se utiliza este estilo, z/OS Connect admite el uso de otros métodos HTTP como, por ejemplo, GET, PUT, POST y DELETE. Las solicitudes que llegan a este URI, independientemente del método HTTP empleado, pasan a través de los interceptores de z/OS Connect y pasan al método invoke() del proveedor de servicios.
Ejemplo de utilización HTTP POST o PUT:
https://host:puerto/zosConnect/services/recordOpsCreate?action=invoke { <Objeto JSON pasado a la invocación de servicios> }
Ejemplo de la carga útil de JSON que se ha devuelto:
{ <Objeto JSON devuelto de la invocación de servicios> }

Nombre de archivo: twlp_zconnect_rest.html