CREATE QUEUE (Transact-SQL)

Gilt für: SQL Server Azure SQL Managed Instance

Erstellt eine neue Warteschlange in einer Datenbank. Fügt einer Warteschlange gespeicherte Nachrichten hinzu. Wenn eine Nachricht für einen Dienst eintrifft, platziert Service Broker die Nachricht in der dem Dienst zugeordneten Warteschlange.

Transact-SQL-Syntaxkonventionen

Syntax

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 }

Argumente

database_name (Objekt)

Der Name der Datenbank, in der die neue Warteschlange erstellt werden soll. database_name muss dem Namen einer vorhandenen Datenbank entsprechen. Wird database_name nicht bereitgestellt, wird die Warteschlange in der aktuellen Datenbank erstellt.

schema_name (Objekt)

Der Name des Schemas, zu dem die neue Warteschlange gehört. Standardmäßig handelt es sich bei dem Schema um das Standardschema für den Benutzer, der die Anweisung ausführt. Wird die CREATE QUEUE-Anweisung von einem Mitglied der festen Serverrolle sysadmin oder einem Mitglied der festen Datenbankrollen db_dbowner oder db_ddladmin in der durch database_name angegebenen Datenbank ausgeführt, kann schema_name ein anderes als das dem Anmeldenamen der aktuellen Verbindung zugeordnete Schema angeben. Andernfalls muss es sich bei schema_name um das Standardschema für den Benutzer handeln, der die Anweisung ausführt.

queue_name

Der Name der zu erstellenden Warteschlange. Dieser Name muss den Richtlinien für SQL Server-Bezeichner entsprechen.

STATUS (Warteschlange)

Gibt an, ob die Warteschlange verfügbar ist (ON) oder nicht (OFF). Ist die Warteschlange nicht verfügbar, können der Warteschlange keine Nachrichten hinzugefügt oder aus ihr entfernt werden. Sie können die Warteschlange im nicht verfügbaren Status erstellen, damit Nachrichten erst dann in der Warteschlange ankommen, wenn die Warteschlange mit einer ALTER QUEUE-Anweisung zur Verfügung gestellt wird. Wird diese Klausel nicht angegeben, ist die Standardeinstellung ON, und die Warteschlange ist verfügbar.

RETENTION

Gibt die Beibehaltungseinstellung für die Warteschlange an. Ist RETENTION = ON, werden alle Nachrichten, die für Konversationen mit dieser Warteschlange gesendet oder empfangen werden, in der Warteschlange beibehalten, bis die Konversationen beendet sind. Dies ermöglicht es Ihnen, Nachrichten zu Überwachungszwecken oder zur Ausführung von kompensierenden Transaktionen beim Auftreten eines Fehlers beizubehalten. Wird diese Klausel nicht angegeben, wird die Beibehaltungseinstellung standardmäßig auf OFF festgelegt.

Hinweis

Das Festlegen von RETENTION = ON kann die Leistung reduzieren. Diese Einstellung sollte nur verwendet werden, wenn sie für die Anwendung erforderlich ist.

ACTIVATION

Gibt Informationen über die gespeicherte Prozedur an, die Sie für die Verarbeitung von Nachrichten in dieser Warteschlange starten müssen.

STATUS (Aktivierung)

Gibt an, ob Service Broker die gespeicherte Prozedur startet. Ist STATUS = ON, startet die Warteschlange die mit PROCEDURE_NAME angegebene gespeicherte Prozedur, wenn die Anzahl der zurzeit ausgeführten Prozeduren kleiner als MAX_QUEUE_READERS ist und wenn Nachrichten schneller in der Warteschlange ankommen, als die gespeicherten Prozeduren Nachrichten empfangen. Ist STATUS = OFF, startet die Warteschlange die gespeicherte Prozedur nicht. Wird diese Klausel nicht angegeben, ist die Standardeinstellung ON.

PROCEDURE_NAME = <procedure>

Gibt den Namen der gespeicherten Prozedur an, die für die Verarbeitung von Nachrichten in dieser Warteschlange gestartet werden soll. Dieser Wert muss ein SQL Server-Bezeichner sein.

database_name(Prozedur) ist der Name der Datenbank, die die gespeicherte Prozedur enthält.

schema_name(Prozedur) ist der Name des Schemas, das die gespeicherte Prozedur enthält.

procedure_name ist der Name der gespeicherten Prozedur.

MAX_QUEUE_READERS =max_reader

Gibt die maximale Anzahl von Instanzen der gespeicherten Aktivierungsprozedur an, die von der Warteschlange gleichzeitig gestartet werden. Der Wert von max_readers muss eine Zahl zwischen 0 und 32767 sein.

EXECUTE AS

