CREATE QUEUE (Transact-SQL)

適用対象: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 }

引数

database_name (オブジェクト)

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

schema_name (オブジェクト)

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

queue_name

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

STATUS(キュー)

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

RETENTION

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

Note

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

ACTIVATION

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

STATUS(起動)

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

PROCEDURE_NAME = <手続き>

このキュー内のメッセージを処理するために開始するストアドプロシージャの名前を指定します。この値は 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 filegroup | [DEFAULT]

このキューを作成する SQL Server ファイルグループを指定します。 ファイルグループを識別するためにファイルグループパラメータを使うか、サービスブローカーデータベースのデフォルトファイルグループとしてDEFAULT識別子を使うことができます。この条項の文脈では、 DEFAULT はキーワードではなく、識別子として区切られなければなりません。ファイルグループを指定しない場合、キューの作成ではデータベースの既定のファイルグループが使用されます。

解説

キューは SELECT ステートメントの対象にすることができますが、ただし、キューの内容はサービスブローカーの会話で動作する文( SEND、 RECEIVE、 END CONVERSATIONなど)でのみ変更可能です。キューは INSERT、 UPDATE、 DELETE、またはTRUNCATE文の対象にはなりません。

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

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

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

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

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

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

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

列名	データ型	説明
`status`	tinyint	メッセージの状態。 RECEIVE文はステータスが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`=空 `N`=なし `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];

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-06-24