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 ]

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

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

protocol-option-string
[ http-option-list]
[, soap-option-list ]

http-option-list : 
HTTP(
[ CH[UNK]={ ON | OFF | AUTO } ]
[; VER[SION]={ 1.0 | 1.1 };kto=number-of-seconds ]
[REDIR(COUNT=count, STATUS=status-list)
)

 soap-option-list : 
SOAP(OP[ERATION]=soap-operation-name)

パラメータ名は、データベース識別子に対するルールに従って付けてください。パラメータ名は、有効な 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: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	証明書自体
certificate_name	cert_name	データベースに保存される証明書の名前
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;kto=number-of-seconds )' (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 が使用される

kto=number-of-seconds キープアライブタイムアウト条件 (kto) を指定して、Web クライアントプロシージャがキープアライブ HTTP/HTTPS 接続をインスタンス化し、一定期間キャッシュできるようにします。HTTP キープアライブ接続をキャッシュするには、HTTP バージョンを 1.1 に設定し、kto をゼロ以外の値に設定する必要があります。kto は、HTTPS 接続の場合、特に HTTP と HTTPS の接続のパフォーマンスに大きな差がある場合に使用すると効果があります。データベース接続でキャッシュできるのは 1 つのキープアライブ HTTP 接続だけです。同じ URI を使用する Web クライアントプロシージャへのその後の呼び出しでは、キープアライブ接続が再利用されます。このため、実行する Web クライアント呼び出しに含まれる URI のスキーマ、宛先ホスト、ポートが、キャッシュされた URI と一致することが必要です。また、HEADER 句で Connection:close を指定しないでください。kto が指定されないか、ゼロに設定されている場合、HTTP/HTTPS 接続はキャッシュされません。

'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-string 設定を 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 要求へのパラメータは、常に要求本文にバンドルされます。

ユーザ本人が所有する関数を作成するには、CREATE PROCEDURE システム権限が必要です。

他のユーザが所有する関数を作成するには、CREATE ANY PROCEDURE または CREATE ANY OBJECT のシステム権限が必要です。

外部関数を作成するには、CREATE EXTERNAL REFERENCE システム権限が必要です。

テンポラリ関数の作成には権限は必要ありません。

オートコミット。

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 を渡すことができるようにします。セキュア HTTPS 要求では、データベースに格納されている証明書を使用します。CHUNK モードの転送エンコードをオフにするために、SET 句が使用されます。

CREATE CERTIFICATE client_cert 
FROM FILE 'C:\\Users\\Public\\Documents\\SQL Anywhere 16\\Samples\\Certificates\\rsaroot.crt';

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

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

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

CREATE FUNCTION 文 [Web サービス]

構文

パラメータ

備考

権限

関連する動作

参照

標準と互換性

例