sp_send_dbmail (Transact-SQL)

  • Article

S’applique à :SQL ServerAzure SQL Managed Instance

Envoie un message électronique aux destinataires spécifiés. Le message peut inclure un jeu de résultats de requête, des pièces jointes ou les deux. Lorsque le courrier est correctement placé dans la file d’attente de messagerie de base de données, sp_send_dbmail retourne le mailitem_id message. Cette procédure stockée se trouve dans la msdb base de données.

Conventions de la syntaxe Transact-SQL

Syntaxe

sp_send_dbmail [ [ @profile_name = ] 'profile_name' ]
    [ , [ @recipients = ] 'recipients [ ; ...n ]' ]
    [ , [ @copy_recipients = ] 'copy_recipient [ ; ...n ]' ]
    [ , [ @blind_copy_recipients = ] 'blind_copy_recipient [ ; ...n ]' ]
    [ , [ @from_address = ] 'from_address' ]
    [ , [ @reply_to = ] 'reply_to' ]
    [ , [ @subject = ] N'subject' ]
    [ , [ @body = ] N'body' ]
    [ , [ @body_format = ] 'body_format' ]
    [ , [ @importance = ] 'importance' ]
    [ , [ @sensitivity = ] 'sensitivity' ]
    [ , [ @file_attachments = ] N'attachment [ ; ...n ]' ]
    [ , [ @query = ] N'query' ]
    [ , [ @execute_query_database = ] 'execute_query_database' ]
    [ , [ @attach_query_result_as_file = ] attach_query_result_as_file ]
    [ , [ @query_attachment_filename = ] N'query_attachment_filename' ]
    [ , [ @query_result_header = ] query_result_header ]
    [ , [ @query_result_width = ] query_result_width ]
    [ , [ @query_result_separator = ] 'query_result_separator' ]
    [ , [ @exclude_query_output = ] exclude_query_output ]
    [ , [ @append_query_error = ] append_query_error ]
    [ , [ @query_no_truncate = ] query_no_truncate ]
    [ , [ @query_result_no_padding = ] @query_result_no_padding ]
    [ , [ @mailitem_id = ] mailitem_id ] [ OUTPUT ]
[ ; ]

Arguments

[ @profile_name = ] 'profile_name'

Nom du profil à partir duquel envoyer le message. La @profile_name est de type sysname, avec une valeur par défaut .NULL Le @profile_name doit être le nom d’un profil de messagerie de base de données existant. Lorsqu’aucun @profile_name n’est spécifié, sp_send_dbmail utilise le profil privé par défaut pour l’utilisateur actuel. Si l’utilisateur n’a pas de profil privé par défaut, sp_send_dbmail utilise le profil public par défaut pour la msdb base de données. Si l’utilisateur n’a pas de profil privé par défaut et qu’il n’existe aucun profil public par défaut pour la base de données, @profile_name doit être spécifié.

[ @recipients = ] 'recipients'

Liste délimitée par des points-virgules d’adresses de messagerie à laquelle envoyer le message. La liste des destinataires est de type varchar(max). Bien que ce paramètre soit facultatif, au moins un des @recipients, @copy_recipients ou @blind_copy_recipients doivent être spécifiés, ou sp_send_dbmail retourne une erreur.

[ @copy_recipients = ] 'copy_recipients'

Liste délimitée par des points-virgules d’adresses de messagerie vers laquelle copier le message en carbone. La liste des destinataires de copie est de type varchar(max). Bien que ce paramètre soit facultatif, au moins un des @recipients, @copy_recipients ou @blind_copy_recipients doivent être spécifiés, ou sp_send_dbmail retourne une erreur.

[ @blind_copy_recipients = ] 'blind_copy_recipients'

Liste délimitée par des points-virgules d’adresses de messagerie vers laquelle copier le message en carbone aveugle. La liste des destinataires de copie aveugle est de type varchar(max). Bien que ce paramètre soit facultatif, au moins un des @recipients, @copy_recipients ou @blind_copy_recipients doivent être spécifiés, ou sp_send_dbmail retourne une erreur.

