HTTP 功能概觀

基礎函數是根據提出 HTTP 要求時所使用的 三個 維度來命名。

• 第一個維度是 HTTP 作業。 有 5 個不同的 HTTP 作業 :GET、PUT、POST、 PATCH及 DELETE。
• 第二個維度是用於傳送及傳回資料的資料類型。 有兩個替代方案 :BLOB 和 CLOB 的隱含值。
• 第三個維度指出是否應該使用函數的詳細版本。 非詳細函數是純量函數。 詳細函數是傳回單一列的表格函數，其中包括從 HTTP 伺服器傳送的傳回標頭資訊。 標頭資訊格式化為 JSON。

下表彙總函數。

這些 HTTP 函數會傳遞參數，指出要存取的 HTTP 伺服器、HTTP 標頭的設定，以及要傳送至伺服器的任何資料。 每一個 HTTP 函數的參數都類似。

• 第一個參數是用來存取伺服器的 URL。
• 最後一個參數是字串，指出要在要求上使用的選項。 這些選項包括 HTTP 標頭的設定。 字串是具有下列格式的 JSON 物件:

  {"option1":"option-setting1","option2":"option-setting2"}

部分其他 HTTP 函數是用於處理 HTTP 要求的公用程式函數。

此程序要求使用者有權建立 /home/javaTrustStore 目錄，並且有權讀取 cacerts 檔案。

-- The following SQL script generates a KDB trust store from a Java trust  
-- store using an intermediate JKS trust store.  The IFS directory and  
-- name of the KDB trust store are set in the NEW_TRUST_DIRECTORY and 
-- NEW_TRUST_STORE variables below. 
--  
-- Create an SQL schema to contain temporary variables. 
-- The user must have permission to create a schema.  
-- 
CREATE SCHEMA FROM_JAVA_TRUST_STORE;
SET SCHEMA FROM_JAVA_TRUST_STORE;
SET PATH CURRENT PATH, FROM_JAVA_TRUST_STORE;

--
-- Define global variables for parameters to the procedure for generating new trust store. 
-- 

-- Specify the IFS directory to use for the new trust store.
-- In this example, we use /home/javaTrustStore
-- The user must have *W authority to /home in order to create this  
-- directory.  
CREATE OR REPLACE VARIABLE   NEW_TRUST_DIRECTORY VARCHAR(80) CCSID 37;
SET NEW_TRUST_DIRECTORY='/home/javaTrustStore'; 

-- Specify the name of the new trust store name
-- In this example, the name is fromJava.KDB
CREATE OR REPLACE VARIABLE   NEW_TRUST_STORE VARCHAR(80) CCSID 37;
SET NEW_TRUST_STORE = NEW_TRUST_DIRECTORY CONCAT '/fromJava.KDB'; 

-- Specify the password for the trust store.  This
-- should be changed to keep the new trust store secure. 
CREATE OR REPLACE VARIABLE   NEW_TRUST_STORE_PASSWORD VARCHAR(80) CCSID 37;
SET NEW_TRUST_STORE_PASSWORD= 'abc123';

-- Specify the Java trust store to use. 
CREATE OR REPLACE VARIABLE   JAVA_TRUST_STORE VARCHAR(80) CCSID 37;
SET JAVA_TRUST_STORE='/QOpenSys/QIBM/ProdData/JavaVM/jdk80/64bit/jre/lib/security/cacerts';

-- Specify the Java trust store password.  The default password is changeit.
-- If the password has been changed on the system, the correct value will need to be used. 
CREATE OR REPLACE VARIABLE   JAVA_TRUST_STORE_PASSWORD VARCHAR(80) CCSID 37; 
SET JAVA_TRUST_STORE_PASSWORD = 'changeit';

-- Specify the name of a temporary JKS format TRUST STORE.  
-- In this example, jksExport is used.
CREATE OR REPLACE VARIABLE JKS_TRUST_STORE VARCHAR(80) CCSID 37; 
SET JKS_TRUST_STORE = NEW_TRUST_DIRECTORY CONCAT '/jksExport';

-- Specify the password of the temporary JKS format TRUST STORE. 
-- In this example, xyz789 is used as the password.
CREATE OR REPLACE VARIABLE JKS_TRUST_STORE_PASSWORD VARCHAR(80) CCSID 37; 
SET JKS_TRUST_STORE_PASSWORD = 'xyz789' ;


-- Step 1.  Use QCMDEXC and QSH and mkdir to create a directory in which 
--          to save the new store file
CALL QSYS2.QCMDEXC( 'QSH CMD(''mkdir ' CONCAT NEW_TRUST_DIRECTORY CONCAT ''')');


-- Step 2.  Use QCMDEXC and QSH to run the keytool command to export 
--          the default java certificate store in PKCS12 format
CALL QSYS2.QCMDEXC(
   'QSH CMD(''keytool -importkeystore ' CONCAT
   ' -srcstorepass ' CONCAT JAVA_TRUST_STORE_PASSWORD CONCAT
   ' -srckeystore ' CONCAT JAVA_TRUST_STORE CONCAT
   ' -destkeystore ' CONCAT JKS_TRUST_STORE CONCAT
   ' -srcstoretype JKS -deststoretype PKCS12 ' CONCAT 
   ' -deststorepass ' CONCAT JKS_TRUST_STORE_PASSWORD CONCAT ''')');


