Automatizar z/OS mediante z/OSMF: las API REST de trabajos, conjuntos de datos y archivos

Qué es

z/OS Management Facility (z/OSMF) es la interfaz de IBM basada en navegador y orientada a tareas para las tareas de programación de sistemas de z/OS, pensada para hacer el sistema accesible al personal que aún no domina los paneles de TSO/ISPF. Por debajo de su interfaz de usuario, z/OSMF expone las mismas funciones como servicios REST sobre HTTPS: una interfaz de trabajos (jobs) para enviar, listar y consultar trabajos por lotes y obtener su salida de spool; una interfaz de conjuntos de datos y archivos para listar, leer y escribir conjuntos de datos clásicos y archivos UNIX de z/OS; y otras interfaces adicionales para el resto de tareas de programación de sistemas. Para un agente, estas API REST son la alternativa práctica a manejar TSO/ISPF o SDSF mediante emulación de terminal: devuelven JSON estructurado sobre verbos HTTP normales (GET, PUT, POST, DELETE) en lugar de texto de pantalla posicional.

Las solicitudes llevan la cabecera personalizada X-CSRF-ZOSMF-HEADER (su valor no es significativo; el cliente de ejemplo de IBM envía zosmf), que existe para evitar la falsificación de solicitudes entre sitios; una llamada que cambia el estado sin ella se rechaza incluso con credenciales válidas, y el ejemplo de IBM también la envía en las lecturas. Un trabajo se envía con PUT /zosmf/restjobs/jobs y el JCL como cuerpo text/plain; el estado se obtiene con GET /zosmf/restjobs/jobs/{jobname}/{jobid} (terminado cuando status es OUTPUT, con un retcode como CC 0000, ABEND S0C7 o JCL ERROR), y el spool con .../{jobid}/files y .../files/{id}/records. Los conjuntos de datos residen bajo /zosmf/restfiles/ds/{dsname} (listado con ?dslevel=HLQ.*) y los archivos UNIX bajo /zosmf/restfiles/fs/{path}.

Por qué importa

Tratar z/OSMF como «una API REST más» sin la cabecera CSRF es el fallo de integración inicial más habitual; y como las API de trabajos/conjuntos de datos/archivos se corresponden de cerca con los conceptos subyacentes de JES y de conjuntos de datos (un trabajo enviado sigue obteniendo un ID de trabajo de JES, y escribir un conjunto de datos sigue teniendo que cumplir las reglas de RECFM/LRECL y de autoridad de acceso), entender antes los fundamentos de JCL/conjuntos de datos (véanse los demás artículos sobre z/OS) hace que las respuestas REST resulten más fáciles de interpretar en lugar de opacas.

Cómo aplicarlo

• Incluir X-CSRF-ZOSMF-HEADER en cada solicitud; es inofensiva en las lecturas y obligatoria en las escrituras.
• Autenticarse por HTTPS con lo que acepte el z/OSMF local: normalmente autenticación básica HTTP con el ID de usuario y la contraseña SAF (RACF), un certificado de cliente, o la cookie de token de sesión devuelta por una primera solicitud autenticada. El ID de usuario también necesita autorización de z/OSMF (habitualmente, pertenecer al grupo IZUUSER).
• Usar el sondeo de estado de la API de trabajos en lugar de esperas fijas para detectar la finalización de un trabajo, y obtener la salida de spool a través de la misma API en lugar de recurrir a SDSF una vez que un flujo de trabajo está automatizado.
• Tratar las respuestas HTTP que no son 2xx como la señal de error principal; z/OSMF devuelve los detalles del problema en el cuerpo JSON en lugar de un código de mensaje 3270.

Trampas

• Reutilizar una cookie o un token de sesión más allá de su tiempo de espera configurado y obtener fallos de autenticación que parecen fallos de autorización.
• Suponer que la API REST de trabajos elude las comprobaciones de autoridad de RACF sobre conjuntos de datos o clases de trabajo; no es así — se aplican los mismos controles de acceso que a cualquier otro remitente.