[ @from_address = ] 'from_address'

Valeur de l’adresse « from address » de l’e-mail. Il s'agit d'un paramètre optionnel utilisé pour remplacer les paramètres dans le profil de messagerie. Ce paramètre est de type varchar(max). Les paramètres de sécurité SMTP déterminent si ces substitutions sont acceptées. Si aucun paramètre n’est spécifié, la valeur par défaut est NULL.

[ @reply_to = ] 'reply_to'

Valeur de la « réponse à l’adresse » du message électronique. Une seule adresse de messagerie est acceptée comme valeur valide. Il s'agit d'un paramètre optionnel utilisé pour remplacer les paramètres dans le profil de messagerie. Ce paramètre est de type varchar(max). Les paramètres de sécurité SMTP déterminent si ces substitutions sont acceptées. Si aucun paramètre n’est spécifié, la valeur par défaut est NULL.

[ @subject = ] N’subject'

Objet du message électronique. L’objet est de type nvarchar(255). Si l'objet est omis, « Message SQL Server » est la valeur par défaut.

[ @body = ] N’body'

Corps du message électronique. Le corps du message est de type nvarchar(max), avec la valeur par défaut NULL.

[ @body_format = ] 'body_format'

Format du corps du message. Le paramètre est de type varchar(20), avec la valeur par défaut NULL. Lorsqu'il est spécifié, les en-têtes du message sortant sont définis pour indiquer le format choisi pour le corps de message. Le paramètre peut contenir l’une des valeurs suivantes :

  • TEXT (valeur par défaut)
  • HTML

[ @importance = ] 'importance'

Importance du message. Le paramètre est de type varchar(6). Le paramètre peut contenir l’une des valeurs suivantes :

  • Low
  • Normal (valeur par défaut)
  • High

[ @sensitivity = ] 'sensibilité'

Sensibilité du message. Le paramètre est de type varchar(12). Le paramètre peut contenir l’une des valeurs suivantes :

  • Normal (valeur par défaut)
  • Personal
  • Private
  • Confidential

[ @file_attachments = ] N’file_attachments'

Liste délimitée par des points-virgules des noms de fichiers à joindre au message électronique. Les fichiers de la liste doivent être spécifiés sous forme de chemins d'accès absolus. La liste des pièces jointes est de type nvarchar(max). Par défaut, la messagerie de base de données limite la taille des pièces jointes à 1 Mo par fichier.

Important

Ce paramètre n’est pas disponible dans Azure SQL Managed Instance, car il ne peut pas accéder au système de fichiers local.

[ @query = ] N’query'

Requête à exécuter. Les résultats de la requête sont inclus dans le corps du message électronique ou attachés comme pièce jointe. La requête est de type nvarchar(max) et peut contenir n’importe quelle instruction Transact-SQL valide. La requête est exécutée dans une session distincte, de sorte que les variables locales dans l’appel sp_send_dbmail de script ne sont pas disponibles pour la requête.

Lorsque vous utilisez le paramètre @query , le principal qui s’exécute sp_send_dbmail doit être connecté en tant qu’individu, et non dans le cadre d’un groupe, qu’il s’agisse d’un ID Microsoft Entra (anciennement Azure Active Directory) ou d’un groupe Windows Active Directory. Les connexions SQL Server, les identités Windows et les identités Microsoft Entra peuvent exécuter la requête, mais les membres du groupe ne peuvent pas, en raison de l’emprunt d’identité d’Azure SQL Managed Instance et des limitations EXECUTE AS.

[ @execute_query_database = ] 'execute_query_database'

Contexte de base de données dans lequel la procédure stockée exécute la requête. Le paramètre est de type sysname, avec une valeur par défaut de la base de données active. Ce paramètre s’applique uniquement si @query est spécifié.

[ @attach_query_result_as_file = ] attach_query_result_as_file

