配置 JAX-RS 2.0 用戶端

若為 Java™ API for XML RESTful Web Services 2.0,您可以將用戶端配置成存取 REST 端點。JAX-RS 2.0 推出新的標準化「用戶端 API」,可讓您對遠端 RESTful Web 服務提出 HTTP 要求。

關於這項作業

需要 Client 實例,才能使用「用戶端 API」存取 Web 資源。如果要取得 Client 預設實例,可在 ClientBuilder 上呼叫 newClientbuild。如果您建立用戶端,您可以在伺服器層次或用戶端應用程式內配置它。

程序

  1. server.xml 檔中啟用 jaxrsClient-2.0 或 jaxrs-2.0 特性:
    <featureManager>
        <feature>jaxrs-2.0</feature>// If you only need the JAX-RS 2.0 client feature, you can enable jaxrsClient-2.0 instead of  jaxrs-2.0
    </featureManager>
  2. 建立 JAX-RS 2.0 用戶端,並傳送要求給伺服器:
    javax.ws.rs.client.ClientBuilder cb = ClientBuilder.newBuilder();
    
    javax.ws.rs.client.Client c = cb.build();
    String res = null;
    
    try {
    	res = c.target("<Resource_URL>")
                 .path("<PATH>")
                 .request()
                 .get(String.class);
    	} catch (Exception e) {
          	res = "[Error]:" + e.toString();
          } finally {
                c.close();
          }   
    如需非同步 JAX-RS 2.0 用戶端的相關資訊,請參閱非同步處理

下一步

建立 JAX-RS 2.0 用戶端之後,您可以配置它,作法是在 server.xml 檔中定義 webTarget 元素,或在用戶端應用程式中以程式設計方式配置內容。

[17.0.0.2 以及更新版本]如果要在 server.xml 檔中,以 webTarget XML 元素來配置內容,請輸入:

<webTarget URI="value" property="value" property="value".../>
當將 webTarget 物件實例化,且其 URI 符合這個元素中的 URI 值時,會將內容套用至 webTarget 物件。在您定義 webTarget 元素時,請考量下列的配置資訊:
  • URI 可以是確切的,例如 http://foo,或者以 * 為結尾,例如 http://foo*。當尾端是 * 時,會將內容套用至其 URI 開頭為 http://foo 的任何 webTarget 物件。
  • 如果 server.xml 檔中有多個 webTarget 元素符合該 URI,則完全相符項會先套用,再來是套用萬用字元相符項(依 URI 排序)。
  • 比對內容名稱時,不區分大小寫。
  • 可以使用所提供的任何 JAX-RS 內容名稱與值。如果要尋找配置內容的簡短名稱,請參閱 webTarget JAX-RS 用戶端內容

