CREATE SERVICE 文 [HTTP Web サービス]

CREATE SERVICE service-name
TYPE { 'RAW' | 'HTML' | 'JSON' | 'XML' }
[ URL [PATH] { ON | OFF | ELEMENTS } ]
[ common-attributes ]
[ AS { statement | NULL } ]

common-attributes :
[ AUTHORIZATION { ON | OFF } ]
[ ENABLE | DISABLE ]
[ METHODS 'method,...' ]
[ SECURE { ON | OFF } ]
[ USER { user-name | NULL } ]

method :
DEFAULT
| POST
| GET
| HEAD
| PUT
| DELETE
| NONE
| *

service-name Web サービス名に使用できるのは、任意の順序の英数字文字、またはスラッシュ (/)、ハイフン (-)、アンダースコア (_)、ピリオド (.)、感嘆符 (!)、チルダ (~)、アスタリスク (*) 、アポストロフィ (')、左カッコ (()、右カッコ ()) です。ただし、スラッシュ (/) は、サービス名の先頭または最後の文字には使用できず、2 つ以上連続 (// など) して使用することもできません。
サービス root に名前を付けることができますが、この名前には特別な機能があります。
TYPE 句 各サービスが特定の応答フォーマットを定義する、サービスタイプを識別します。リストされたサービスタイプのいずれかを指定します。デフォルト値はありません。
- 'RAW' 結果セットはフォーマットされずにクライアントに送られます。このサービスを利用するには、すべてのコンテンツのマークアップが明示的に指定されている必要があります。マークアップが付けられた現在のコンテンツを含む複雑な動的コンテンツである JavaScript およびイメージは、オンデマンドで生成できます。sa_set_http_header プロシージャーを使用して Content-Type 応答ヘッダーを設定することにより、メディアタイプを指定できます。すべてのブラウザーでマークアップを text/plaina ではなく HTML として表示するには、HTML マークアップを生成するときに Content-Type ヘッダーを 'text/html' に設定することをおすすめします。
- 'HTML' 結果セットはテーブルまたはビューの HTML 表現で返されます。
- 'JSON' 結果セットは JavaScript Object Notation (JSON) で返されます。JSON サービスは、自動的には JSON 入力を処理しません。(応答内の) データを JSON 形式で表すことのみ行います。JSON は、application/x-www-form-urlencoded がサポートされている POST/PUT メソッドを受け付けます。POST/PUT メソッドで Content-Type: application/json を指定すると、アプリケーションは http_variable('body') を使用して JSON (要求) コンテンツを取得します。SQL Anywhere は自動的には JSON 入力を解析しません。解析するかどうかはアプリケーションによって決まります。JSON の詳細については、 http://www.json.org/を参照してください。
- 'XML' 結果セットは XML として返されます。結果セットがすでに XML の場合、それ以上フォーマットは適用されません。XML でない場合は、XML として自動的にフォーマットされます。代替手段としては、sa_set_http_header プロシージャーを使用して text/xml などの有効な Content-Type を設定した FOR XML RAW 句を使用して、RAW サービスから select を返す方法もあります。

URL 句 URL パスを受け入れるかどうか、受け入れる場合にはどのように処理するかを決定します。URL PATH を指定すると、URL と同じ機能があります。

OFF URL 要求でサービス名に続いてパスを指定できないことを示します。OFF はデフォルト設定です。たとえば、パス要素 /aaa/bbb/ccc のため、次の形式は許可されません。

http://host-name/service-name/aaa/bbb/ccc

Web サービスの作成時に CREATE SERVICE echo URL PATH OFF が指定されたとします。http://localhost/echo?id=1 に似た URL で次の値が生成されます。

HTTP_VARIABLE('id') == 1,
HTTP_HEADER('@HTTPQUERYSTRING') == id=1

ON URL 要求でサービス名に続いてパスを指定できることを示します。URL という名前の専用の HTTP 変数を問い合わせることにより、パスの値が返されます。URL パラメーターを明示的に指定するようにサービスを定義したり、HTTP_VARIABLE 関数を使用して取得したりできます。たとえば、次の形式は許可されます。

http://host-name/service-name/aaa/bbb/ccc

Web サービスの作成時に CREATE SERVICE echo URL PATH ON が指定されたとします。http://localhost/echo/one/two?id=1 に似た URL で次の値が生成されます。

HTTP_VARIABLE('id') == 1,
HTTP_VARIABLE('URL') == one/two,
HTTP_HEADER('@HTTPQUERYSTRING') == id=1

ELEMENTS URL 要求でサービス名に続いてパスを指定できることを示します。URL1、URL2 などの単一のパラメーターキーワードを指定することにより、セグメントでパスが取得されます。各パラメーターは、HTTP_VARIABLE 関数または NEXT_HTTP_VARIABLE 関数を使用して検索できます。これらの繰り返し関数は、可変の数のパス要素を指定できるアプリケーションで使用できます。たとえば、次の形式は許可されます。

http://host-name/service-name/aaa/bbb/ccc

Web サービスの作成時に CREATE SERVICE echo URL PATH ELEMENTS が指定されたとします。http://localhost/echo/one/two?id=1 に似た URL で次の値が生成されます。

HTTP_VARIABLE('id') == 1,
HTTP_VARIABLE('URL1') == one,
HTTP_VARIABLE('URL2') == two,
HTTP_HEADER('@HTTPQUERYSTRING') == id=1

10 個までの要素を取得できます。対応する要素が指定されていない場合は、NULL 値が返されます。上記の例では、対応する要素が指定されていないため、HTTP_VARIABLE('URL3') は NULL を返します。

URL の詳細については、HTTP Web サーバーの参照とクライアント提供の HTTP 変数とヘッダーのアクセスを参照してください。

AUTHORIZATION 句 サービスに接続するときに、ユーザーが基本的な HTTP 認証を通じてユーザー名とパスワードを指定する必要があるかどうかを決定します。デフォルト値は ON です。AUTHORIZATION が OFF の場合、すべてのサービスに AS 句が必要となり、USER 句でユーザーを指定する必要があります。そのユーザーのアカウントとパーミッションを使用して、すべての要求が実行されます。AUTHORIZATION が ON の場合、すべてのユーザーはユーザー名とパスワードを指定する必要があります。オプションとして、USER 句でユーザー名またはグループ名を指定することにより、サービスを使用できるユーザーを制限することもできます。ユーザー名が NULL の場合、既知のユーザーはすべてサービスにアクセスできます。AUTHORIZATION 句を使用すると、Web サービスでデータベース認証とパーミッションを使用して、データベース内のデータへのアクセスを制御できます。
authorization の値が ON の場合、Web サービスに接続しようとしている HTTP クライアントは、基本認証 (RFC 2617) を使用します。基本認証では、ユーザーとパスワードの情報が base-64 エンコーディングを使用して難読化されます。セキュリティを強化するため、HTTPS プロトコルを使用することをおすすめします。
ENABLE 句と DISABLE 句 サービスを使用できるかどうかを指定します。デフォルトでは、サービスの作成時に有効にされます。サービスを作成または変更するときに、ENABLE 句または DISABLE 句を含めることができます。サービスを無効にすると、事実上、サービスがオフラインになります。無効にしたサービスは、後で ENABLE 句を含む ALTER SERVICE 文を使用して有効にできます。無効にされたサービスに対して HTTP 要求を行うと、通常、404 Not Found HTTP ステータスが返されます。

METHODS 句 サービスでサポートされている HTTP メソッドを指定します。有効な値は、DEFAULT、POST、GET、HEAD、PUT、DELETE、NONE です。アスタリスク (*) は、POST、GET、HEAD メソッドを表す省略形として使用できます。これらのメソッドは、RAW、HTML、XML サービスタイプのデフォルトの要求タイプです。すべての HTTP メソッドがすべてのサービスタイプに有効なわけではありません。次の表は、各サービスタイプに適用できる有効な HTTP メソッドの概要を示します。

メソッド値	適用対象のサービス	説明
DEFAULT	すべて	DEFAULT は、指定されたサービスタイプのデフォルトの HTTP メソッドのセットをリセットする場合に使用します。他のメソッド値が存在するリストに含めることはできません。
POST	RAW、HTML、JSON、XML	デフォルトでは有効になっています。
GET	RAW、HTML、JSON、XML	デフォルトでは有効になっています。
HEAD	RAW、HTML、JSON、XML	デフォルトでは有効になっています。
PUT	RAW、HTML、JSON、XML	デフォルトでは有効になっていません。
DELETE	RAW、HTML、JSON、XML	デフォルトでは有効になっていません。
NONE	すべて	NONE は、サービスへのアクセスを無効にするために使用します。
*	RAW、HTML、JSON、XML	'POST,GET,HEAD' と指定することと同じです。

たとえば、次のいずれかの句を使用して、サービスですべての HTTP メソッドタイプがサポートされていることを指定できます。

METHODS '*,PUT,DELETE'
METHODS 'POST,GET,HEAD,PUT,DELETE'

サービスタイプに対する要求タイプのリストをデフォルトにリセットするには、次の句を使用できます。

METHODS 'DEFAULT'

SECURE 句 セキュアリスナーまたは非セキュアリスナーでサービスにアクセスできるかどうかを指定します。ON は、HTTPS 接続のみが受け入れられ、HTTP ポートが受信する接続は HTTPS ポートに自動的にリダイレクトされることを示します。OFF は、Web サーバーの起動時に必要なポートが指定されていると、HTTP 接続と HTTPS 接続の両方が受け入れられることを示します。デフォルト値は OFF です。
USER 句 Web サービス要求を実行するパーミッションを持つデータベースユーザーまたはユーザーのグループを指定します。サービスが AUTHORIZATION OFF で設定されている場合は、USER 句を指定する必要があり、AUTHORIZATION ON で指定する必要があります。(デフォルト) 認証を必要とするサービスに対して HTTP 要求を行うと、401 Authorization Required HTTP 応答ステータスになります。この応答に基づいて、ユーザー ID とパスワードを要求するプロンプトが Web ブラウザーで表示されます。

警告

認証が有効になっている場合 (デフォルト) には、USER 句を指定することを強くおすすめします。指定しないと、すべてのユーザーが認証されます。

USER 句は、サービス要求を処理するのに使用できるデータベースユーザーアカウントを制御します。データベースのアクセスパーミッションは、サービスのユーザーに割り当てられた権限に制限されます。

statement サービスにアクセスしたときに起動する、ストアドプロシージャー呼び出しなどのコマンドを指定します。

statement なしの DISH 以外のサービスに対する HTTP 要求により、URL 内で実行する SQL 式が指定されます。認証が必要ですが、この機能はサーバーを SQL の挿入に対して脆弱にするため、実稼動システムでは使用しないでください。サービス内で文が定義されると、指定された SQL 文はサービスによって実行できる文のみとなります。

通常の Web サービスアプリケーションでは、statement を使用して関数またはプロシージャーを呼び出します。ホスト変数をパラメーターとして渡して、クライアント提供の HTTP 変数にアクセスできます。

次の statement は、AuthenticateUser という名前のプロシージャーに 2 つのホスト変数を渡すプロシージャーコールを示しています。この呼び出しは Web クライアントが user_name および user_password 変数を供給することを仮定しています。

CALL AuthenticateUser ( :user_name, :user_password );

関数またはプロシージャーに渡すホスト変数の詳細については、クライアント提供の HTTP 変数とヘッダーのアクセスを参照してください。

サービス定義は、ISYSWEBSERVICE テーブルに格納され、SYSWEBSERVICE ビューから検査できます。

DBA 権限。

なし

SQL/2008 ベンダー拡張。
Transact-SQL CREATE SERVICE は、XML と RAW タイプに関してのみ Adaptive Server Enterprise でサポートされています。

次の例は、JSON サービスの作成方法を示します。

-xs (http または https) オプションを指定してデータベースサーバーを起動してから、次の SQL 文を実行してサービスを設定します。

CREATE PROCEDURE ListEmployees()
RESULT (
 EmployeeID            integer,
 Surname               person_name_t,
 GivenName             person_name_t,
 StartDate             date,
 TerminationDate       date )
BEGIN
    SELECT EmployeeID, Surname, GivenName, StartDate, TerminationDate 
    FROM Employees 
END;

CREATE SERVICE "jsonEmployeeList"
    TYPE 'JSON'
    AUTHORIZATION OFF
    SECURE OFF
    USER DBA
    AS CALL ListEmployees();

JSON サービスは、AJAX コールバックで簡単に使用できるデータを提供します。

次の SQL 文を実行して、読み取り可能な形式でサービスを提供する HTML サービスを作成します。

CREATE SERVICE "EmployeeList"
    TYPE 'HTML'
    AUTHORIZATION OFF
    SECURE OFF
    USER DBA
    AS CALL ListEmployees();

Web ブラウザーを使用して、http://localhost/EmployeeList に似た URL を使用してサービスにアクセスします。

CREATE SERVICE 文 [HTTP Web サービス]

構文

パラメーター

警告

備考

パーミッション

関連する動作

参照

標準と互換性

例