CREATE QUEUE (Transact-SQL)

[アーティクル]
04/05/2024

適用対象: SQL Server Azure SQL Managed Instance

データベースに新しいキューを作成します。キューにはメッセージが格納されます。サービス用のメッセージを受信すると、そのメッセージは Service Broker によって、サービスに関連付けられているキューに格納されます。

構文

CREATE QUEUE <object>
   [ WITH
     [ STATUS = { ON | OFF } [ , ] ]
     [ RETENTION = { ON | OFF } [ , ] ]
     [ ACTIVATION (
         [ STATUS = { ON | OFF } , ]
           PROCEDURE_NAME = <procedure> ,
           MAX_QUEUE_READERS = max_readers ,
           EXECUTE AS { SELF | 'user_name' | OWNER }
            ) [ , ] ]
     [ POISON_MESSAGE_HANDLING (
         [ STATUS = { ON | OFF } ] ) ]
    ]
     [ ON { filegroup | [ DEFAULT ] } ]
[ ; ]

<object> ::=
{ database_name.schema_name.queue_name | schema_name.queue_name | queue_name }

<procedure> ::=
{ database_name.schema_name.stored_procedure_name | schema_name.stored_procedure_name | stored_procedure_name }

Note

SQL Server 2014 (12.x) 以前のバージョンの Transact-SQL 構文を確認するには、以前のバージョンのドキュメントを参照してください。

引数

database_name (オブジェクト)

新しいキューを作成するデータベースの名前です。 database_name には、既存のデータベース名を指定する必要があります。 database_name が指定されていない場合、キューは現在のデータベースに作成されます。

schema_name (オブジェクト)

新しいキューが所属するスキーマの名前を指定します。省略すると、ステートメントを実行するユーザーの既定のスキーマが使用されます。 CREATE QUEUE ステートメントが、sysadmin 固定サーバーロールのメンバー、または database_name で指定されるデータベース内の db_dbowner または db_ddladmin 固定データベースロールのメンバーによって実行される場合、schema_name には、現在の接続のログインに関連付けられているスキーマ以外のスキーマを指定できます。それ以外の場合、schema_name には、ステートメントを実行するユーザーの既定のスキーマを指定する必要があります。

queue_name

作成するキューの名前を指定します。この名前は、SQL Server 識別子のガイドラインに従っている必要があります。

STATUS (Queue)

キューが使用可能 (ON) か、使用不可能 (OFF) かを指定します。キューが使用不可能な場合、キューにメッセージを追加したり、キューからメッセージを削除することはできません。 ALTER QUEUE ステートメントによってキューが使用可能になるまでキューにメッセージが届かないようにする場合は、キューを使用不可能な状態で作成できます。この句を省略すると、既定値の ON が使用され、キューは使用可能になります。

RETENTION

キューのメッセージ保有期間の設定を指定します。 RETENTION = ON の場合、このキューを使用するメッセージ交換で送信または受信されるすべてのメッセージは、メッセージ交換が終了するまでキュー内に保有されます。このことにより、監査目的でメッセージを保有したり、エラーが発生した場合に補正するトランザクションを実行することができます。この句を指定しない場合、保有期間の設定は既定で OFF になります。

Note

RETENTION = ON を設定すると、パフォーマンスが低下する場合があります。この設定はアプリケーションに必要な場合にのみ使用してください。

ACTIVATION

このキュー内のメッセージを処理するために開始する必要があるストアドプロシージャの情報を指定します。

STATUS (Activation)

Service Broker によってストアドプロシージャを開始するかどうかを指定します。 STATUS = ON の場合は、現在実行中のプロシージャの数が MAX_QUEUE_READERS より少なく、ストアドプロシージャによるメッセージの受信よりも早くメッセージがキューに到着する場合に、PROCEDURE_NAME で指定されるストアドプロシージャがキューによって開始されます。 STATUS = OFF の場合は、キューによってストアドプロシージャが開始されません。この句を指定しない場合、既定値は ON になります。

PROCEDURE_NAME = <procedure>

このキュー内のメッセージを処理するために開始するストアドプロシージャの名前を指定します。この値は SQL Server の識別子にする必要があります。

database_name (プロシージャ) は、ストアドプロシージャを含むデータベースの名前です。

schema_name (プロシージャ) は、ストアドプロシージャを含むスキーマの名前です。

procedure_name は、ストアドプロシージャの名前です。

MAX_QUEUE_READERS =max_readers

キューで同時に開始する、アクティブ化ストアドプロシージャの最大インスタンス数を指定します。 max_readers の値には、0 から 32767 の数値を指定する必要があります。

EXECUTE AS

