CREATE FUNCTION 文 [Web サービス]

CREATE [ OR REPLACE ] FUNCTION [ owner.]function-name ( [ parameter, ... ] )
RETURNS data-type
URL url-string
[ HEADER header-string ]
[ SOAPHEADER soap-header-string ]
[ TYPE { 
  'HTTP[ :{ GET | POST[:MIME-type ] | PUT[:MIME-type ] | DELETE | HEAD } ]' | 
  'SOAP[:{ RPC | DOC } ]' } ]
[ NAMESPACE namespace-string ]
[ CERTIFICATE certificate-string ]
[ CLIENTPORT clientport-string ]
[ PROXY proxy-string ]
[ SET protocol-option-string ]

url-string :
' { HTTP | HTTPS | HTTPS_FIPS }://[user:password@]hostname[:port][/path]'

parameter :
   [ IN ] parameter-name data-type [ DEFAULT expression ]

パラメーター名は、データベース識別子に対するルールに従って付けてください。パラメーター名は、有効な SQL データ型にします。また、キーワード IN のプレフィクスを付けて、引数が関数に値を提供する式であることを示してください。ただし、関数パラメーターはデフォルトで IN です。

関数を実行するときに、すべてのパラメーターを指定する必要はありません。CREATE FUNCTION 文の中に DEFAULT 値がある場合、不明のパラメーターにデフォルト値を割り当てます。呼び出すときに引数を指定せず、デフォルトも設定されていない場合には、エラーが発生します。

OR REPLACE 句 OR REPLACE を指定すると、新しい関数が作成されるか、同じ名前の既存の関数が置き換えられます。この句によって、関数の定義は変更されますが、既存のパーミッションは保持されます。OR REPLACE 句をテンポラリ関数で使用することはできません。
RETURNS 句 次のいずれかを指定して、SOAP 関数または HTTP 関数の戻り値のデータ型を定義します。
- CHAR
- VARCHAR
- LONG VARCHAR
- TEXT
- NCHAR
- NVARCHAR
- LONG NVARCHAR
- NTEXT
- XML
- BINARY
- VARBINARY
- LONG BINARY
返される値は、HTTP 応答の本文です。HTTP ヘッダー情報は含まれません。ステータス情報などの他の情報が必要な場合は、関数ではなくプロシージャーを使用します。

データ型は HTTP 応答の処理方法には影響しません。
URL 句 URL 句は HTTP または SOAP Web サービスクライアント関数を定義する場合にのみ使用します。URL 句は Web サービスの URI を指定します。オプションのユーザー名とパスワードのパラメーターは、HTTP 基本認証に必要なクレデンシャルとして機能します。HTTP 基本認証は、ユーザーとパスワードの情報を base-64 でエンコードし、HTTP 要求の Authentication ヘッダーに渡します。
HTTPS_FIPS を指定すると、強制的に FIPS 認定ライブラリが使用されます。HTTPS_FIPS を指定したときに、FIPS 認定ライブラリがない場合は、代わりに FIPS 認定ではないライブラリが使用されます。

HTTP:GET タイプの関数の場合、URL 句内および (自動的に生成されて) プロシージャーに渡されたパラメーターからの両方でクエリパラメーターを指定できるようになりました。
URL 'http://localhost/service?parm=1
HEADER 句 HTTP Web サービスクライアント関数を作成する場合は、この句を使用して、HTTP 要求ヘッダーのエントリを追加または変更します。HTTP ヘッダーに指定できるのは印字可能な ASCII 文字のみで、大文字と小文字は区別されません。
SOAPHEADER 句 SOAP Web サービスを関数として宣言する場合は、この句を使用して 1 つ以上の SOAP 要求ヘッダーエントリを指定します。SOAP ヘッダーは、静的定数として宣言したり、代入パラメーターメカニズムを使用して動的に設定したりできます (hd1、hd2 などに IN、OUT、または INOUT パラメーターを宣言)。Web サービス関数では、1 つ以上の IN モード代入パラメーターを定義できますが、INOUT または OUT 代入パラメーターは定義できません。

TYPE 句 TYPE 句は Web サービス要求を行う場合に使用するフォーマットを指定します。SOAP が指定されている場合、または TYPE 句が含まれていない場合は、SOAP:RPC が使用されます。HTTP が指定されている場合は、HTTP:POST が使用されます。

