CREATE QUEUE (Transact-SQL)CREATE QUEUE (Transact-SQL)

CETTE RUBRIQUE S’APPLIQUE À :ouiSQL Server (à partir de la version 2008)nonAzure SQL DatabasenonAzure SQL Data Warehouse nonParallel Data Warehouse THIS TOPIC APPLIES TO:yesSQL Server (starting with 2008)noAzure SQL DatabasenoAzure SQL Data Warehouse noParallel Data Warehouse

Crée une file d'attente dans une base de données.Creates a new queue in a database. Les files d'attente stockent les messages.Queues store messages. Lorsqu'un message destiné à un service se présente, Service BrokerService Broker le place dans la file d'attente associée au service.When a message arrives for a service, Service BrokerService Broker puts the message on the queue associated with the service.

Icône de lien de rubrique Conventions de la syntaxe Transact-SQLTopic link icon Transact-SQL Syntax Conventions

SyntaxeSyntax

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 ] . | schema_name. ]  
        queue_name  
}   

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

ArgumentsArguments

database_name (objet)database_name (object)
Nom de la base de données dans laquelle la file d'attente doit être créée.Is the name of the database within which to create the new queue. database_name doit spécifier le nom d’une base de données existante.database_name must specify the name of an existing database. Quand database_name n’est pas fourni, la file d’attente est créée dans la base de données active.When database_name is not provided, the queue is created in the current database.

schema_name (objet)schema_name (object)
Nom du schéma auquel la nouvelle file d'attente appartient.Is the name of the schema to which the new queue belongs. Le schéma par défaut est le schéma par défaut de l'utilisateur exécutant l'instruction.The schema defaults to the default schema for the user that executes the statement. 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.If the CREATE QUEUE statement is executed by a member of the sysadmin fixed server role, or a member of the db_dbowner or db_ddladmin fixed database roles in the database specified by database_name, schema_name can specify a schema other than the one associated with the login of the current connection. Sinon, schema_name doit être le schéma par défaut de l’utilisateur qui exécute l’instruction.Otherwise, schema_name must be the default schema for the user who executes the statement.

queue_namequeue_name
Nom de la file d'attente à créer.Is the name of the queue to create. Ce nom doit respecter les règles définies pour les identificateurs SQL ServerSQL Server.This name must meet the guidelines for SQL ServerSQL Server identifiers.

