CREATE QUEUE (Transact-SQL)

Область применения: SQL Server Управляемый экземпляр SQL Azure

Создает в базе данных новую очередь. Очереди служат для хранения сообщений. Когда сообщение поступает для службы, Компонент 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 (объект)

Имя базы данных, в которой должна быть создана новая очередь. Параметр database_name должен указывать имя существующей базы данных. Если database_name не указан, в текущей базе данных создается очередь.

schema_name (объект)

Имя схемы, которой принадлежит новая очередь. Значения по умолчанию для схемы по умолчанию текущего пользователя, выполняющего инструкцию. Если инструкция CREATE QUEUE выполняется элементом предопределенной роли сервера sysadmin или элементом предопределенных ролей базы данных db_dbowner или db_ddladmin в базе данных, указанной аргументом database_name, то schema_name может определять схему, не связанную с именем входа текущего соединения. Иначе указанная схема schema_name должна являться схемой по умолчанию для пользователя, выполняющего инструкцию.

queue_name

Имя создаваемой очереди. Это имя должно соответствовать рекомендациям по идентификаторам SQL Server.

STATUS (очередь)

Указывает, доступна очередь (ON) или нет (OFF). Когда очередь недоступна, нельзя ни добавлять в нее сообщения, ни удалять их из нее. Можно создать очередь в состоянии недоступности, чтобы сообщения не поступали в очередь до тех пор, пока очередь не будет сделана доступной с помощью инструкции ALTER QUEUE. Если это предложение опущено, значение по умолчанию равно ON, и очередь доступна.

RETENTION

Указывает параметр хранения для очереди. Если указано RETENTION = ON, то все сообщения, посылаемые или отправляемые во время диалогов, которые используют данную очередь, хранятся в очереди до окончания этих диалогов. Это позволяет хранить сообщения для аудита или выполнять компенсирующие транзакции в случае ошибки. Если это предложение не указано, параметр хранения по умолчанию установлен в OFF.

Примечание.

Установка RETENTION = ON может уменьшить производительность. Ее следует использовать только в том случае, если это требуется для приложения.

АКТИВАЦИЯ

Указывает сведения о хранимых процедурах, которые нужно активировать, чтобы начать обработку сообщений в этой очереди.

STATUS (активация)

Указывает, запускает ли компонент Service Broker хранимую процедуру. Если параметр STATUS = ON, то очередь запускает хранимую процедуру, указанную параметром PROCEDURE_NAME, если количество выполняемых в настоящий момент хранимых процедур меньше, чем значение MAX_QUEUE_READERS, и если сообщения прибывают в очередь быстрее, чем хранимые процедуры получают сообщения. Если параметр STATUS = OFF, то очередь не активирует хранимую процедуру. Если это предложение не указано, значение по умолчанию равно ON.

PROCEDURE_NAME = <procedure>

Указывает имя хранимой процедуры, которая должна быть активирована для обработки сообщений в данной очереди. Это значение должно быть идентификатором SQL Server.

database_name (процедура) — имя базы данных, которая содержит хранимую процедуру.

schema_name (процедура) — имя схемы, которая содержит хранимую процедуру.

procedure_name — имя хранимой процедуры.

MAX_QUEUE_READERS =max_readers

Определяет максимальное количество экземпляров хранимой процедуры активации, запускаемых очередью одновременно. Значение аргумента max_readers должно быть числом от 0 до 32 767.

EXECUTE AS

Указывает учетную запись пользователя базы данных SQL Server, в которой выполняется хранимая процедура активации. SQL Server должен иметь возможность проверить разрешения для этого пользователя во время запуска очереди хранимой процедуры. Для пользователя домена сервер должен быть подключен к домену в момент активации процедуры, иначе произойдет ошибка активации. Для пользователя SQL Server сервер всегда может проверять разрешения.

SELF указывает, что хранимая процедура выполняется как текущий пользователь. (участника базы данных, выполняющего эту инструкцию CREATE QUEUE).

user_name — имя пользователя, от имени которого выполняется хранимая процедура. Параметр user_name должен быть допустимым пользователем SQL Server, указанным в качестве идентификатора SQL Server. Текущий пользователь должен иметь разрешение IMPERSONATE на указанного аргументом user_name пользователя.

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.

Следующая таблица содержит столбцы в очереди.

Имя столбца	Тип данных	Description
status	tinyint	Состояние сообщения. Инструкция RECEIVE возвращает сообщения со значением состояния, равным 1. Если хранение сообщений включено, то значение состояния устанавливается в 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=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.

Примеры

А. Создание очереди без параметров

В следующем примере создается очередь, готовая к приему сообщений. Для очереди не указана хранимая процедура активации.

CREATE QUEUE ExpenseQueue;

B. Создание недоступной очереди

В следующем примере создается очередь, недоступная для приема сообщений. Для очереди не указана хранимая процедура активации.

CREATE QUEUE ExpenseQueue WITH STATUS=OFF;

В. Создание очереди с указанием внутренних сведений об активации

В следующем примере создается очередь, готовая к приему сообщений. При поступлении сообщения в очередь запускается хранимая процедура 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;

Е. Создание очереди с несколькими параметрами

В следующем примере создается очередь на основании файловой группы 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];

Связанный контент

• ALTER QUEUE (Transact-SQL)
• CREATE SERVICE (Transact-SQL)
• DROP QUEUE (Transact-SQL)
• RECEIVE (Transact-SQL)
• EVENTDATA (Transact-SQL)