TYPE 句では、HTTP:GET、HTTP:POST、HTTP:PUT の各タイプに MIME タイプを指定できます。MIME タイプ指定は、Content-Type 要求ヘッダーや操作モードの設定に使用することにより、1 つの呼び出しパラメーターのみで要求の本文を設定できます。パラメーターの置換後に Web サービスのストアド関数呼び出しを行う場合は、パラメーターがまったくなくなるか、1 つだけ残される場合があります。Web サービス関数を (置換後に) NULL 値またはパラメーターなしで呼び出すと、本文がなくコンテンツ長が 0 の要求になります。パラメーターの名前と値 (複数のパラメーターが可能) は、HTTP 要求の本文内で URL コード化されます。

一般的な MIME タイプの例を次に示します。

text/plain
text/html
text/xml

TYPE 句のキーワードには次の意味があります。

HTTP:GET デフォルトでは、URL で指定されたパラメーターのエンコード用に、このタイプで MIME タイプ application/x-www-form-urlencoded が使用されます。

たとえば、クライアントが URL http://localhost/WebServiceName?arg1=param1&arg2=param2 から要求を送信すると、次の要求が生成されます。

GET /WebServiceName?arg1=param1&arg2=param2 HTTP/1.1
// <End of Request - NO BODY>

HTTP:POST デフォルトでは、POST 要求の本文で指定されたパラメーターのエンコード用に、このタイプで MIME タイプ application/x-www-form-urlencoded が使用されます。URL パラメーターは、本文に格納されます。

たとえば、クライアントが URL http://localhost/WebServiceName?arg1=param1&arg2=param2 から要求を送信すると、次の要求が生成されます。

POST /WebServiceName HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: 19

arg1=param1&arg2=param2
// <End of Request>

HTTP:PUT HTTP:PUT は HTTP:POST と似ていますが、HTTP 要求メソッドが生成されます。HTTP:PUT タイプには、デフォルトのメディアタイプはありません。

次の例は、put_data.sql サンプルを実行している SQL Anywhere サーバーにデータをアップロードする、汎用のクライアントプロシージャーを設定する方法を示します。

ALTER PROCEDURE CPUT("data" LONG VARCHAR, resnm LONG VARCHAR, mediatype LONG VARCHAR)
    URL 'http://localhost/resource/!resnm'
    TYPE 'HTTP:PUT:!mediatype';

CALL CPUT('hello world', 'hello', 'text/plain' );

HTTP:DELETE サーバーにあるリソースを削除する Web サービスクライアントプロシージャーを設定できます。メディアタイプの指定はオプションです。

次の例は、put_data.sql サンプルを実行している SQL Anywhere サーバーからリソースを削除する、汎用のクライアントプロシージャーを設定する方法を示します。

ALTER PROCEDURE CDEL(resnm LONG VARCHAR, mediatype LONG VARCHAR)
    URL 'http://localhost/resource/!resnm'
    TYPE 'HTTP:DELETE:!mediatype';

CALL CDEL('hello', 'text/plain' );

HTTP:HEAD HEAD メソッドは GET メソッドと同じですが、サーバーは本文を返しません。メディアタイプを指定できます。

ALTER PROCEDURE CHEAD(resnm LONG VARCHAR) URL 'http://localhost/resource/!resnm' TYPE 'HTTP:HEAD'; CALL CHEAD( 'hello' );

SOAP:RPC このタイプは、Content-Type ヘッダーを 'text/xml' に設定します。SOAP 操作と SOAP パラメーターは、SOAP エンベロープの XML ドキュメントにカプセル化されます。
SOAP:DOC このタイプは、Content-Type ヘッダーを 'text/xml' に設定します。SOAP:RPC タイプに似ていますが、より多くのデータ型を送信できます。SOAP 操作と SOAP パラメーターは、SOAP エンベロープの XML ドキュメントにカプセル化されます。

TYPE 句に MIME タイプを指定すると、その MIME タイプに Content-Type ヘッダーが自動的に設定されます。

NAMESPACE 句 SOAP クライアント関数にのみ適用されます。この句は、SOAP:RPC 要求と SOAP:DOC 要求の両方に通常必要なメソッドネームスペースを識別します。要求を処理する SOAP サーバーは、このネームスペースを使用して、SOAP 要求メッセージ本文内のエンティティの名前を解釈します。ネームスペースは、Web サービスサーバーから使用できる SOAP サービスの WSDL (Web Services Description Language) から取得できます。デフォルト値は、関数の URL のオプションのパスコンポーネントの直前までです。

