配置 JAX-RS 2.0 用戶端
若為 Java™ API for XML RESTful Web Services 2.0,您可以將用戶端配置成存取 REST 端點。JAX-RS 2.0 推出新的標準化「用戶端 API」,可讓您對遠端 RESTful Web 服務提出 HTTP 要求。
關於這項作業
程序
下一步
建立 JAX-RS 2.0 用戶端之後,您可以配置它,作法是在 server.xml 檔中定義 webTarget 元素,或在用戶端應用程式中以程式設計方式配置內容。
如果要在 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}
- com.ibm.ws.jaxrs.client.connection.timeout
- 使用下列用戶端內容,以支援用戶端 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。
如果您想在 JAX-RS 2.0 中使用 Secure Sockets Layer (SSL) 功能,則需要啟用 ssl-1.0 或 appSecurity-2.0 特性。若要發揮 LTPA 記號的功能,則需要 appSecurity-2.0 特性。ClientBuilder cb = ClientBuilder.newBuilder(); Client c = cb.build(); c.property("com.ibm.ws.jaxrs.client.ltpa.handler", "true");
如需如何配置環境,讓 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。
如需從 IHS 金鑰檔擷取憑證,將它新增至 Liberty JKS 檔來建立信任的相關資訊,請參閱建立在 SSL 信號交換期間鑑別 Web 伺服器時所需的金鑰資料庫檔案和憑證。ClientBuilder cb = ClientBuilder.newBuilder(); cb.property("com.ibm.ws.jaxrs.client.ssl.config", "mySSLRefId"); Client c = cb.build();
註: server.xml 中的配置顯示如下:<ssl id="mySSLRefId" keyStoreRef="clientKeyStore" trustStoreRef="clientTrustStore" />
不以程式設計方式來設定 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 過濾器的相關資訊,請參閱SSL 配置的出埠過濾器。<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 過濾器以用來比對找出出埠連線,則 JAX-RS 用戶端會使用出埠 SSL 預設值。
server.xml 檔中您要更新的配置如下:
如需 SSL 出埠預設值的相關資訊,請參閱配置用於出埠通訊的 SSL 設定。<sslDefault outboundSSLRef=”mySSLRefId” /> <ssl id="mySSLRefId" keyStoreRef="clientKeyStore" trustStoreRef="clientTrustStore"/> <ssl id="defaultSSLConfig" keyStoreRef="defaultKeyStore" />
- 在 server.xml 檔中啟用 transportSecurity-1.0 特性:
- 利用 com.ibm.ws.jaxrs.client.disableCNCheck 用戶端內容來停用一般名稱檢查。
ClientBuilder cb = ClientBuilder.newBuilder(); cb.property("com.ibm.ws.jaxrs.client.disableCNCheck", true);