CREATE QUEUE (Transact-SQL)

S’applique à : SQL Server Azure SQL Managed Instance

Crée une file d'attente dans une base de données. Les files d'attente stockent les messages. Lorsqu'un message destiné à un service se présente, Service Broker le place dans la file d'attente associée au service.

Conventions de la syntaxe Transact-SQL

Syntaxe

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 }

Arguments

database_name (objet)

Nom de la base de données dans laquelle la file d'attente doit être créée. database_name doit spécifier le nom d’une base de données existante. Quand database_name n’est pas fourni, la file d’attente est créée dans la base de données active.

schema_name (objet)

Nom du schéma auquel la nouvelle file d'attente appartient. Le schéma par défaut est le schéma par défaut de l'utilisateur exécutant l'instruction. schema_name peut indiquer un autre schéma que celui associé au nom de la connexion active si l’instruction CREATE QUEUE est exécutée par un membre du rôle serveur fixe sysadmin ou par un membre du rôle de base de données fixe db_dbowner ou db_ddladmin dans la base de données spécifiée par database_name. Sinon, schema_name doit être le schéma par défaut de l’utilisateur qui exécute l’instruction.

queue_name

Nom de la file d'attente à créer. Ce nom doit respecter les règles définies pour les identificateurs SQL Server.