Gibt das SQL Server-Datenbank-Benutzerkonto an, unter dem die gespeicherte Aktivierungsprozedur ausgeführt wird. SQL Server muss zum Zeitpunkt des Startens der gespeicherten Prozedur durch die Warteschlange die Berechtigungen für diesen Benutzer überprüfen können. Bei einem Domänenbenutzer muss der Server mit der Domäne verbunden sein, wenn die Prozedur gestartet wird. Andernfalls erzeugt die Aktivierung einen Fehler. Bei einem SQL Server-Benutzer kann der Server immer die Berechtigungen überprüfen.

SELF gibt an, dass die gespeicherte Prozedur als der aktuelle Benutzer ausgeführt wird. (Der Datenbankprinzipal, der diese CREATE QUEUE-Anweisung ausführt.)

'user_name' ist der Name des Benutzers, als der die gespeicherte Prozedur ausgeführt wird. Der user_name-Parameter muss ein gültiger SQL Server-Benutzer sein, der als SQL Server-Bezeichner angegeben wird. Der aktuelle Benutzer muss über die IMPERSONATE-Berechtigung für den mit user_name angegebenen Benutzer verfügen.

OWNER gibt an, dass die gespeicherte Prozedur als der Besitzer der Warteschlange ausgeführt wird.

POISON_MESSAGE_HANDLING

Gibt an, ob die Behandlung nicht verarbeitbarer Nachrichten für die Warteschlange aktiviert ist. Der Standardwert ist ON.

Eine Warteschlange, für die die Behandlung nicht verarbeitbarer Nachrichten auf OFF festgelegt ist, wird erst nach fünf aufeinander folgenden Transaktionsrollbacks deaktiviert. Daher ist es möglich, dass von der Anwendung ein System für die Behandlung nicht verarbeitbarer Nachrichten definiert wird.

ON filegroup | [DEFAULT]

Gibt die SQL Server-Dateigruppe an, in der diese Warteschlange erstellt werden soll. Sie können mit dem filegroup-Parameter eine Dateigruppe identifizieren oder mit dem DEFAULT-Bezeichner die Standarddateigruppe für die Service Broker-Datenbank verwenden. Im Kontext dieser Klausel ist DEFAULT kein Schlüsselwort und muss als Bezeichner begrenzt sein. Wird keine Dateigruppe angegeben, verwendet die Warteschlange die Standarddateigruppe für die Datenbank.

Bemerkungen

Eine Warteschlange kann das Ziel einer SELECT-Anweisung sein. Der Inhalt einer Warteschlange kann jedoch nur mithilfe von Anweisungen geändert werden, die für Service Broker-Konversationen verwendet werden, wie beispielsweise SEND, RECEIVE und END CONVERSATION. Eine Warteschlange kann nicht das Ziel einer INSERT-, UPDATE-, DELETE- oder TRUNCATE-Anweisung sein.

Eine Warteschlange ist möglicherweise kein temporäres Objekt. Daher sind Warteschlangennamen, die mit # beginnen, ungültig.

Das Erstellen einer Warteschlange im inaktiven Status ermöglicht es Ihnen, die Infrastruktur für einen Dienst einzurichten, bevor der Empfang von Nachrichten in der Warteschlange zugelassen wird.

Service Broker beendet gespeicherte Aktivierungsprozeduren nicht, wenn sich keine Nachrichten in der Warteschlange befinden. Eine gespeicherte Aktivierungsprozedur sollte beendet werden, wenn eine kurze Zeit lang keine Nachrichten in der Warteschlange verfügbar sind.

Berechtigungen für die gespeicherte Aktivierungsprozedur werden überprüft, wenn Service Broker die gespeicherte Prozedur startet, nicht, wenn die Warteschlange erstellt wird. Die CREATE QUEUE-Anweisung überprüft nicht, ob der in der EXECUTE AS-Klausel angegebene Benutzer über die Berechtigung verfügt, die in der PROCEDURE NAME-Klausel angegebene gespeicherte Prozedur auszuführen.

Ist eine Warteschlange nicht verfügbar, speichert Service Broker Nachrichten für Dienste, die die Warteschlange verwenden, in der Übertragungswarteschlange für die Datenbank. Die sys.transmission_queue-Katalogsicht bietet eine Ansicht der Übertragungswarteschlange.

Eine Warteschlange ist ein Objekt, dessen Besitzer ein Schema ist. Warteschlangen werden in der sys.objects-Katalogsicht angezeigt.

In der folgenden Tabelle werden die Spalten in einer Warteschlange aufgelistet.