Indique si l'ensemble de résultats de la requête est retourné comme pièce jointe. @attach_query_result_as_file est de type bit, avec une valeur par défaut .0

Lorsque la valeur est 0, les résultats de la requête sont inclus dans le corps du message électronique, après le contenu du paramètre @body . Lorsque la valeur est 1, les résultats sont retournés sous forme de pièce jointe. Ce paramètre s’applique uniquement si @query est spécifié.

[ @query_attachment_filename = ] N’query_attachment_filename'

Précise le nom de fichier à utiliser pour la pièce jointe de l'ensemble de résultats de la requête. @query_attachment_filename est de type nvarchar(255), avec la valeur par défaut NULL. Ce paramètre est ignoré lorsque @attach_query_result_as_file est 0. Lorsque @attach_query_result_as_file est et que ce paramètre est 1NULL, Database Mail crée un nom de fichier arbitraire.

[ @query_result_header = ] query_result_header

Spécifie si les résultats de la requête comportent des en-têtes de colonne. La valeur query_result_header est de type bit. Lorsque la valeur est 1, les résultats de la requête contiennent des en-têtes de colonne. Lorsque la valeur est 0, les résultats de la requête n’incluent pas d’en-têtes de colonne. Ce paramètre est défini par défaut sur 1. Ce paramètre s’applique uniquement si @query est spécifié.

L’erreur suivante peut se produire lors de la définition de @query_result_header sur 0 et de la définition de @query_no_truncate sur 1:

Msg 22050, Level 16, State 1, Line 12: Failed to initialize sqlcmd library with error number -2147024809.

[ @query_result_width = ] query_result_width

Largeur de ligne, en caractères, à utiliser pour mettre en forme les résultats de la requête. La @query_result_width est de type int, avec une valeur par défaut .256 La valeur fournie doit être comprise entre 10 et 32767. Ce paramètre s’applique uniquement si @query est spécifié.

[ @query_result_separator = ] 'query_result_separator'

Caractère utilisé pour séparer les colonnes dans la sortie de la requête. Le séparateur est de type char(1). ' ' Valeur par défaut (espace).

[ @exclude_query_output = ] exclude_query_output

Spécifie si la sortie de l'exécution de la requête doit être retournée dans le message électronique. @exclude_query_output est bit, avec la valeur par défaut 0. Lorsque ce paramètre est 0le cas, l’exécution de la sp_send_dbmail procédure stockée imprime le message retourné suite à l’exécution de la requête sur la console. Lorsque ce paramètre est 1, l’exécution de la sp_send_dbmail procédure stockée n’imprime aucun des messages d’exécution de requête sur la console.

[ @append_query_error = ] append_query_error

Spécifie s’il faut envoyer le courrier électronique lorsqu’une erreur revient de la requête spécifiée dans l’argument @query. @append_query_error est bit, avec la valeur par défaut 0. Lorsque ce paramètre est 1le cas, la messagerie de base de données envoie le message électronique et inclut le message d’erreur de requête dans le corps du message électronique. Lorsque ce paramètre est 0le cas, la messagerie de base de données n’envoie pas le message électronique et sp_send_dbmail se termine par le code 1de retour, ce qui indique l’échec.

[ @query_no_truncate = ] query_no_truncate

Spécifie s’il faut exécuter la requête avec l’option qui évite la troncation de types de données de longueur variable volumineux (varchar(max), nvarchar(max), varbinary(max), xml, text, ntext, image et types de données définis par l’utilisateur). Lorsque vous définissez, les résultats de la requête n’incluent pas d’en-têtes de colonne. La valeur @query_no_truncate est de type bit. Lorsque la valeur est 0 spécifiée ou non, les colonnes de la requête tronquent à 256 caractères. Lorsque la valeur est 1, les colonnes de la requête ne sont pas tronquées. Ce paramètre est défini par défaut sur 0.

Remarque

