z/OS Connect-REST-APIs verwenden

z/OS® Connect stellt einen Satz REST-konformer APIs bereit, mit denen Sie Services erkennen, den Servicestatus überprüfen, Services starten und stoppen, Statistiken abrufen und weitere Operationen ausführen können.

Informationen zu diesem Vorgang

Sie können z/OS Connect-REST-APIs über einen Client verwenden, der in einer Webumgebung, einer mobilen Umgebung oder einer Cloudumgebung ausgeführt wird.

Vorgehensweise

  1. Services in der z/OS Connect-Konfiguration erkennen.

    Beispiel für eine HTTP-Abrufanforderung GET:

    https://Host:Port/zosConnect/services 

    Zurückgegebene JSON-Beispielnutzdaten:

    { 
      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. Konfigurationsdaten für einen Service abrufen. Beispiel für eine HTTP-Abrufanforderung GET:
    https://Host:Port/zosConnect/services/recordOpsCreate 

    Die Ausgabe wird in zwei Teilen zurückgegeben: Der erste Teil enthält die z/OS Connect-Konfigurationsparameter und der zweite Teil enthält die von der Service-Provider-Implementierung zurückgegebene Konfiguration. Im Folgenden sehen Sie ein Beispiel für die zurückgegebenen JSON-Nutzdaten:

    { 
      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. Servicestatus abrufen. Beispiel für eine HTTP-Abrufanforderung GET:
    https://Host:Port/zosConnect/services/recordOpsCreate?action=status

    Zurückgegebene JSON-Beispielnutzdaten.

    {
      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. Anforderungsschema abrufen. Beispiel für eine HTTP-Abrufanforderung GET:
    https://Host:Port/zosConnect/services/recordOpsCreate?action=getRequestSchema

    Zurückgegebene JSON-Beispielnutzdaten.

    {
    <Vom konfigurieren Datentransformator zurückgegebenes Anforderungsschema>
    }
  5. Antwortschema abrufen. Beispiel für eine HTTP-Abrufanforderung GET:
    https://Host:Port/zosConnect/services/recordOpsCreate?action=getResponseSchema

    Zurückgegebene JSON-Beispielnutzdaten.

    {
    <Vom konfigurieren Datentransformator zurückgegebenes Anforderungsschema>
    }
  6. Statistiken abrufen.

    Statistiken enthalten z/OS Connect-Daten für einen Service wie InvokeRequestCount und TimeOfRegistrationWithZosConnect sowie weitere Statistiken, die vom Service-Provider mit der getStatistics()-SPI-Implementierung im Provider zurückgegeben werden. Statistiken für einen bestimmten Service können über einen Aufruf von /zosConnect/operation oder action= request abgerufen werden. /zosConnect/operations-Anforderungen bieten eine höhere Flexibilität, da das Produkt Statistiken für alle Services abrufen kann. Wenn der Berechtigungsinterceptor aktiviert ist, gibt das Produkt nur Statistiken für die Services zurück, die der Benutzer anfordern kann. Weitere Details finden Sie in der Dokumentation zur z/OS Connect-Sicherheit.

    HTTP-Beispielabrufanforderung zum Zurückgeben von Statistiken mit action=getStatistics:

    https://Host:Port/zosConnect/services/recordOpsCreate?action=getStatistics

    Zurückgegebene JSON-Beispielnutzdaten.

    {
      recordOpsCreate: 
      {
        ServiceProvider: "SAMPLE-1.0"
        InvokeRequestCount: 100
        TimeOfRegistrationWithZosConnect: "xxx-xx-xx xx:xx:xx:xxx xxx"
        ServiceStatistics: 
        {
    			<JSON-Name/Wert-Paare mit vom Service zurückgegebenen statistischen Informationen>
        }
      }
    }
  7. Statistiken für einen Service können auch mit der REST-API zosConnect/operations/getStatistics abgerufen werden.

    Die zurückgegebenen Informationen enthalten Statistiken für alle Services, die der aktuelle Benutzer anfordern kann.

    HTTP-Beispielabrufanforderung mit /zosConnect/operation/getStatistics:

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

    Zurückgegebene JSON-Beispielnutzdaten.

    {
    zosConnectStatistics: 
    [
      {
        recordOpsCreate: 
        {  
             ServiceProvider: "SAMPLE-1.0"
             InvokeRequestCount: 100
             TimeOfRegistrationWithZosConnect: "xxx-xx-xx xx:xx:xx:xxx xxx"
          ServiceStatistics: 
          {
    				<JSON-Name/Wert-Paare mit vom Service zurückgegebenen statistischen Informationen>
             }
           }
         },
      {
        recordOpsDelete: 
        {  
             ServiceProvider: "SAMPLE-1.0"
             InvokeRequestCount: 100
             TimeOfRegistrationWithZosConnect: "xxx-xx-xx xx:xx:xx:xxx xxx"
          ServiceStatistics: 
          {
    				<JSON-Name/Wert-Paare mit vom Service zurückgegebenen statistischen Informationen>
             }
           }
         }
      ]
    }

    Wenn keine Services bei z/OS Connect registriert sind, sieht die Ausgabe wie folgt aus:

    {
    zosConnectStatistics:[]
    }
  8. Rufen Sie Statistiken für alle Services ab, die für einen bestimmten Service-Provider definiert sind, indem Sie die REST-API "zosConnect/operations/getStatistics" verwenden.

    Beispiel für eine HTTP-Abrufanforderung GET:

    https://Host:Port/zosConnect/operations/getStatistics?provider=SAMPLE-1.0 

    Beispielformat/Beispielausgabe:

    {
      recordOpsCreate: 
      {
        ServiceProvider: "SAMPLE-1.0"
        InvokeRequestCount: 100
        TimeOfRegistrationWithZosConnect: "xxx-xx-xx xx:xx:xx:xxx xxx"
        ServiceStatistics: 
        {
          .. JSON-Name/Wert-Paare mit vom Service zurückgegebenen statistischen Informationen.
        }
      }
    }
  9. Rufen Sie Statistiken für einen einzelnen Service mit der REST-API "zosConnect/operations/getStatistics?service=<Servicename>" ab. Die Verwendung dieser Operation entspricht der Angabe von action=getStatistics für einen Service. HTTP-Abrufanforderung GET:
    https://host:port/zosConnect/operations/getStatistics?service=recordOpsCreate 

    Zurückgegebene JSON-Beispielnutzdaten:

    {
      recordOpsCreate: 
      {
        ServiceProvider: "SAMPLE-1.0"
        InvokeRequestCount: 100
        TimeOfRegistrationWithZosConnect: "xxx-xx-xx xx:xx:xx:xxx xxx"
        ServiceStatistics: 
        {
    			<JSON-Name/Wert-Paare mit vom Service zurückgegebenen statistischen Informationen>
        }
      }
    }      
  10. Stoppen Sie z/OS Connect-Services mit einer HTTP-POST-Anforderung oder einer HTTP-PUT-Anforderung mit action=stop oder starten Sie die Services mit HTTP POST oder PUT mit der Abfragezeichenfolge action=start.

    Für Stopp- und Startaktionen sind keine Nutzdaten erforderlich. Werden Nutzdaten angegeben, werden sie ignoriert. Ein Benutzer kann den Status eines z/OS Connect-Service mit HTTP GET für den Servicenamen mit der Abfragezeichenfolge action=status abrufen. Wenn der von z/OS Connect bereitgestellte Berechtigungsinterceptor aktiviert ist, muss der Benutzer, der den Status oder die Statusänderung anfordert, die für den Service erforderlich ist, zur Bediener- oder Administratorgruppe gehören. Die SPI des Service-Providers wird jeweils von z/OS Connect aufgerufen, um den Service über die Anforderung dieser Aktionen zu benachrichtigen. Die zugehörigen Methodennamen in der SPI sind stop(), start() und status().

    Anmerkung: z/OS Connect speichert nicht jeden Status persistent, der sich auf den Service bezieht, und delegiert dies stattdessen an den Service-Provider.

    Der Service-Provider kann andere Antworten als Stopp- und Startantworten senden. z/OS Connect erlaubt die Rückgabe eines angepassten Status.

    Beispiel für das Stoppen eines Service mit HTTP POST oder PUT:

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

    Zurückgegebene JSON-Beispielnutzdaten:

    {
      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. Servicebeispiel mit HTTP POST oder HTTP PUT starten:
    https://Host:Port/zosConnect/services/recordOpsCreate?action=start

    Zurückgegebene JSON-Beispielnutzdaten:

    {
      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. Rufen Sie Services mit der z/OS Connect-Abfragezeichenfolge action=invoke auf, die die Methode invoke() der SPI-Implementierung des Service-Providers ausführt.

    Das Beispiel in diesem Schritt führt die invoke-Methode für den Service mit dem Namen recordOpsCreate aus und übergibt Nutzdaten eines JSON-Objekts im Anforderungshauptteil.

    Die invoke-Methode von z/OS Connect unterstützt für diese Anforderung Eingabenutzdaten im JSON-Objektformat. Im Codebeispiel wird davon ausgegangen, dass z/OS Connect den Service-Provider gesucht und eine Servicereferenz für den Service mit dem Namen SAMPLE-1.0 ermittelt hat. Außerdem gibt es eine Datentransformationreferenz in der z/OS Connect-Servicedefinition mit einem Provider mit dem Namen jsonByte-1.0. Wenn die invoke-Methode des Service-Providers somit die Kontrolle erlangt und die Methode getBytes() aufruft, erlangt die Implementierung der Datentransformation Kontrolle und konvertiert die Anforderungsnutzdaten aus JSON in ein Byte-Array und gibt es an den Service-Provider zurück.

    Wenn die URL, mit der die invoke-Aktionsanforderung getätigt wurde, Abfrageparameter enthält, werden diese Parameter zusammen mit weiteren HTTP-Anforderungsinformationen an den Service-Provider mit der SPI-Schnittstelle com.ibm.wsspi.zos.connect.HttpZosConnectRequest von z/OS Connect übergeben. Interceptors, die für Aktionen oder Operationen verarbeitet werden, empfangen ebenfalls HTTP-Anforderungsionformationen über dasselbe Objekt.

    Ein weiterer von z/OS Connect unterstützter Aufrufstil stellt einen Möglichkeit dar, einen benutzerdefinierten URI als invokeURI in der z/OS Connect-Servicedefinition zu definieren. Wird dieser Stil verwendet, muss die HTTP-Anforderung zosConnect/services nicht enthalten und kann stattdessen eine benutzerdefinierte Zeichenfolge sein.

    Wird dieser Stil verwendet, unterstützt z/OS Connect die Verwendung anderer HTTP-Methoden wie GET, PUT, POST und DELETE. Anforderungen, die mit diesem URI eingehen, durchlaufen unabhängig von der verwendeten HTTP-Methode z/OS Connect-Interceptors und werden an die Methode invoke() des Service-Providers übergeben.

    Beispiel für die Verwendung von HTTP POST oder PUT:

    https://host:port/zosConnect/services/recordOpsCreate?action=invoke 
    {
    <Für den Serviceaufruf übergebenes JSON-Objekt>
    }

    Zurückgegebene JSON-Beispielnutzdaten:

    {
    <Vom Serviceaufruf zurückgegebenes JSON-Objekt>
    }

Symbol das den Typ des Artikels anzeigt. Taskartikel

Dateiname: twlp_zconnect_rest.html