CREATE QUEUE (Transact-SQL)

Article
12/15/2008

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

Icône Lien de rubrique 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 } 
            ) ]
    ]
     [ ON { filegroup | [ DEFAULT ] } ]
[ ; ]

<object> ::=
{
    [ database_name. [ schema_name ] . | schema_name. ]
        queue_name
} 

<procedure> ::=
{
    [ database_name. [ schema_name ] . | schema_name. ]
        stored_procedure_name
}

Arguments

database_name (objet)
Nom de la base de données dans laquelle créer la nouvelle file d'attente. L'argument database_name doit spécifier le nom d'une base de données existante. Si cet argument n'est pas renseigné, 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 qui est associé au nom d'accès 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. Si ce n'est pas le cas, le paramètre schema_name spécifié doit être le schéma par défaut de l'utilisateur exécutant 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.

Remarque :
Les performances peuvent se trouver altérées si RETENTION = ON. Ce paramètre doit être utilisé seulement si l'application le nécessite. Pour plus d'informations, consultez Message Retention.

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

STATUS (Activation)
Précise si Service Broker active 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 n'active pas la procédure stockée. Si cette clause est omise, la valeur par défaut est ON.

PROCEDURE_NAME = <procedure>
Spécifie le nom de la procédure stockée à activer pour traiter les messages dans cette file d'attente. Cette valeur doit être un identificateur SQL Server. Pour plus d'informations, consultez Understanding When Activation Occurs.

database_name (procédure)
Nom de la base de données contenant la procédure stockée.

schema_name (procédure)
Nom du schéma qui contient la procédure stockée.

procedure_name
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 active la procédure stockée. Pour un utilisateur de domaine, le serveur doit être connecté au domaine lorsque la procédure est activé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. (L'entité de sécurité de la base de données exécutant cette instruction CREATE QUEUE.)

'user_name'
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 de 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.

ON filegroup | [ 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 active 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 d'attente dans la file d'attente de transmission pour la base de données. L'affichage 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 l'affichage 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. Pour les messages renvoyés par la commande RECEIVE, l'état est toujours 1. Dans la file d'attente, les messages peuvent contenir l'une des valeurs suivantes : 0= Message reçu 1= Prêt 2= Pas encore terminé 3= Message envoyé conservé
priorité	tinyint	Réservé pour un usage futur.
queuing_order	bigint	Numéro d'ordre du message dans la file d'attente.
conversation_group_id	uniqueidentifier	Identificateur du groupe de conversation auquel ce message appartient.
conversation_handle	uniqueidentifier	Descripteur de la conversation dont ce message fait partie.
message_sequence_number	bigint	Numéro de séquence du message dans la conversation.
service_name	nvarchar(512)	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(256)	Nom du contrat respecté par la conversation.
service_contract_id	int	Identificateur d'objet SQL Server du contrat respecté par la conversation.
message_type_name	nvarchar(256)	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= Aucune X= XML
message_body	varbinary(MAX)	Contenu du message.
message_id	uniqueidentifier	Identificateur unique du message.

Autorisations

L'autorisation de créer une file d'attente est accordée par défaut aux membres des rôles de base de données fixes db_ddladmin ou db_owner et 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 des rôle de base de données fixes db_ddladmin ou db_owner et 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 et aux membres du rôle serveur fixe sysadmin.

Exemples

A. Création d'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éation d'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éation d'une file d'attente et spécification d'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éation d'une file d'attente dans 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éation d'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. Lorsque la file d'attente est rendue disponible via l'instruction ALTER QUEUE, elle active la procédure stockée AdventureWorks.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 = AdventureWorks.dbo.expense_procedure,
          MAX_QUEUE_READERS = 10,
          EXECUTE AS SELF )
    ON [DEFAULT] ;

Voir aussi