Lorsqu’elle est utilisée avec de grandes quantités de données, l’option @query_no_truncate consomme des ressources supplémentaires et peut ralentir les performances du serveur.

[ @query_result_no_padding = ] query_result_no_padding

Le type est bit. Par défaut, il s’agit de 0. Lorsque vous définissez 1sur , les résultats de la requête ne sont pas rembourrés, ce qui réduit éventuellement la taille du fichier. Si vous définissez 1@query_result_no_padding et définissez le paramètre @query_result_width, le paramètre @query_result_no_padding remplace le paramètre @query_result_width.

Dans ce cas, aucune erreur ne se produit.

L’erreur suivante peut se produire lors de la définition de @query_result_no_padding et 1 de la fourniture d’un paramètre pour @query_no_truncate :

Msg 22050, Level 16, State 1, Line 0: Failed to execute the query because the @query_result_no_append and @query_no_truncate options are mutually exclusive.

Si vous définissez le @query_result_no_padding1 sur et que vous définissez le paramètre @query_no_truncate , une erreur est générée.

[ @mailitem_id = ] mailitem_id [ OUTPUT ]

Le paramètre de sortie facultatif retourne le mailitem_id message. @mailitem_id est de type int.

Valeurs des codes de retour

Code de retour des moyens de 0 réussite. Une autre valeur signifie l'échec. Code d’erreur de l’instruction qui a échoué est stocké dans la @@ERROR variable.

Jeu de résultats

En cas de succès, le message « Courrier en file d'attente » est renvoyé.

Notes

Avant d’utiliser, la messagerie de base de données doit être activée à l’aide de l’Assistant Configuration de la messagerie de base de données, ou sp_configure.

sysmail_stop_sp arrête la messagerie de base de données en arrêtant les objets Service Broker que le programme externe utilise. sp_send_dbmail accepte toujours le courrier lorsque la messagerie de base de données est arrêtée à l’aide sysmail_stop_sp. Pour démarrer la messagerie de base de données, utilisez sysmail_start_sp.

Quand @profile n’est pas spécifié, sp_send_dbmail utilise un profil par défaut. Si l'utilisateur expéditeur du message électronique a un profil privé par défaut, la messagerie de base de données utilise ce profil. Si l’utilisateur n’a pas de profil privé par défaut, sp_send_dbmail utilise le profil public par défaut. S’il n’existe aucun profil privé par défaut pour l’utilisateur et aucun profil public par défaut, sp_send_dbmail retourne une erreur.

sp_send_dbmail ne prend pas en charge les messages électroniques sans contenu. Pour envoyer un message électronique, vous devez spécifier au moins l’un des @body, @query, @file_attachments ou @subject. Sinon, sp_send_dbmail retourne une erreur.

La messagerie de base de données utilise le contexte de sécurité Microsoft Windows de l’utilisateur actuel pour contrôler l’accès aux fichiers. Par conséquent, les utilisateurs authentifiés avec l’authentification SQL Server ne peuvent pas joindre de fichiers à l’aide de @file_attachments. Windows n’autorise pas SQL Server à fournir des informations d’identification d’un ordinateur distant à un autre ordinateur distant. Par conséquent, la messagerie de base de données peut ne pas être en mesure d’attacher des fichiers à partir d’un partage réseau dans les cas où la commande est exécutée à partir d’un ordinateur autre que l’ordinateur sur lequel SQL Server s’exécute.

Si les @query et les @file_attachments sont spécifiés et que le fichier est introuvable, la requête est toujours exécutée, mais l’e-mail n’est pas envoyé.

Lorsqu'une requête est spécifiée, l'ensemble de résultats se présente sous la forme d'un texte inséré. Les données binaires contenues dans le résultat sont envoyées au format hexadécimal.

Les paramètres @recipients, @copy_recipients et @blind_copy_recipients sont des listes délimitées par des points-virgules d’adresses de messagerie. Au moins un de ces paramètres doit être fourni ou sp_send_dbmail retourne une erreur.

