共用方式為


CREATE QUEUE (Transact-SQL)

適用於:SQL Server Azure SQL 受控執行個體

在資料庫中建立新的佇列。 佇列會儲存訊息。 當服務的訊息到達時,Service Broker 會將訊息放在與服務相關聯的佇列中。

Transact-SQL 語法慣例

語法

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 (object)

這是在其中建立新佇列之資料庫的名稱。 database_name 必須指定現有資料庫的名稱。 未提供 database_name 時,會在目前的資料庫中建立佇列。

schema_name (object)

這是新佇列所屬的結構描述名稱。 結構描述預設為執行陳述式之使用者的預設結構描述。 如果 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。

注意

設定 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 的值必須是在 032767 之間的數字。

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 的佇列將不會在五個連續的交易復原後停用。 這可讓應用程式定義自訂有害訊息處理系統。

ON 檔案群組 | [DEFAULT]

指定這個佇列建立所在的 SQL Server 檔案群組。 您可以利用 filegroup 參數來識別檔案群組,或利用 DEFAULT 識別碼來使用 Service Broker 資料庫的預設檔案群組。 在這個子句的內容中,DEFAULT 不是關鍵字,必須用識別碼來分隔。 當沒有指定任何檔案群組時,佇列會使用資料庫的預設檔案群組。

備註

佇列可以是 SELECT 陳述式的目標。 不過,您只能利用在 Service Broker 交談上運作的陳述式來修改佇列的內容,例如 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 陳述式會傳回 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_ddladmindb_owner 固定資料庫角色的成員,或是 sysadmin 固定伺服器角色的成員。

佇列的 REFERENCES 權限預設為佇列的擁有者、db_ddladmindb_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];