HTTP 関数の概要

基本関数は、 HTTP リクエストを行うときに使用される 3 つの次元に応じて名前が付けられます。

• 最初のディメンションは、HTTP 操作です。 HTTP ：GET、PUT、POST、 PATCH、DELETEである。
• つ目の次元は、データの送受信に使われるデータ型である。 選択肢は2つある：BLOBとCLOBの暗黙値である。
• 3 番目のディメンションは、関数の詳細バージョンを使用する必要があるかどうかを示します。 非詳細関数はスカラー関数です。 冗長関数は、 HTTP サーバーから送信される戻りヘッダー情報を含む単一行を戻す表関数です。 ヘッダー情報は JSON形式でフォーマットされます。

以下の表は、関数の要約です。

これらの HTTP 関数には、アクセスする HTTP サーバー、HTTP ヘッダーの設定、サーバーに送信する任意のデータを指定するパラメーターを渡します。 各パラメーターは、 HTTP 関数で同様である。

• 第 1 パラメーターは、サーバーへのアクセスに使用する 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. 

• http 認証は basicAuth オプションを使用して指定する必要があります。 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.