アクティブ化ストアドプロシージャを実行する SQL Server データベースユーザーアカウントを指定しますキューによってストアドプロシージャが開始されたときに、SQL Server ではこのユーザーの権限を確認できる必要があります。ドメインユーザーの場合は、プロシージャが開始されるかアクティブ化が失敗したとき、サーバーがドメインに接続している必要があります。 SQL Server ユーザーの場合は、サーバーで常に権限を確認できます。

SELF は、現在のユーザーとしてストアドプロシージャを実行することを指定します。 (対象の CREATE QUEUE ステートメントを実行しているデータベースプリンシパル。)

'user_name' は、ストアドプロシージャを実行するユーザーの名前を指定します。 user_name パラメーターには、SQL Server 識別子として有効な SQL Server ユーザーを指定する必要があります。現在のユーザーは、指定した user_name に対して IMPERSONATE 権限を保持している必要があります。

OWNER は、キューの所有者としてストアドプロシージャを実行することを指定します。

POISON_MESSAGE_HANDLING

キューに対する有害なメッセージの処理が有効かどうかを指定します。既定値は ON です。

有害なメッセージの処理が OFF に設定されているキューは、トランザクションのロールバックが連続して 5 回実行されても無効になりません。これにより、カスタムの有害なメッセージの処理システムをアプリケーションで定義できます。

ON ファイルグループ | [DEFAULT]

このキューを作成する SQL Server ファイルグループを指定します。 filegroup パラメーターを使用してファイルグループを指定するか、DEFAULT 識別子を使用して Service Broker データベースの既定のファイルグループを指定することができます。この句のコンテキストでは、DEFAULT はキーワードとして扱われないため、識別子として区切り記号で区切る必要があります。ファイルグループを指定しない場合、キューの作成ではデータベースの既定のファイルグループが使用されます。

解説

キューは SELECT ステートメントの対象にすることができますが、キューの内容を変更するには、SEND、RECEIVE、END CONVERSATION など、Service Broker のメッセージ交換で動作するステートメントを使用する必要があります。キューは、INSERT、UPDATE、DELETE、または TRUNCATE ステートメントの対象にすることはできません。

キューは一時オブジェクトとして指定できません。したがって、 # で始まるキューの名前は無効になります。

キューを非アクティブ状態で作成した場合、サービス用のインフラストラクチャを配置してから、キューでメッセージを受信することができます。

キューにメッセージがない場合、Service Broker によってアクティブ化ストアドプロシージャは停止されません。アクティブ化ストアドプロシージャは、しばらくの間キューに使用できるメッセージがないときには終了してください。

アクティブ化ストアドプロシージャの権限は、キューの作成時ではなく、Service Broker によってストアドプロシージャが開始されるときに確認されます。 CREATE QUEUE ステートメントでは、EXECUTE AS 句で指定したユーザーに、PROCEDURE NAME 句で指定したストアドプロシージャの実行権限があるかどうかは確認されません。

キューが使用できない場合、Service Broker では、データベースの転送キュー内にあるキューを使用するサービスのメッセージが保持されます。カタログビュー sys.transmission_queue により、転送キューのビューが提供されます。

キューはスキーマが所有するオブジェクトです。キューは、sys.objects カタログビューに表示されます。

次の表は、キューの列の一覧です。

列名	データ型	説明
`status`	tinyint	メッセージの状態。 RECEIVE ステートメントでは、status が 1 のメッセージがすべて返されます。メッセージの保有が指定されている場合は、status が 0 に設定されます。メッセージの保有が指定されていない場合は、メッセージがキューから削除されます。キューのメッセージには、次のいずれかの値を含めることができます。 `0`=受信したメッセージを保持 `1`=受け取る準備完了 `2`=まだ完了していない `3`=送信済みメッセージを保持
`priority`	tinyint	このメッセージに割り当てられている優先度レベル。
`queuing_order`	bigint	キュー内のメッセージの順序番号。
`conversation_group_id`	uniqueidentifier	メッセージが属するメッセージ交換グループの識別子。
`conversation_handle`	uniqueidentifier	メッセージが属するメッセージ交換のハンドル。
`message_sequence_number`	bigint	メッセージ交換内でのメッセージのシーケンス番号。
`service_name`	nvarchar(128)	メッセージ交換の対象サービスの名前。
`service_id`	int	メッセージ交換の対象サービスに関する SQL Server オブジェクト識別子。
`service_contract_name`	nvarchar(128)	メッセージ交換が従うコントラクトの名前。
`service_contract_id`	int	メッセージ交換が従うコントラクトに関する SQL Server オブジェクト識別子。
`message_type_name`	nvarchar(128)	メッセージの種類を示すメッセージ型の名前。
`message_type_id`	int	メッセージの種類を示すメッセージ型に関する SQL Server オブジェクト識別子。
`validation`	nchar(2)	メッセージに使用される検証。 `E`=Empty `N`=None `X`=XML
`message_body`	varbinary(max)	メッセージの内容。
`message_enqueue_time`	datetime	メッセージがエンキューされた日時。