Spaltenname	Datentyp	Beschreibung
status	tinyint	Status der Nachricht. Die RECEIVE-Anweisung gibt alle Nachrichten zurück, die den Status 1 haben. Wenn die Nachrichtenbeibehaltung aktiviert ist, wird der Status auf 0 festgelegt. Wenn die Nachrichtenbeibehaltung deaktiviert ist, wird die Meldung aus der Warteschlange gelöscht. Nachrichten in der Warteschlange können einen der folgenden Werte enthalten: 0=Empfangene Nachricht beibehalten 1=Bereit für den Empfang 2=Noch nicht abgeschlossen 3=Gesendete Nachricht beibehalten
priority	tinyint	Die Prioritätsebene, die der Nachricht zugewiesen wird.
queuing_order	bigint	Fortlaufende Nummer der Nachricht in der Warteschlange.
conversation_group_id	uniqueidentifier	Bezeichner für die Konversationsgruppe, zu der diese Nachricht gehört.
conversation_handle	uniqueidentifier	Handle der Konversation, von der diese Nachricht ein Teil ist.
message_sequence_number	bigint	Sequenznummer der Nachricht in der Konversation.
service_name	nvarchar(128)	Name des Diensts, an den die Konversation gerichtet ist.
service_id	int	SQL Server-Objektbezeichner des Diensts, an den die Konversation gerichtet ist.
service_contract_name	nvarchar(128)	Name des Vertrags, dem die Konversation entspricht.
service_contract_id	int	SQL Server-Objektbezeichner des Vertrags, dem die Konversation entspricht.
message_type_name	nvarchar(128)	Name des Nachrichtentyps, der die Nachricht beschreibt.
message_type_id	int	SQL Server-Objektbezeichner des Nachrichtentyps, der die Nachricht beschreibt.
validation	nchar(2)	Für die Nachricht verwendete Überprüfung. E=Leer N=Keine X=XML
message_body	varbinary(max)	Inhalt der Nachricht.
message_enqueue_time	datetime	Uhrzeit, zu der die Nachricht in die Warteschlange eingereiht wurde.

Berechtigungen

Die Berechtigung zum Erstellen einer Warteschlange liegt bei Mitgliedern der festen Datenbankrollen db_ddladmin oder db_owner bzw. der festen Serverrolle sysadmin.

Die REFERENCES-Berechtigung für eine Warteschlange wird standardmäßig dem Besitzer der Warteschlange, den Mitgliedern der festen Datenbankrolle db_ddladmin oder db_owner bzw. den Mitgliedern der festen Serverrolle sysadmin zugewiesen.

RECEIVE-Berechtigungen für eine Warteschlange liegen standardmäßig beim Besitzer der Warteschlange, bei Mitgliedern der festen Datenbankrolle db_owner oder bei Mitgliedern der festen Serverrolle sysadmin.

Beispiele

A. Erstellen einer Warteschlange ohne Parameter

Im folgenden Beispiel wird eine Warteschlange erstellt, die für den Empfang von Nachrichten verfügbar ist. Für die Warteschlange wird keine gespeicherte Aktivierungsprozedur angegeben.

CREATE QUEUE ExpenseQueue;

B. Erstellen einer nicht verfügbaren Warteschlange

Im folgenden Beispiel wird eine Warteschlange erstellt, die nicht für den Empfang von Nachrichten verfügbar ist. Für die Warteschlange wird keine gespeicherte Aktivierungsprozedur angegeben.

CREATE QUEUE ExpenseQueue WITH STATUS=OFF;

C. Erstellen einer Warteschlange und Angeben von internen Aktivierungsinformationen

Im folgenden Beispiel wird eine Warteschlange erstellt, die für den Empfang von Nachrichten verfügbar ist. Die Warteschlange startet die gespeicherte Prozedur expense_procedure, wenn eine Nachricht in der Warteschlange angeordnet wird. Die gespeicherte Prozedur wird als der Benutzer ExpenseUser ausgeführt. Die Warteschlange startet ein Maximum von 5 Instanzen der gespeicherten Prozedur.

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

D: Erstellen einer Warteschlange für eine bestimmte Dateigruppe

Im folgenden Beispiel wird eine Warteschlange in der ExpenseWorkFileGroup-Dateigruppe erstellt.

CREATE QUEUE ExpenseQueue
    ON ExpenseWorkFileGroup;

E. Erstellen einer Warteschlange mit mehreren Parametern

Im folgenden Beispiel wird eine Warteschlange in der DEFAULT-Dateigruppe erstellt. Die Warteschlange ist nicht verfügbar. Nachrichten werden in der Warteschlange beibehalten, bis die Konversation endet, zu der sie gehören. Wenn die Warteschlange über ALTER QUEUE zur Verfügung gestellt wird, startet die Warteschlange die gespeicherte Prozedur AdventureWorks2022.dbo.expense_procedure für die Verarbeitung von Nachrichten. Die gespeicherte Prozedur wird als der Benutzer ausgeführt, der die CREATE QUEUE-Anweisung ausgeführt hat. Die Warteschlange startet ein Maximum von 10 Instanzen der gespeicherten Prozedur.

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

Zugehöriger Inhalt

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