Lors de l’exécution sp_send_dbmail sans contexte de transaction, La messagerie de base de données démarre et valide une transaction implicite. Lors de l’exécution sp_send_dbmail à partir d’une transaction existante, Database Mail s’appuie sur l’utilisateur pour valider ou restaurer les modifications. Elle ne démarre pas une transaction interne.

Autorisations

Exécutez les autorisations par sp_send_dbmail défaut pour tous les membres du rôle de base de données DatabaseMailUser dans la msdb base de données. Toutefois, lorsque l’utilisateur envoyant le message n’a pas l’autorisation d’utiliser le profil pour la demande, sp_send_dbmail retourne une erreur et n’envoie pas le message.

Exemples

R. Envoyer un message électronique

Cet exemple envoie un message électronique à votre ami à l’aide de l’adresse myfriend@adventure-works.comde messagerie. Le message a comme objet Automated Success Message. Le corps du message contient la phrase The stored procedure finished successfully.

EXEC msdb.dbo.sp_send_dbmail
    @profile_name = 'Adventure Works Administrator',
    @recipients = 'yourfriend@adventure-works.com',
    @body = 'The stored procedure finished successfully.',
    @subject = 'Automated Success Message';

B. Envoyer un message électronique avec les résultats d’une requête

Cet exemple envoie un message électronique à votre ami à l’aide de l’adresse yourfriend@adventure-works.comde messagerie. Le message a l’objet Work Order Countet exécute une requête qui affiche le nombre de commandes de travail avec moins DueDate de deux jours après le 30 avril 2022. La messagerie de base de données joint le résultat au courrier sous la forme d'un fichier texte.

EXEC msdb.dbo.sp_send_dbmail
    @profile_name = 'Adventure Works Administrator',
    @recipients = 'yourfriend@adventure-works.com',
    @query = 'SELECT COUNT(*) FROM AdventureWorks2022.Production.WorkOrder
                  WHERE DueDate > ''2022-04-30''
                  AND  DATEDIFF(dd, ''2022-04-30'', DueDate) < 2',
    @subject = 'Work Order Count',
    @attach_query_result_as_file = 1;

C. Envoyer un message électronique HTML

Cet exemple envoie un message électronique à votre ami à l’aide de l’adresse yourfriend@adventure-works.comde messagerie. Le message a l’objet Work Order Listet contient un document HTML qui affiche les commandes de travail avec moins DueDate de deux jours après le 30 avril 2022. La messagerie de base de données envoie le message au format HTML.

DECLARE @tableHTML NVARCHAR(MAX);

SET @tableHTML = N'<H1>Work Order Report</H1>' + N'<table border="1">'
    + N'<tr><th>Work Order ID</th><th>Product ID</th>'
    + N'<th>Name</th><th>Order Qty</th><th>Due Date</th>'
    + N'<th>Expected Revenue</th></tr>'
    + CAST((
            SELECT td = wo.WorkOrderID, '',
                td = p.ProductID, '',
                td = p.Name, '',
                td = wo.OrderQty, '',
                td = wo.DueDate, '',
                td = (p.ListPrice - p.StandardCost) * wo.OrderQty
            FROM AdventureWorks.Production.WorkOrder AS wo
            INNER JOIN AdventureWorks.Production.Product AS p
                ON wo.ProductID = p.ProductID
            WHERE DueDate > '2022-04-30'
                AND DATEDIFF(dd, '2022-04-30', DueDate) < 2
            ORDER BY DueDate ASC,
                (p.ListPrice - p.StandardCost) * wo.OrderQty DESC
            FOR XML PATH('tr'),
                TYPE
            ) AS NVARCHAR(MAX))
    + N'</table>';

EXEC msdb.dbo.sp_send_dbmail @recipients = 'yourfriend@adventure-works.com',
    @subject = 'Work Order List',
    @body = @tableHTML,
    @body_format = 'HTML';

Contenu connexe