STATUS (File d'attente)

Indique si la file d'attente est disponible (ON) ou indisponible (OFF). Lorsque la file d'attente est indisponible, aucun message ne peut y être ajouté ou supprimé. Vous pouvez créer une file d'attente indisponible pour empêcher l'arrivée des messages jusqu'au moment où cette file d'attente est rendue disponible avec l'instruction ALTER QUEUE. Si cette clause est omise, la valeur par défaut est ON et la file d'attente est disponible.

RETENTION

Spécifie le paramètre de rétention pour la file d'attente. Si RETENTION = ON (activé), tous les messages des conversations qui ont été envoyés ou reçus sont conservés dans leur file d'attente jusqu'à ce que les conversations s'achèvent. Vous pouvez ainsi garder ces messages pour effectuer des audits ou procéder à des transactions de compensation si une erreur se produit. Si cette clause n'est pas spécifiée, la valeur par défaut du paramètre de rétention est OFF.

Notes

Les performances peuvent se trouver altérées si RETENTION = ON. Ce paramètre doit être utilisé seulement si l'application le nécessite.

ACTIVATION

Spécifie des informations sur la procédure stockée à démarrer pour traiter les messages dans cette file d'attente.

STATUS (Activation)

Spécifie si Service Broker démarre ou non la procédure stockée. Lorsque STATUS = ON, la file d'attente lance la procédure stockée spécifiée avec PROCEDURE_NAME, quand le nombre de procédures actuellement en cours d'exécution est inférieur à la valeur de MAX_QUEUE_READERS et que la réception des messages dans la file d'attente est plus rapide que la réception des messages par les procédures stockées. Lorsque STATUS = OFF, la file d'attente ne démarre pas la procédure stockée. Quand cette clause est omise, la valeur par défaut est ON.

PROCEDURE_NAME = <procédure>

Spécifie le nom de la procédure stockée à démarrer pour traiter les messages dans cette file d'attente. Cette valeur doit être un identificateur SQL Server.

database_name (procédure) est le nom de la base de données contenant la procédure stockée.

schema_name (procédure) est le nom du schéma contenant la procédure stockée.

procedure_name est le nom de la procédure stockée.

MAX_QUEUE_READERS =max_readers

Spécifie le nombre maximal d'instances de la procédure stockée d'activation lancées simultanément par la file d'attente. La valeur de max_readers doit être comprise entre 0 et 32 767.

EXECUTE AS

Spécifie le compte d'utilisateur de la base de données SQL Server sous lequel la procédure stockée d'activation s'exécute. SQL Server doit être en mesure de contrôler les autorisations de cet utilisateur au moment où la file d'attente démarre la procédure stockée. Pour un utilisateur de domaine, le serveur doit être connecté au domaine lorsque la procédure est démarrée, sinon l'activation échoue. Pour un utilisateur SQL Server, le serveur peut toujours vérifier les autorisations.

SELF spécifie que la procédure stockée s’exécute en tant qu’utilisateur actuel. (Le principal de la base de données exécutant cette instruction CREATE QUEUE.)

’user_name’ est le nom de l’utilisateur sous lequel la procédure stockée s’exécute. Le paramètre user_name doit être un utilisateur SQL Server valide spécifié en tant qu’identificateur SQL Server. L’utilisateur actuel doit disposer de l’autorisation IMPERSONATE pour la valeur user_name spécifiée.

OWNER spécifie que la procédure stockée s’exécute en tant que propriétaire de la file d’attente.

POISON_MESSAGE_HANDLING

Spécifie si la gestion des messages incohérents est activée pour la file d'attente. La valeur par défaut est ON.

Une file d'attente dont la gestion des messages incohérents a la valeur OFF ne sera pas désactivée après cinq restaurations de transactions consécutives. L'application peut ainsi définir un système personnalisé de gestion des messages incohérents.

Groupe de fichiers ON | [DEFAULT]

Spécifie le groupe de fichiers SQL Server sur lequel créer cette file d'attente. Vous pouvez utiliser ce paramètre filegroup pour identifier un groupe de fichiers ou utiliser l’identificateur DEFAULT pour utiliser le groupe de fichiers par défaut pour la base de données Service Broker. Dans le contexte de cette clause, DEFAULT n'est pas un mot clé et il doit être délimité comme un identificateur. Quand aucun groupe de fichiers n'est spécifié, la file d'attente utilise le groupe de fichiers par défaut pour la base de données.

Notes

Une file d'attente peut être la cible d'une instruction SELECT. Toutefois, le contenu d'une file d'attente est uniquement modifiable par le biais d'instructions s'exécutant sur des conversations Service Broker, par exemple SEND, RECEIVE et END CONVERSATION. Une file d'attente ne peut pas être la cible d'une instruction INSERT, UPDATE, DELETE ou TRUNCATE.

Une file d'attente ne peut pas être un objet temporaire. Les noms de file d’attente commençant par # ne sont donc pas valides.

La création d'une file d'attente inactive permet de mettre en place l'infrastructure d'un service avant d'autoriser la réception de messages dans cette file d'attente.

Service Broker n'arrête pas les procédures stockées d'activation lorsqu'il n'existe aucun message dans la file d'attente. Une procédure stockée d'activation doit s'achever quand aucun message n'est disponible dans la file d'attente après un court laps de temps.

Les autorisations correspondant à la procédure stockée d'activation sont vérifiées lorsque Service Broker démarre la procédure stockée et non lorsque la file d'attente est créée. L'instruction CREATE QUEUE ne vérifie pas si l'utilisateur spécifié dans la clause EXECUTE AS dispose de l'autorisation d'exécution de la procédure stockée spécifiée dans la clause PROCEDURE NAME.

Lorsqu'une file d'attente est indisponible, Service Broker conserve les messages destinés aux services qui utilisent cette file dans la file d'attente de transmission de la base de données. La vue de catalogue sys.transmission_queue donne une vue de la file d’attente de transmission.

Une file d'attente est un objet appartenant à un schéma. Les files d’attente apparaissent dans la vue de catalogue sys.objects.

Le tableau suivant donne la liste des colonnes d'une file d'attente.

Nom de la colonne	Type de données	Description
status	tinyint	État du message. L’instruction RECEIVE retourne tous les messages pour lesquels status est égal à 1. Si la rétention des messages est activée, status a la valeur 0. Si la rétention des messages est désactivée, le message est supprimé de la file d'attente. Dans la file d’attente, les messages peuvent contenir l’une des valeurs suivantes : 0=Message reçu conservé 1=Prêt à recevoir 2=Pas encore terminé 3=Message envoyé conservé
priority	tinyint	Niveau de priorité assigné à ce message.
queuing_order	bigint	Numéro d'ordre du message dans la file d'attente.
conversation_group_id	uniqueidentifier	Identificateur du groupe de conversations auquel ce message appartient.
conversation_handle	uniqueidentifier	Descripteur de conversation dont ce message fait partie.
message_sequence_number	bigint	Numéro de séquence du message dans la conversation.
service_name	nvarchar(128)	Nom du service auquel la conversation est destinée.
service_id	int	Identificateur d'objet SQL Server du service auquel la conversation est destinée.
service_contract_name	nvarchar(128)	Nom du contrat suivi par la conversation.
service_contract_id	int	Identificateur d'objet SQL Server du contrat suivi par la conversation.
message_type_name	nvarchar(128)	Nom du type de message décrivant le message.
message_type_id	int	Identificateur d'objet SQL Server du type de message décrivant le message.
validation	nchar(2)	Validation utilisée pour le message. E=Vide N=Aucun X=XML
message_body	varbinary(max)	Contenu du message.
message_enqueue_time	datetime	Heure à laquelle le message a été mis en file d’attente.

Autorisations

L’autorisation de création d’une file d’attente est accordée aux membres du rôle de base de données fixe db_ddladmin ou db_owner ou aux membres du rôle serveur fixe sysadmin.

L’autorisation REFERENCES pour une file d’attente est accordée par défaut au propriétaire de la file d’attente, aux membres du rôle de base de données fixe db_ddladmin ou db_owner ou aux membres du rôle serveur fixe sysadmin.

L’autorisation RECEIVE pour une file d’attente est accordée par défaut au propriétaire de la file d’attente, aux membres du rôle de base de données fixe db_owner ou aux membres du rôle serveur fixe sysadmin.

Exemples

R. Créer une file d’attente sans paramètres

L'exemple suivant crée une file d'attente disponible pour la réception de messages. Aucune procédure stockée d'activation n'est spécifiée pour la file d'attente.

CREATE QUEUE ExpenseQueue;

B. Créer une file d’attente indisponible

L'exemple suivant crée une file d'attente indisponible pour la réception de messages. Aucune procédure stockée d'activation n'est spécifiée pour la file d'attente.

CREATE QUEUE ExpenseQueue WITH STATUS=OFF;

C. Créer une file d’attente et spécifier des informations d’activation internes

L'exemple suivant crée une file d'attente disponible pour la réception de messages. La file d'attente lance la procédure stockée expense_procedure quand un message entre dans la file d'attente. Cette procédure stockée s'exécute en tant qu'utilisateur ExpenseUser. La file d'attente démarre au maximum 5 instances de la procédure stockée.

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

D. Créer une file d’attente sur un groupe de fichiers spécifique

L'exemple suivant crée une file d'attente dans le groupe de fichiers ExpenseWorkFileGroup.

CREATE QUEUE ExpenseQueue
    ON ExpenseWorkFileGroup;

E. Créer une file d’attente avec plusieurs paramètres

L’exemple suivant crée une file d’attente dans le groupe de fichiers DEFAULT. La file d'attente n'est pas disponible. Les messages sont conservés dans la file d'attente jusqu'à ce que la conversation dont ils font partie se termine. Quand la file d’attente est rendue disponible via ALTER QUEUE, elle démarre la procédure stockée AdventureWorks2022.dbo.expense_procedure pour traiter les messages. La procédure stockée s'exécute sous l'utilisateur qui a lancé l'instruction CREATE QUEUE. La file d'attente démarre au maximum 10 instances de la procédure stockée.

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

Contenu connexe

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