如果要在 JAX-RS 2.0 應用程式中,以程式設計方式來配置內容,請執行下列動作:

  • 利用 com.ibm.ws.jaxrs.client.connection.timeout 用戶端內容和 com.ibm.ws.jaxrs.client.receive.timeout 用戶端內容來設定逾時值。
    • com.ibm.ws.jaxrs.client.connection.timeout
      javax.ws.rs.client.ClientBuilder cb = ClientBuilder.newBuilder();
              cb.property("com.ibm.ws.jaxrs.client.connection.timeout", "1000");
              Client c = cb.build();
    • com.ibm.ws.jaxrs.client.receive.timeout
      javax.ws.rs.client.ClientBuilder cb = ClientBuilder.newBuilder();
              cb.property("com.ibm.ws.jaxrs.client.receive.timeout", "1000");
              Client c = cb.build();
    提示: 逾時內容的值是毫秒,類型必須是 long 或 int。如果值的類型無效,會顯示下列訊息:
    CWWKW0700E: 您在 JAX-RS 用戶端的 com.ibm.ws.jaxrs.client.receive.timeout 內容中指定的逾時值 {0} 無效。值會設為預設值 30000。{3}
  • 使用下列用戶端內容,以支援用戶端 Proxy:
    ClientBuilder cb = ClientBuilder.newBuilder();
    cb.property("com.ibm.ws.jaxrs.client.proxy.host", "hostname");
    cb.property("com.ibm.ws.jaxrs.client.proxy.port", "8888";);
    cb.property("com.ibm.ws.jaxrs.client.proxy.type", "HTTP");
    
    Client c = cb.build();
    • com.ibm.ws.jaxrs.client.proxy.host
    • com.ibm.ws.jaxrs.client.proxy.port
      提示: Proxy 伺服器埠值的類型必須是 int。預設值是 80。如果值類型無效,會顯示下列訊息:
      CWWKW0701E: 您在「JAX-RS 用戶端」上的 com.ibm.ws.jaxrs.client.proxy.port 內容中指定的 Proxy 伺服器埠值 {0} 無效。值會設為預設值 80。{3}
    • com.ibm.ws.jaxrs.client.proxy.type
      提示: Proxy 伺服器類型的值必須是 HTTP 或 SOCKS。預設值為 HTTP。如果 Proxy 伺服器的類型無效,會顯示下列訊息:
      CWWKW0702E: 您在「JAX-RS 用戶端」上的 com.ibm.ws.jaxrs.client.proxy.type 內容中指定的 Proxy 伺服器類型值 {0} 無效。值會設為預設值 HTTP。{3}
  • 使用 com.ibm.ws.jaxrs.client.ltpa.handler 用戶端內容來設定 SSO Cookie,並將值設為 true。
    ClientBuilder cb = ClientBuilder.newBuilder();
            Client c = cb.build();
            c.property("com.ibm.ws.jaxrs.client.ltpa.handler", "true");
    如果您想在 JAX-RS 2.0 中使用 Secure Sockets Layer (SSL) 功能,則需要啟用 ssl-1.0 或 appSecurity-2.0 特性。若要發揮 LTPA 記號的功能,則需要 appSecurity-2.0 特性。

    如需如何配置環境,讓 JAX-RS 2.0 用戶端透過 IHS 來與 SSL 搭配執行的相關資訊,請參閱配置 IBM® HTTP Server SSL 支援

    註: ssl-1.0 特性是 appSecurity-2.0 特性的子特性。如果您啟用 jaxrsClient-2.0 特性和 ssl-1.0 特性,便會自動啟用 appSecurity-2.0 特性。
  • 使用 com.ibm.ws.jaxrs.client.ssl.config 用戶端內容,來設定 server.xml 的 SSL 參照 ID。
    ClientBuilder cb = ClientBuilder.newBuilder();
            cb.property("com.ibm.ws.jaxrs.client.ssl.config", "mySSLRefId");
            Client c = cb.build();
    如需從 IHS 金鑰檔擷取憑證,將它新增至 Liberty JKS 檔來建立信任的相關資訊,請參閱建立在 SSL 信號交換期間鑑別 Web 伺服器時所需的金鑰資料庫檔案和憑證
    註: server.xml 中的配置顯示如下:
    <ssl id="mySSLRefId" keyStoreRef="clientKeyStore" trustStoreRef="clientTrustStore" />
  • [17.0.0.3 以及更新版本]不以程式設計方式來設定 com.ibm.ws.jaxrs.client.ssl.config 用戶端內容,而改以配置出埠 SSL,使 JAX-RS 2.0 用戶端可以根據 SSL 配置來識別所要使用的出埠 SSL。

    如果要配置出埠 SSL,您可以配置出埠 SSL 過濾器及出埠 SSL 預設值兩者,或是配置這兩個選項中的一個。在實作這些選項時,不論您採取哪種組合,都必須啟用 transportSecurity-1.0 特性。

    • server.xml 檔中啟用 transportSecurity-1.0 特性:
      <featureManager>
          <feature>transportSecurity-1.0</feature>
      </featureManager>
    • 配置出埠 SSL 過濾器,以用來將 SSL 配置指定給目的地主機,或同時指定給目的地主機與目的地埠。
      server.xml 檔中您要更新的配置如下:
      <ssl id="mySSLRefId" keyStoreRef="clientKeyStore"
      trustStoreRef="clientTrustStore">
         <outboundConnection host=”myhost.atdomain.com” port=”9443” />       
         <outboundConnection host=”theotherhost.atdomain.com” port=”8020” 
      /> 
      </ssl>
      <ssl id="defaultSSLConfig" keyStoreRef="defaultKeyStore" >
         <outboundConnection host=”defaulthost.domain.com” />      
      </ssl>
      如需出埠 SSL 過濾器的相關資訊,請參閱SSL 配置的出埠過濾器
    • 配置出埠 SSL 預設值。

      如果不存在任何 SSL 過濾器以用來比對找出出埠連線,則 JAX-RS 用戶端會使用出埠 SSL 預設值。

      server.xml 檔中您要更新的配置如下:
      <sslDefault outboundSSLRef=”mySSLRefId” /> 
      
      <ssl id="mySSLRefId" keyStoreRef="clientKeyStore" 
      trustStoreRef="clientTrustStore"/>      
      
      <ssl id="defaultSSLConfig" keyStoreRef="defaultKeyStore" />
      如需 SSL 出埠預設值的相關資訊,請參閱配置用於出埠通訊的 SSL 設定
  • 利用 com.ibm.ws.jaxrs.client.disableCNCheck 用戶端內容來停用一般名稱檢查。
    ClientBuilder cb = ClientBuilder.newBuilder();
    cb.property("com.ibm.ws.jaxrs.client.disableCNCheck", true);

指示主題類型的圖示 作業主題

檔名:twlp_jaxrs2.0_clientconfig.html