CERTIFICATE 句 安全な (HTTPS) 要求を行うには、HTTPS サーバーで使用される証明書にクライアントがアクセスできる必要があります。必要な情報は、セミコロンで区切られたキー／値のペアの文字列で指定されます。ファイルキーを使用して証明書のファイル名を指定したり、証明書キーを使用してサーバー証明書を文字列で指定したりできます。ファイルキーと証明書キーを一緒に指定することはできません。次のキーを使用できます。

キー	省略形	説明
file		証明書のファイル名
certificate	cert	証明書自体
company	co	証明書で指定された会社
unit		証明書で指定された会社の部署
name		証明書で指定された通称

証明書は、HTTPS サーバーに対する要求、または安全でないサーバーから安全なサーバーにリダイレクトされる可能性がある要求に対してのみ必要です。PEM でフォーマットされた証明書のみがサポートされています。

CLIENTPORT 句 HTTP クライアント関数が TCP/IP を使用して通信するポート番号を示します。この句は、ファイアウォールを介する通信のためのものであり、このような通信にのみおすすめします。ファイアウォールは TCP/UDP ポートに従ってフィルターします。単一のポート番号、ポート番号の範囲、または両方の組み合わせを指定できます。たとえば、CLIENTPORT '85,90-97' を指定できます。
PROXY 句 プロキシサーバーの URI を指定します。クライアントがプロキシを介してネットワークにアクセスする場合に使用します。この句は、関数がプロキシサーバーに接続し、そのプロキシサーバーを介して Web サービスに要求を送信することを示します。

SET 句 HTTP および SOAP のプロトコル固有の動作オプションを指定します。次の表に、サポートされている SET オプションを示します。CHUNK と VERSION は、HTTP プロトコルに適用されます。OPERATION は、SOAP プロトコルに適用されます。この句では、パラメーターの代入がサポートされています。

'HTTP(CH[UNK]=option)' (HTTP または SOAP) このオプションでは、チャンクを使用するかどうかを指定します。チャンクを使用すると、HTTP メッセージを複数の部分に分割できます。可能な値は、ON (常にチャンクを使用)、OFF (チャンクは使用しない)、AUTO (内容が 8196 バイトを超えた場合にのみチャンクを使用、ただし自動生成されたマークアップを除く) です。たとえば、次の SET 句を使用すると、チャンクは有効になります。

SET 'HTTP(CHUNK=ON)'

CHUNK オプションを指定しないときの、デフォルトの動作は AUTO です。チャンクされた要求が AUTO モードのときに、ステータスが 505 (HTTP Version Not Supported) または 501 (Not Implemented) または 411 (Length Required) で失敗した場合、クライアントはチャンクされた転送コーディングなしで要求をリトライします。

チャンクされた転送コーディングによる要求を HTTP サーバーがサポートしない場合は、CHUNK オプションを OFF (チャンクを使用しない) に設定してください。

CHUNK モードは HTTP バージョン 1.1 からサポートされる転送エンコードです。CHUNK を ON に設定する場合、バージョン (VER) が 1.1 に設定される必要がありますが、デフォルトのバージョンとして 1.1 を使用する場合は、VER に何も設定しないでください。

' HTTP(VER[SION]=ver)' (HTTP または SOAP) このオプションでは、HTTP メッセージのフォーマットに使用する HTTP プロトコルのバージョンを指定します。たとえば、次の SET 句は HTTP のバージョンを 1.1 に設定します。

SET 'HTTP(VERSION=1.1)'

可能な値は 1.0 と 1.1 です。VERSION が指定されていない場合は、次のようになります。

CHUNK が ON に設定された場合、1.1 が HTTP バージョンとして使用される
CHUNK が OFF に設定された場合、1.0 が HTTP バージョンとして使用される
CHUNK が AUTO に設定された場合、クライアントが CHUNK モードで送信しているかどうかによって 1.0 か 1.1 が使用される

'REDIR(COUNT=count, STATUS=status-list)' (HTTP または SOAP) 302 Found および 303 See Other などの HTTP 応答ステータスコードを使用して、特に HTTP POST を実行した後に Web アプリケーションを新しい URI にリダイレクトします。たとえば、クライアント要求は次のようにすることができます。

GET /people/alice HTTP/1.1 Host: www.example.com Accept: text/html, application/xhtml+xml Accept-Language: en, de

web サーバー応答は次のようにすることができます。

HTTP/1.1 302 Found
Location: http://www.example.com/people/alice.en.html

応答では、クライアントは別の HTTP 要求を新しい URI に送信します。REDIR オプションを使用して、許可されるリダイレクションの最大数および自動的にリダイレクトする HTTP 応答ステータスコードを制御できます。

