Utilisation des API REST de z/OS Connect

z/OS® Connect fournit un ensemble d'API RESTful que vous pouvez utiliser pour reconnaître des services, vérifier le statut des services, démarrer ou arrêter des services, obtenir des statistiques, et effectuer d'autres opérations.

Pourquoi et quand exécuter cette tâche

Vous pouvez utiliser des API REST de z/OS Connect depuis un client opérant en environnement Web, sur une unité mobile ou un cloud.

Procédure

  1. Reconnaissance des services dans la configuration z/OS Connect.

    Exemple de requête HTTP GET :

    https://host:port/zosConnect/services 

    Exemple de contenu JSON renvoyé :

    { 
      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" 
        } 
      ] 
    } 
  2. Extrayez les données de configuration d'un service. Exemple de requête HTTP GET :
    https://host:port/zosConnect/services/recordOpsCreate 

    Le résultat est renvoyé en deux parties : la première contient les paramètres de configuration z/OS Connect et le seconde contient la configuration renvoyée par l'implémentation du fournisseur de services. Ci-après figure un exemple de contenu JSON renvoyé :

    { 
      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" 
      } 
    }
  3. Extrayez le statut ^du service. Exemple de requête HTTP GET :
    https://host:port/zosConnect/services/recordOpsCreate?action=status

    Exemple de contenu JSON renvoyé.

    {
      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"
      }
    }
  4. Extrayez le contenu de la requête. Exemple de requête HTTP GET :
    https://host:port/zosConnect/services/recordOpsCreate?action=getRequestSchema

    Exemple de contenu JSON renvoyé.

    {
    <Request schema as returned by the data configured data transformer>
    }
  5. Extrayez le schéma de réponse. Exemple de requête HTTP GET :
    https://host:port/zosConnect/services/recordOpsCreate?action=getResponseSchema

    Exemple de contenu JSON renvoyé.

    {
    <Request schema as returned by the data configured data transformer>
    }
  6. Extrayez les statistiques.

    Les statistiques incluent les données z/OS pour un service tel que InvokeRequestCount et une valeur TimeOfRegistrationWithZosConnect, ainsi que d'autres statistiques éventuelles renvoyées par le fournisseur de services utilisant l'interface SPI getStatistics() dans le fournisseur. Les statistiques d'un service spécifique peuvent être extraites via un appel de /zosConnect/operation ou de action= request . Les requêtes /zosConnect/operations offrent plus de souplesse puisque le produit peut extraite des statistiques pour tous les services. Si l'intercepteur d'autorisation est activé, le produit ne renvoie des statistiques que pour les services que l'utilisateur peut demander. Pour plus d'informations, reportez-vous à la documentation sur la sécurité z/OS Connect.

    Exemple de requête HTTP GET pour renvoi de statistiques à l'aide de action=getStatistics:

    https://host:port/zosConnect/services/recordOpsCreate?action=getStatistics 

    Exemple de contenu JSON renvoyé.

    {
      recordOpsCreate: 
      {
        ServiceProvider: "SAMPLE-1.0"
        InvokeRequestCount: 100
        TimeOfRegistrationWithZosConnect: "xxx-xx-xx xx:xx:xx:xxx xxx"
        ServiceStatistics: 
        {
    			<JSON name value pairs showing statistical information the service returned>
        }
      }
    }
  7. L'extraction de statistiques pour un service peut également être réalisée à l'aide de l'API REST zosConnect/operations/getStatistics .

    Les informations renvoyées incluent des statistiques pour tous les services que l'utilisateur actuel peut demander.

    Exemple de requête HTTP GET à l'aide de /zosConnect/operation/getStatistics :

    https://host:port/zosConnect/operations/getStatistics

    Exemple de contenu JSON renvoyé.

    {
    zosConnectStatistics: 
    [
      {
        recordOpsCreate: 
        {  
             ServiceProvider: "SAMPLE-1.0"
             InvokeRequestCount: 100
             TimeOfRegistrationWithZosConnect: "xxx-xx-xx xx:xx:xx:xxx xxx"
          ServiceStatistics: 
          {
    				<JSON name value pairs showing statistical information the service returned>
             }
           }
         },
      {
        recordOpsDelete: 
        {  
             ServiceProvider: "SAMPLE-1.0"
             InvokeRequestCount: 100
             TimeOfRegistrationWithZosConnect: "xxx-xx-xx xx:xx:xx:xxx xxx"
          ServiceStatistics: 
          {
    				<JSON name value pairs showing statistical information the service returned>
             }
           }
         }
      ]
    }

    Si aucun service n'est enregistré auprès de z/OS Connect, la sortie est similaire à ceci :

    {
    zosConnectStatistics:[]
    }
  8. Extrayez des statistiques pour tous les services définis pour un fournisseur de services spécifique à l'aide de l'API REST zosConnect/operations/getStatistics.

    Exemple de requête HTTP GET :

    https://host:port/zosConnect/operations/getStatistics?provider=SAMPLE-1.0 

    Exemple de format/sortie :

    {
      recordOpsCreate: 
      {
        ServiceProvider: "SAMPLE-1.0"
        InvokeRequestCount: 100
        TimeOfRegistrationWithZosConnect: "xxx-xx-xx xx:xx:xx:xxx xxx"
        ServiceStatistics: 
        {
          .. JSON name value pairs showing statistical information the service returned.
        }
      }
    }
  9. Extrayez des statistiques pour un service unique à l'aide de l'API REST zosConnect/operations/getStatistics?service=<nom service>. Cette opération est équivalente à la chaîne de requête action=getStatistics sur un service. Requête HTTP GET :
    https://host:port/zosConnect/operations/getStatistics?service=recordOpsCreate 

    Exemple de contenu JSON renvoyé :

    {
      recordOpsCreate: 
      {
        ServiceProvider: "SAMPLE-1.0"
        InvokeRequestCount: 100
        TimeOfRegistrationWithZosConnect: "xxx-xx-xx xx:xx:xx:xxx xxx"
        ServiceStatistics: 
        {
    			<JSON name value pairs showing statistical information the service returned>
        }
      }
    }      
  10. Arrêtez les services z/OS Connect en utilisant une requête HTTP POST ou PUT avec action=stop, ou démarrez les services en utilisant HTTP POST ou PUT avec la chaîne de requête action=start.

    Arrêtez et démarrez des actions qui ne requièrent pas un contenu. Si une telle action est indiquée, elle est ignorée. Un utilisateur peut extraire le statut d'un service z/OS Connect en utilisant HTTP GET sur le nom du service avec la chaîne de requête action=status. Si l'intercepteur d'autorisation fourni par z/OS Connect est activé, l'utilisateur demandant le statut ou le changement d'état doit faire partie du groupe des opérateurs ou des administrateurs requis pour le service. Pour chacun de ces membres, l'interface SPI du fournisseur de service est appelée par z/OS Connect pour l'aviser que ces actions ont été demandées. Les noms de méthode dans l'interface SPI pour cette opération sont : stop(), start() et status().

    Remarque : z/OS Connect ne rend persistant aucun état associé au service mais délègue ceci au fournisseur de services.

    Le fournisseur de services peut renvoyer des réponses autres que le démarrage ou l'arrêt. z/OS Connect permet de renvoyer un statut personnalisé.

    Exemple d'arrêt d'un service à l'aide de HTTP POST ou PUT:

    https://host:port/zosConnect/services/recordOpsCreate?action=stop 

    Exemple de contenu JSON renvoyé :

    {
      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"
      }
    }
  11. Lancez un exemple de service utilisant HTTP POST ou PUT :
    https://host:port/zosConnect/services/recordOpsCreate?action=start 

    Exemple de contenu JSON renvoyé :

    {
      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"
      }
    }
  12. Appelez des services à l'aide de la chaîne de requête z/OS Connect : action=invoke, laquelle exécute la méthode invoke() de l'implémentation d'interface SPI du fournisseur de services.

    L'exemple de cette étape exécute la méthode 'invoke' pour le service nommé recordOpsCreate et transmet un contenu d'objet JSON dans le corps de la requête.

    La méthode z/OS Connect 'invoke' prend en charge un contenu d'entrée sous forme d'objet JSON pour cette requête. L'exemple de code suppose que z/OS Connect a recherché le fournisseur de services et a identifié une référence de service pour le service nommé SAMPLE-1.0. La définition de service z/OS Connect contient également une référence de transformation de données avec un fournisseur nommé jsonByte-1.0. Dans cette situation, lorsque la méthode 'invoke' du fournisseur de données prend le contrôle et appelle la méthode getBytes(), l'implémentation de transformation des données prend la main et convertit le contenu de la requête au format JSON en tableau d'octets et la renvoie au fournisseur de données.

    Si l'URL d'où provient la requête d'action 'invoke' était accompagnée de paramètres de requête, ces paramètres ainsi que d'autres informations de requête HTTP sont transmis au fournisseur de services à l'aide de l'interface SPI com.ibm.wsspi.zos.connect.HttpZosConnectRequest fournie par z/OS Connect. Les intercepteurs traités pour des actions ou des opérations reçoivent également les informations de requête HTTP via le même objet.

    Un autre style d'appel pris en charge par z/OS Connect permet de spécifier une URI définie par l'utilisateur comme l'élément invokeURI dans la définition de service z/OS Connect. De la sorte, la requête HTTP n'a pas besoin de contenir zosConnect/services et peut à la place être une chaîne définie par l'utilisateur.

    Lorsque ce style est employé, z/OS Connect prend en charge l'utilisation d'autres méthodes HTTP, telles que GET, PUT, POST et DELETE. Les requêtes arrivant avec cette URI, quelle que soit la méthode HTTP employée, transitent par les intercepteurs z/OS Connect d'où elles sont transmises à la méthode invoke() du fournisseur de services.

    Exemple utilisant HTTP POST ou PUT :

    https://host:port/zosConnect/services/recordOpsCreate?action=invoke 
    {
    <JSON object passed in for the service invocation>
    }

    Exemple de contenu JSON renvoyé :

    {
    <JSON object returned from the service invocation>
    }

Icône indiquant le type de rubrique Rubrique Tâche

Nom du fichier : twlp_zconnect_rest.html