STATUS (File d'attente)STATUS (Queue)
Indique si la file d'attente est disponible (ON) ou indisponible (OFF).Specifies whether the queue is available (ON) or unavailable (OFF). Lorsque la file d'attente est indisponible, aucun message ne peut y être ajouté ou supprimé.When the queue is unavailable, no messages can be added to the queue or removed from the queue. 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.You can create the queue in an unavailable state to keep messages from arriving on the queue until the queue is made available with an ALTER QUEUE statement. Si cette clause est omise, la valeur par défaut est ON et la file d'attente est disponible.If this clause is omitted, the default is ON, and the queue is available.

RETENTIONRETENTION
Spécifie le paramètre de rétention pour la file d'attente.Specifies the retention setting for the queue. 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.If RETENTION = ON, all messages sent or received on conversations that use this queue are retained in the queue until the conversations have ended. Vous pouvez ainsi garder ces messages pour effectuer des audits ou procéder à des transactions de compensation si une erreur se produit.This lets you retain messages for auditing purposes, or to perform compensating transactions if an error occurs. Si cette clause n'est pas spécifiée, la valeur par défaut du paramètre de rétention est OFF.If this clause is not specified, the retention setting defaults to OFF.

Note

Les performances peuvent se trouver altérées si RETENTION = ON.Setting RETENTION = ON can decrease performance. Ce paramètre doit être utilisé seulement si l'application le nécessite.This setting should only be used if it is required for the application.

ACTIVATIONACTIVATION
Spécifie des informations sur la procédure stockée à démarrer pour traiter les messages dans cette file d'attente.Specifies information about which stored procedure you have to start to process messages in this queue.

STATUS (Activation)STATUS (Activation)
Spécifie si Service BrokerService Broker démarre ou non la procédure stockée.Specifies whether Service BrokerService Broker starts the stored procedure. 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.When STATUS = ON, the queue starts the stored procedure specified with PROCEDURE_NAME when the number of procedures currently running is less than MAX_QUEUE_READERS and when messages arrive on the queue faster than the stored procedures receive messages. Lorsque STATUS = OFF, la file d'attente ne démarre pas la procédure stockée.When STATUS = OFF, the queue does not start the stored procedure. Quand cette clause est omise, la valeur par défaut est ON.If this clause is not specified, the default is ON.

PROCEDURE_NAME = <procedure>PROCEDURE_NAME = <procedure>
Spécifie le nom de la procédure stockée à démarrer pour traiter les messages dans cette file d'attente.Specifies the name of the stored procedure to start to process messages in this queue. Cette valeur doit être un identificateur SQL ServerSQL Server.This value must be a SQL ServerSQL Server identifier.

database_name (procédure)database_name(procedure)
Nom de la base de données contenant la procédure stockée.Is the name of the database that contains the stored procedure.

schema_name (procédure)schema_name(procedure)
Nom du schéma qui contient la procédure stockée.Is the name of the schema that contains the stored procedure.

procedure_nameprocedure_name
Nom de la procédure stockée.Is the name of the stored procedure.

MAX_QUEUE_READERS =max_readersMAX_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.Specifies the maximum number of instances of the activation stored procedure that the queue starts at the same time. La valeur de max_readers doit être comprise entre 0 et 32 767.The value of max_readers must be a number between 0 and 32767.

EXECUTE ASEXECUTE AS
Spécifie le compte d'utilisateur de la base de données SQL ServerSQL Server sous lequel la procédure stockée d'activation s'exécute.Specifies the SQL ServerSQL Server database user account under which the activation stored procedure runs. SQL ServerSQL 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. must be able to check the permissions for this user at the time that the queue starts the stored procedure. Pour un utilisateur de domaine, le serveur doit être connecté au domaine lorsque la procédure est démarrée, sinon l'activation échoue.For a domain user, the server must be connected to the domain when the procedure is started or activation fails. Pour un utilisateur SQL ServerSQL Server, le serveur peut toujours vérifier les autorisations.For a SQL ServerSQL Server user, the server can always check permissions.

SELFSELF
Spécifie que la procédure stockée s'exécute en tant qu'utilisateur actuel.Specifies that the stored procedure executes as the current user. (Le principal de la base de données exécutant cette instruction CREATE QUEUE.)(The database principal executing this CREATE QUEUE statement.)

'user_name''user_name'
Nom de l'utilisateur sous lequel la procédure stockée s'exécute.Is the name of the user who the stored procedure executes as. Le paramètre user_name doit être un utilisateur SQL ServerSQL Server valide spécifié en tant qu’identificateur SQL ServerSQL Server.The user_name parameter must be a valid SQL ServerSQL Server user specified as a SQL ServerSQL Server identifier. L’utilisateur actuel doit disposer de l’autorisation IMPERSONATE pour la valeur user_name spécifiée.The current user must have IMPERSONATE permission for the user_name specified.

OWNEROWNER
Spécifie que la procédure stockée s'exécute en tant que propriétaire de la file d'attente.Specifies that the stored procedure executes as the owner of the queue.

POISON_MESSAGE_HANDLINGPOISON_MESSAGE_HANDLING
Spécifie si la gestion des messages incohérents est activée pour la file d'attente.Specifies whether poison message handling is enabled for the queue. La valeur par défaut est ON.The default is 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.A queue that has poison message handling set to OFF will not be disabled after five consecutive transaction rollbacks. L'application peut ainsi définir un système personnalisé de gestion des messages incohérents.This allows for a custom poison message handing system to be defined by the application.

ON filegroup | [DEFAULT]ON filegroup | [DEFAULT]
Spécifie le groupe de fichiers SQL ServerSQL Server sur lequel créer cette file d'attente.Specifies the SQL ServerSQL Server filegroup on which to create this queue. 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.You can use the filegroup parameter to identify a filegroup, or use the DEFAULT identifier to use the default filegroup for the service broker database. Dans le contexte de cette clause, DEFAULT n'est pas un mot clé et il doit être délimité comme un identificateur.In the context of this clause, DEFAULT is not a keyword, and must be delimited as an identifier. 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.When no filegroup is specified, the queue uses the default filegroup for the database.

Notes Remarks

Une file d'attente peut être la cible d'une instruction SELECT.A queue can be the target of a SELECT statement. Toutefois, le contenu d'une file d'attente est uniquement modifiable par le biais d'instructions s'exécutant sur des conversations Service BrokerService Broker, par exemple SEND, RECEIVE et END CONVERSATION.However, the contents of a queue can only be modified using statements that operate on Service BrokerService Broker conversations, such as SEND, RECEIVE, and END CONVERSATION. Une file d'attente ne peut pas être la cible d'une instruction INSERT, UPDATE, DELETE ou TRUNCATE.A queue cannot be the target of an INSERT, UPDATE, DELETE, or TRUNCATE statement.

Une file d'attente ne peut pas être un objet temporaire.A queue might not be a temporary object. Les noms de file d’attente commençant par # ne sont donc pas valides.Therefore, queue names starting with # are not valid.

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.Creating a queue in an inactive state lets you get the infrastructure in place for a service before allowing messages to be received on the queue.

Service BrokerService Broker n'arrête pas les procédures stockées d'activation lorsqu'il n'existe aucun message dans la file d'attente. does not stop activation stored procedures when there are no messages on the queue. 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.An activation stored procedure should exit when no messages are available on the queue for a short time.

Les autorisations correspondant à la procédure stockée d'activation sont vérifiées lorsque Service BrokerService Broker démarre la procédure stockée et non lorsque la file d'attente est créée.Permissions for the activation stored procedure are checked when Service BrokerService Broker starts the stored procedure, not when the queue is created. 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.The CREATE QUEUE statement does not verify that the user specified in the EXECUTE AS clause has permission to execute the stored procedure specified in the PROCEDURE NAME clause.

Lorsqu'une file d'attente est indisponible, Service BrokerService 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.When a queue is unavailable, Service BrokerService Broker holds messages for services that use the queue in the transmission queue for the database. L'affichage catalogue sys.transmission_queue donne une vue de la file d'attente de transmission.The sys.transmission_queue catalog view provides a view of the transmission queue.

Une file d'attente est un objet appartenant à un schéma.A queue is a schema-owned object. Les files d'attente apparaissent dans l'affichage catalogue sys.objects.Queues appear in the sys.objects catalog view.

Le tableau suivant donne la liste des colonnes d'une file d'attente.The following table lists the columns in a queue.

Nom de colonneColumn name Type de donnéesData type DescriptionDescription
statusstatus tinyinttinyint État du message.Status of the message. L’instruction RECEIVE retourne tous les messages pour lesquels status est égal à 1.The RECEIVE statement returns all messages that have a status of 1. Si la rétention des messages est activée, status a la valeur 0.If message retention is on, the status is then set to 0. Si la rétention des messages est désactivée, le message est supprimé de la file d'attente.If message retention is off, the message is deleted from the queue. Dans la file d’attente, les messages peuvent contenir l’une des valeurs suivantes :Messages in the queue can contain one of the following values:

0 = Message reçu conservé0=Retained received message

1 = Prêt à recevoir1=Ready to receive

2 = Pas encore terminé2=Not yet complete

3 = Message envoyé conservé3=Retained sent message
prioritypriority tinyinttinyint Niveau de priorité assigné à ce message.The priority level that is assigned to this message.
queuing_orderqueuing_order bigintbigint Numéro d'ordre du message dans la file d'attente.Message order number in the queue.
conversation_group_idconversation_group_id uniqueidentifieruniqueidentifier Identificateur du groupe de conversations auquel ce message appartient.Identifier for the conversation group that this message belongs to.
conversation_handleconversation_handle uniqueidentifieruniqueidentifier Descripteur de conversation dont ce message fait partie.Handle for the conversation that this message is part of.
message_sequence_numbermessage_sequence_number bigintbigint Numéro de séquence du message dans la conversation.Sequence number of the message in the conversation.
service_nameservice_name nvarchar(512)nvarchar(512) Nom du service auquel la conversation est destinée.Name of the service that the conversation is to.
service_idservice_id Intint Identificateur d'objet SQL ServerSQL Server du service auquel la conversation est destinée. SQL ServerSQL Server object identifier of the service that the conversation is to.
service_contract_nameservice_contract_name nvarchar (256)nvarchar(256) Nom du contrat suivi par la conversation.Name of the contract that the conversation follows.
service_contract_idservice_contract_id Intint Identificateur d'objet SQL ServerSQL Server du contrat suivi par la conversation. SQL ServerSQL Server object identifier of the contract that the conversation follows.
message_type_namemessage_type_name nvarchar (256)nvarchar(256) Nom du type de message décrivant le message.Name of the message type that describes the message.
message_type_idmessage_type_id Intint Identificateur d'objet SQL ServerSQL Server du type de message décrivant le message. SQL ServerSQL Server object identifier of the message type that describes the message.
validationvalidation nchar(2)nchar(2) Validation utilisée pour le message.Validation used for the message.

E=VideE=Empty

N=AucuneN=None

X=XMLX=XML
message_bodymessage_body varbinary(max)varbinary(max) Contenu du message.Content of the message.
message_idmessage_id uniqueidentifieruniqueidentifier Identificateur unique du message.Unique identifier for the message.

AutorisationsPermissions

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 et aux membres du rôle serveur fixe sysadmin.Permission for creating a queue uses members of the db_ddladmin or db_owner fixed database roles and the sysadmin fixed server role.

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 et aux membres du rôle serveur fixe sysadmin.REFERENCES permission for a queue defaults to the owner of the queue, members of the db_ddladmin or db_owner fixed database roles, and members of the sysadmin fixed server role.

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.RECEIVE permission for a queue defaults to the owner of the queue, members of the db_owner fixed database role, and members of the sysadmin fixed server role.

ExemplesExamples

A.A. Création d'une file d'attente sans paramètresCreating a queue with no parameters

L'exemple suivant crée une file d'attente disponible pour la réception de messages.The following example creates a queue that is available to receive messages. Aucune procédure stockée d'activation n'est spécifiée pour la file d'attente.No activation stored procedure is specified for the queue.

CREATE QUEUE ExpenseQueue ;  

B.B. Création d'une file d'attente indisponibleCreating an unavailable queue

L'exemple suivant crée une file d'attente indisponible pour la réception de messages.The following example creates a queue that is unavailable to receive messages. Aucune procédure stockée d'activation n'est spécifiée pour la file d'attente.No activation stored procedure is specified for the queue.

CREATE QUEUE ExpenseQueue WITH STATUS=OFF ;  

C.C. Création d'une file d'attente et spécification d'informations d'activation internesCreating a queue and specify internal activation information

L'exemple suivant crée une file d'attente disponible pour la réception de messages.The following example creates a queue that is available to receive messages. La file d'attente lance la procédure stockée expense_procedure quand un message entre dans la file d'attente.The queue starts the stored procedure expense_procedure when a message enters the queue. Cette procédure stockée s'exécute en tant qu'utilisateur ExpenseUser.The stored procedure executes as the user ExpenseUser. La file d'attente démarre au maximum 5 instances de la procédure stockée.The queue starts a maximum of 5 instances of the stored procedure.

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

D.D. Création d'une file d'attente dans un groupe de fichiers spécifiqueCreating a queue on a specific filegroup

L'exemple suivant crée une file d'attente dans le groupe de fichiers ExpenseWorkFileGroup.The following example creates a queue on the filegroup ExpenseWorkFileGroup.

CREATE QUEUE ExpenseQueue  
    ON ExpenseWorkFileGroup ;  

E.E. Création d'une file d'attente avec plusieurs paramètresCreating a queue with multiple parameters

L’exemple suivant crée une file d’attente dans le groupe de fichiers DEFAULT.The following example creates a queue on the DEFAULT filegroup. La file d'attente n'est pas disponible.The queue is unavailable. Les messages sont conservés dans la file d'attente jusqu'à ce que la conversation dont ils font partie se termine.Messages are retained in the queue until the conversation that they belong to ends. Lorsque la file d'attente est rendue disponible via l'instruction ALTER QUEUE, elle démarre la procédure stockée 2008R2.dbo.expense_procedure pour traiter les messages.When the queue is made available through ALTER QUEUE, the queue starts the stored procedure 2008R2.dbo.expense_procedure to process messages. La procédure stockée s'exécute sous l'utilisateur qui a lancé l'instruction CREATE QUEUE.The stored procedure executes as the user who ran the CREATE QUEUE statement. La file d'attente démarre au maximum 10 instances de la procédure stockée.The queue starts a maximum of 10 instances of the stored procedure.

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

Voir aussiSee Also

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