-- Step 3.  Create an SQL procedure that will call the QSYS/QYMKIMPK API to 
--          create a keystore from the PKCS12 keystore.  A SQL7909 warning from
--          this step can be ignored. 
CREATE OR REPLACE PROCEDURE ImportKeyStore(
     STOREPATH CHAR(100) CCSID 37, 
     STOREPATHLEN INT,  
     STOREFORMAT CHAR(9) CCSID 37, 
     STOREPASSWORD CHAR(100) CCSID 37,
     STOREPASSWORDLEN INT,   
     STOREPASSWORDCCSID INT,    
     IMPORTPATH CHAR(100) CCSID 37,     
     IMPORTPATHLEN INT,     
     IMPORTFORMAT CHAR(9) CCSID 37,  
     IMPORTVERSION CHAR(11) CCSID 37,   
     IMPORTPASSWORD CHAR(100) CCSID 37,   
     IMPORTPASSWORDLEN INT,     
     IMPORTPASSWORDCCSID INT,     
     ERRORCODE CHAR(100) FOR BIT DATA) 
    LANGUAGE C PARAMETER STYLE GENERAL EXTERNAL NAME 'QSYS/QYKMIMPK';

-- Step 4.  Call the SQL procedure to call the QSYS/QYKMIMPK API to 
--          create the new keystore to be used. 
CALL IMPORTKEYSTORE(
  STOREPATH => NEW_TRUST_STORE, 
  STOREPATHLEN => LENGTH(NEW_TRUST_STORE), 
  STOREFORMAT => 'OBJN0100',	            
  STOREPASSWORD => NEW_TRUST_STORE_PASSWORD, 
  STOREPASSWORDLEN => LENGTH(NEW_TRUST_STORE_PASSWORD), 
  STOREPASSWORDCCSID => 37, 
  IMPORTPATH => JKS_TRUST_STORE, 
  IMPORTPATHLEN => LENGTH(JKS_TRUST_STORE), 
  IMPORTFORMAT => 'OBJN0100', 
  IMPORTVERSION => '*PKCS12V3 ',
  IMPORTPASSWORD => JKS_TRUST_STORE_PASSWORD,
  IMPORTPASSWORDLEN => LENGTH(JKS_TRUST_STORE_PASSWORD), 
  IMPORTPASSWORDCCSID => 37, 
  ERRORCODE => X'00000000000000000000000000000000000000000000000000000000000000');

-- Use the new trust store to verify it works.
-- This step assumes that the system has a connection to the internet and that
-- a network firewall is not interposing its own TLS certificate on the connection.
values http_get(
   URL => 'https://www.ibm.com/support/pages/sites/default/files/inline-files/xmldoc.xml',  
   OPTIONS => '{"sslCertificateStoreFile":"' CONCAT NEW_TRUST_STORE CONCAT '"}'); 

-- Cleanup the schema 
DROP SCHEMA FROM_JAVA_TRUST_STORE;

發生錯誤時，請使用函數的 VERBOSE 格式來取得錯誤的其他相關資訊。 這些函數會在 RESPONSE_MESSAGE 直欄中傳回錯誤資訊。 例如，下列呼叫將傳回找不到頁面的相關資訊錯誤。

SELECT * FROM TABLE(QSYS2.HTTP_GET_VERBOSE('http://www.w3.org/notfound.html','')); 

下列是使用 HTTP 函數時可能遇到的一些常見錯誤。

• 如果現行系統沒有網際網路存取權，可能會發生下列錯誤。

  AXISC ERROR  : HTTPTransportException: Channel I/O operation timed
    out. Failed to open connection to server at host 192.168.1.233 and port 80. 
    Error is 3447 - A remote host did not respond within the timeout period.

• 如果系統上未配置 DNS ，可能會發生下列錯誤。

  AXISC ERROR  : AxisTransportException: Cannot open a channel to the
    remote end. Failed to open connection to server at host XXXXX and port 80.
    Error is 3401 - Permission denied 

• 如果正在使用 https ，則連線會使用 SSL。 為了適當地運作，伺服器必須使用 sslCertificateStoreFile 選項所指定之憑證儲存庫中的憑證管理中心所簽署的憑證。

  AXISC ERROR  : HTTPTransportException: Cannot initialize a channel
    to the remote end. Failed to establish SSL connection to server, the operation
    gsk_secure_soc_init() failed. GSKit Error is 6000 - Certificate is not signed 
    by a trusted certificate authority. 

• 必須使用 basicAuth 選項來指定「HTTP 鑑別」。 嘗試在 URL 上使用基本鑑別 (例如 https://userid:password@example.com/login) 會導致下列錯誤。

   AXISC ERROR  : AxisTransportException: Cannot open a channel to the 
    remote end. Failed to open connection to server at host userid and port 0.
    Error is 3421 - Address not available.