アクセス許可

キューを作成する権限では、db_ddladmin 固定データベースロールまたは db_owner 固定データベースロールのメンバー、または sysadmin 固定サーバーロールのメンバーを使用します。

キューに対する REFERENCES 権限は、既定ではキューの所有者、db_ddladmin 固定データベースロールまたは db_owner 固定データベースロールのメンバー、または sysadmin 固定サーバーロールのメンバーに与えられています。

キューに対する RECEIVE 権限は、既定ではキューの所有者、db_owner 固定データベースロールのメンバー、または sysadmin 固定サーバーロールのメンバーに与えられています。

例

A. パラメーターなしでキューを作成する

次の例では、メッセージの受信に使用できるキューを作成します。キューにアクティブ化ストアドプロシージャは指定しません。

CREATE QUEUE ExpenseQueue;

B. 使用できないキューを作成する

次の例では、メッセージの受信に使用できないキューを作成します。キューにアクティブ化ストアドプロシージャは指定しません。

CREATE QUEUE ExpenseQueue WITH STATUS=OFF;

C. キューを作成し、内部アクティブ化情報を指定する

次の例では、メッセージの受信に使用できるキューを作成します。メッセージがキューに格納されると、キューによってストアドプロシージャ expense_procedure が起動されます。このストアドプロシージャは、ユーザー ExpenseUser として実行されます。キューによって、ストアドプロシージャのインスタンスが 5 個まで起動されます。

CREATE QUEUE ExpenseQueue
    WITH STATUS=ON,
    ACTIVATION (
        PROCEDURE_NAME = expense_procedure
        , MAX_QUEUE_READERS = 5
        , EXECUTE AS 'ExpenseUser' );

D. 特定のファイルグループにキューを作成する

次の例では、ファイルグループ ExpenseWorkFileGroup にキューを作成します。

CREATE QUEUE ExpenseQueue
    ON ExpenseWorkFileGroup;

E. 複数のパラメーターでキューを作成する

次の例では、DEFAULT ファイルグループにキューを作成します。このキューは使用不可能な状態になります。メッセージは、それらが属するメッセージ交換が終わるまでキューに保持されます。 ALTER QUEUE を使用してキューを使用できるようにすると、キューによってストアドプロシージャ AdventureWorks2022.dbo.expense_procedure が開始され、メッセージが処理されます。このストアドプロシージャは、CREATE QUEUE ステートメントを実行したユーザーとして実行されます。キューによって、ストアドプロシージャのインスタンスが 10 個まで起動されます。

CREATE QUEUE ExpenseQueue
    WITH STATUS = OFF
      , RETENTION = ON
      , ACTIVATION (
          PROCEDURE_NAME = AdventureWorks2022.dbo.expense_procedure
          , MAX_QUEUE_READERS = 10
          , EXECUTE AS SELF )
    ON [DEFAULT];

CREATE QUEUE (Transact-SQL)

構文

引数

database_name (オブジェクト)

schema_name (オブジェクト)

queue_name

STATUS (Queue)

RETENTION

ACTIVATION

STATUS (Activation)

PROCEDURE_NAME = <procedure>

MAX_QUEUE_READERS =max_readers

EXECUTE AS

POISON_MESSAGE_HANDLING

ON ファイルグループ | [DEFAULT]

解説

アクセス許可

例

A. パラメーターなしでキューを作成する

B. 使用できないキューを作成する

C. キューを作成し、内部アクティブ化情報を指定する

D. 特定のファイルグループにキューを作成する

E. 複数のパラメーターでキューを作成する

フィードバック

フィードバック

その他のリソース

CREATE QUEUE (Transact-SQL)

構文

引数

database_name (オブジェクト)

schema_name (オブジェクト)

queue_name

STATUS (Queue)

RETENTION

ACTIVATION

STATUS (Activation)

PROCEDURE_NAME = <procedure>

MAX_QUEUE_READERS =max_readers

EXECUTE AS

POISON_MESSAGE_HANDLING

ON ファイル グループ | [DEFAULT]

解説

アクセス許可

例

A. パラメーターなしでキューを作成する

B. 使用できないキューを作成する

C. キューを作成し、内部アクティブ化情報を指定する

D. 特定のファイル グループにキューを作成する

E. 複数のパラメーターでキューを作成する

関連するコンテンツ

フィードバック

フィードバック

その他のリソース

ON ファイルグループ | [DEFAULT]

D. 特定のファイルグループにキューを作成する