たとえば、SET 'REDIR(count=3, status=301,307)'では、最大制限の 3 リダイレクションおよび 301 と 307 ステータスのリダイレクションが可能です。302 や 303 などの他のリダイレクションステータスコードが受信されると、エラーが発効されます (SQLCODE -983)。

デフォルトのリダイレクション制限 count は 5 です。デフォルトでは、HTTP クライアントプロシージャーがすべての HTTP リダイレクションステータスコード (301、302、303、307) に応答して自動的にリダイレクトします。すべてのリダイレクションステータスコードを許可しないようにするには、SET REDIR(COUNT=0)を使用します。このモードでは、リダイレクション応答はエラーになりません (SQLCODE -983)。その代わりに、HTTP ステータスおよび応答ヘッダーによって結果セットが返されます。これにより、呼び出し側は Location ヘッダーに含まれる URI に基づいて、条件付きで要求を再発行できます。

303 See Other ステータスを受信する POST HTTP メソッドを指定する Web サービスプロシージャーは、GET HTTP メソッドを使用してリダイレクト要求を発行します。

Location ヘッダーには、絶対パスまたは相対パスのいずれかを含むことができます。どちらも HTTP クライアントプロシージャーによって処理されます。このヘッダーには、クエリパラメーターを含めることもでき、これらのパラメーターはリダイレクトされたロケーションに転送されます。たとえば、ヘッダーに次のようなパラメーターが含まれる場合、後続の GET または POST にこれらのパラメーターが含まれます。

Location: alternate_service?a=1&b=2

上の例では、クエリパラメーターはa=1&b=2です。

'SOAP(OP[ERATION]=soap-operation-name)' (SOAP のみ) このオプションでは、SOAP 操作の名前を指定します (作成しているプロシージャーの名前と異なる場合)。OPERATION の値は、リモートプロシージャーコールの名前に似ています。たとえば、login という SOAP 操作を呼び出す accounts_login というプロシージャーを作成する場合は、次のように指定します。

CREATE FUNCTION accounts_login( name LONG VARCHAR, pwd LONG VARCHAR ) SET 'SOAP(OPERATION=login)';

OPERATION オプションを指定しない場合、SOAP 操作の名前は、作成するプロシージャーの名前と一致する必要があります。

複数の protocol-option 設定を 1 つの SET 句で組み合わせると、次の文のようになります。

CREATE FUNCTION accounts_login( 
      name LONG VARCHAR, 
      pwd LONG VARCHAR )
   SET 'HTTP ( CHUNK=ON; VERSION=1.1 ), SOAP( OPERATION=login )' 
   ...

CREATE FUNCTION 文は、データベースに Web サービス関数を作成します。所有者名を指定すれば、別のユーザーに対する関数を作成できます。

パラメーター値は、要求の一部として渡されます。使用される構文は、要求のタイプによって決まります。HTTP:GET の場合、パラメーターは URL の一部として渡されます。HTTP:POST 要求の場合、値は要求の本文に置かれます。SOAP 要求へのパラメーターは、常に要求本文にバンドルされます。

RESOURCE 権限。

DBA 権限 (Java 関数を含む外部関数に必要)。

オートコミット。

SQL/2008 ベンダー拡張。
Transact-SQL Adaptive Server Enterprise によってサポートされません。

次の文は、localhost 上で実行されている get_picture サービスからイメージを返す cli_test1 という名前の関数を作成します。

CREATE FUNCTION cli_test1( image LONG VARCHAR )
RETURNS LONG BINARY
URL 'http://localhost/get_picture' 
TYPE 'HTTP:GET';

次の文は、URL http://localhost/get_picture?image=widget の HTTP 要求を作成します。

SELECT cli_test1( 'widget' );

次の文は代入パラメーターを使用して、入力パラメーターとして要求 URL を渡すことができるようにします。CHUNK モードの転送エンコードをオフにするために、SET 句が使用されます。

CREATE FUNCTION cli_test2( image LONG VARCHAR, myurl LONG VARCHAR )
RETURNS LONG BINARY
URL '!myurl' 
TYPE 'HTTP:GET'
SET 'HTTP(CH=OFF)'
HEADER 'ASA-ID';

次の文は、URL http://localhost/get_picture?image=widget の HTTP 要求を作成します。

CREATE VARIABLE a_binary LONG BINARY
a_binary = cli_test2('widget', 'http://localhost/get_picture');
SELECT a_binary;

CREATE FUNCTION 文 [Web サービス]

構文

パラメーター

備考

パーミッション

関連する動作

参照

標準と互換性

例