sp_send_dbmail (Transact-SQL)

Gilt für:SQL ServerAzure SQL Managed Instance

Sendet eine E-Mail-Nachricht an die angegebenen Empfänger. Die Nachricht kann ein Abfrageresultset, Dateianlagen oder beides enthalten. Wenn E-Mails erfolgreich in der Datenbank-E-Mail-Warteschlange platziert wurden, sp_send_dbmail gibt den der mailitem_id Nachricht zurück. Diese gespeicherte Prozedur befindet sich in der msdb Datenbank.

Transact-SQL-Syntaxkonventionen

Syntax

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 ]
[ ; ]

Argumente

[ @profile_name = ] 'profile_name'

Der Name des Profils, von dem die Nachricht gesendet werden soll. Die @profile_name ist vom Typ sysname, wobei der Standardwert NULL ist. Der @profile_name muss der Name eines vorhandenen Datenbank-E-Mail-Profils sein. Wenn keine @profile_name angegeben ist, sp_send_dbmail verwendet das private Standardprofil für den aktuellen Benutzer. Wenn der Benutzer kein privates Standardprofil hat, sp_send_dbmail verwendet das öffentliche Standardprofil für die msdb Datenbank. Wenn der Benutzer kein privates Standardprofil hat und kein öffentliches Standardprofil für die Datenbank vorhanden ist, muss @profile_name angegeben werden.

[ @recipients = ] 'Recipients'

Eine durch Semikolon getrennte Liste von E-Mail-Adressen, an die die Nachricht gesendet werden soll. Die Empfängerliste ist vom Typ varchar(max). Obwohl dieser Parameter optional ist, muss mindestens einer der @recipients, @copy_recipients oder @blind_copy_recipients angegeben werden oder sp_send_dbmail gibt einen Fehler zurück.

[ @copy_recipients = ] 'copy_recipients'

Eine durch Semikolons getrennte Liste von E-Mail-Adressen, in die die Nachricht per Carbon kopiert werden soll. Die Liste der Kopierempfänger ist vom Typ varchar(max). Obwohl dieser Parameter optional ist, muss mindestens einer der @recipients, @copy_recipients oder @blind_copy_recipients angegeben werden oder sp_send_dbmail gibt einen Fehler zurück.

[ @blind_copy_recipients = ] 'blind_copy_recipients'

Eine durch Semikolon getrennte Liste von E-Mail-Adressen, in die die Nachricht mit blindem Carbon kopiert werden soll. Die Empfängerliste für blinde Kopien hat den Typ varchar(max).. Obwohl dieser Parameter optional ist, muss mindestens einer der @recipients, @copy_recipients oder @blind_copy_recipients angegeben werden oder sp_send_dbmail gibt einen Fehler zurück.

[ @from_address = ] 'from_address'

Der Wert des "from address" der E-Mail-Nachricht. Dies ist ein optionaler Parameter, mit dem die Einstellungen im Mailprofil überschrieben werden. Dieser Parameter ist vom Typ varchar(max). SMTP-Sicherheitseinstellungen stellen fest, ob diese Überschreibungen akzeptiert werden. Wenn kein Parameter angegeben ist, wird der Standardwert NULL verwendet.

[ @reply_to = ] 'reply_to'

Der Wert der Antwort auf die Adresse der E-Mail-Nachricht. Er akzeptiert nur eine E-Mail-Adresse als gültigen Wert. Dies ist ein optionaler Parameter, mit dem die Einstellungen im Mailprofil überschrieben werden. Dieser Parameter ist vom Typ varchar(max). SMTP-Sicherheitseinstellungen stellen fest, ob diese Überschreibungen akzeptiert werden. Wenn kein Parameter angegeben ist, wird der Standardwert NULL verwendet.

[ @subject = ] N'subject'

Der Betreff der E-Mail. Der Betreff ist vom Typ nvarchar(255). Wenn Sie keinen Betreff angeben, wird standardmäßig 'SQL Server-Nachricht' verwendet.

[ @body = ] N'body'

Der Text der E-Mail-Nachricht. Der Nachrichtentext ist vom Typ nvarchar(max) mit dem Standardwert NULL.

[ @body_format = ] 'body_format'

Das Format des Nachrichtentexts. Der Parameter ist vom Typ varchar(20) mit dem Standardwert NULL. Wenn der Parameter angegeben ist, wird in den Headern der ausgehenden Nachricht angezeigt, dass der Nachrichtentext das angegebene Format besitzt. Der Parameter kann einen der folgenden Werte enthalten:

• TEXT (Standard)
• HTML

[ @importance = ] 'Wichtigkeit'

Die Wichtigkeit der Meldung. Der Parameter ist vom Typ varchar(6). Der Parameter kann einen der folgenden Werte enthalten:

• Low
• Normal (Standard)
• High

[ @sensitivity = ] 'Sensitivität'

Die Vertraulichkeit der Nachricht. Der Parameter ist vom Typ varchar(12). Der Parameter kann einen der folgenden Werte enthalten:

• Normal (Standard)
• Personal
• Private
• Confidential

[ @file_attachments = ] N'file_attachments'

Eine durch Semikolons getrennte Liste von Dateinamen, die an die E-Mail-Nachricht angefügt werden sollen. Die Dateien in der Liste müssen als absolute Pfade angegeben sein. Die Anlagenliste ist vom Typ nvarchar(max). Standardmäßig beschränkt Datenbank-E-Mail Dateianlagen auf 1 MB pro Datei.

Wichtig

Dieser Parameter ist in Azure SQL Managed Instance nicht verfügbar, da er nicht auf das lokale Dateisystem zugreifen kann.

[ @query = ] N'query'

Eine auszuführende Abfrage. Die Ergebnisse der Abfrage können als Datei angefügt oder in den Text der E-Mail-Nachricht eingeschlossen werden. Die Abfrage hat den Typ nvarchar(max) und kann alle gültigen Transact-SQL-Anweisungen enthalten. Die Abfrage wird in einer separaten Sitzung ausgeführt, sodass lokale Variablen in den Skriptaufrufen sp_send_dbmail für die Abfrage nicht verfügbar sind.

Wenn Sie den Parameter @query verwenden, muss der benutzer, der ausgeführt sp_send_dbmail wird, ein SQL Server-Anmeldename sein oder direkt dem Prinzipal (Anmeldung) von Azure AD oder Windows Active Directory zugeordnet sein. Wenn der Benutzer Mitglied einer Azure AD-Gruppe oder einer Windows Active Directory-Gruppe ist, kann er die Abfrage nicht ausführen. Dies ist auf Azure SQL Managed Instance Identitätswechsel und EXECUTE AS-Einschränkungen zurückzuführen.

[ @execute_query_database = ] 'execute_query_database'

Der Datenbankkontext, in dem die gespeicherte Prozedur die Abfrage ausführt. Der Parameter ist vom Typ sysname, wobei der Standardwert die aktuelle Datenbank ist. Dieser Parameter gilt nur, wenn @query angegeben ist.

[ @attach_query_result_as_file = ] attach_query_result_as_file

Gibt an, ob das Resultset der Abfrage als Anlage zurückgegeben wird. @attach_query_result_as_file vom Typ Bit mit dem Standardwert 0.

Wenn der Wert ist 0, werden die Abfrageergebnisse im Textkörper der E-Mail-Nachricht nach dem Inhalt des @body-Parameters eingeschlossen. Wenn der Wert ist 1, werden die Ergebnisse als Anlage zurückgegeben. Dieser Parameter gilt nur, wenn @query angegeben ist.

[ @query_attachment_filename = ] N'query_attachment_filename'

Gibt an, welcher Dateiname für das Resultset der Abfrageanlage verwendet wird. @query_attachment_filename ist vom Typ nvarchar(255) mit dem Standardwert NULL. Dieser Parameter wird ignoriert, wenn @attach_query_result_as_file ist 0. Wenn @attach_query_result_as_file ist 1 und dieser Parameter NULL ist, erstellt Datenbank-E-Mail einen beliebigen Dateinamen.

[ @query_result_header = ] query_result_header

Gibt an, ob die Abfrageergebnisse Spaltenheader einschließen. Der query_result_header Wert ist vom Typ Bit. Wenn der Wert ist 1, enthalten Abfrageergebnisse Spaltenüberschriften. Wenn der Wert ist 0, enthalten Abfrageergebnisse keine Spaltenüberschriften. Dieser Parameter ist standardmäßig .1 Dieser Parameter gilt nur, wenn @query angegeben ist.

Der folgende Fehler kann auftreten, wenn @query_result_header auf 0 und @query_no_truncate auf 1festgelegt wird:

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

[ @query_result_width = ] query_result_width

Die Zeilenbreite in Zeichen, die zum Formatieren der Abfrageergebnisse verwendet werden soll. Die @query_result_width ist vom Typ int, wobei der Standardwert ist 256. Der angegebene Wert muss zwischen 10 und 32767sein. Dieser Parameter gilt nur, wenn @query angegeben ist.

[ @query_result_separator = ] 'query_result_separator'

Das Zeichen, das zum Trennen der Spalten in der Abfrageausgabe verwendet wird. Das Trennzeichen ist vom Typ char(1). Der Standardwert ist ' ' (Leerzeichen).

[ @exclude_query_output = ] exclude_query_output

Gibt an, ob die Ausgabe der Abfrageausführung in der E-Mail-Nachricht zurückgegeben werden soll. @exclude_query_output ist Bit mit dem Standardwert 0. Wenn dieser Parameter ist, gibt 0die Ausführung der sp_send_dbmail gespeicherten Prozedur die Nachricht aus, die als Ergebnis der Abfrageausführung in der Konsole zurückgegeben wird. Wenn dieser Parameter ist 1, gibt die Ausführung der sp_send_dbmail gespeicherten Prozedur keine der Abfrageausführungsmeldungen in der Konsole aus.

[ @append_query_error = ] append_query_error

Gibt an, ob die E-Mail gesendet werden soll, wenn ein Fehler von der im argument @query angegebenen Abfrage zurückgegeben wird. @append_query_error ist Bit, wobei der Standardwert lautet 0. Wenn dieser Parameter ist1, sendet Datenbank-E-Mail die E-Mail-Nachricht und schließt die Abfragefehlermeldung in den Text der E-Mail-Nachricht ein. Wenn dieser Parameter ist0, sendet Datenbank-E-Mail die E-Mail-Nachricht nicht und sp_send_dbmail endet mit dem Rückgabecode1, der auf einen Fehler hinweist.

[ @query_no_truncate = ] query_no_truncate

Gibt an, ob die Abfrage mit der Option ausgeführt werden soll, die das Abschneiden von Datentypen mit großer Variabler Länge (varchar(max), nvarchar(max), varbinary(max), xml, text, ntext, image und benutzerdefinierte Datentypen vermeidet. Wenn sie festgelegt sind, enthalten abfrageergebnisse keine Spaltenüberschriften. Der @query_no_truncate Wert ist vom Typ Bit. Wenn der Wert angegeben ist 0 oder nicht, kürzen Spalten in der Abfrage auf 256 Zeichen. Wenn der Wert ist 1, werden spalten in der Abfrage nicht abgeschnitten. Dieser Parameter ist standardmäßig .0

Hinweis

Bei Verwendung mit großen Datenmengen verbraucht die Option @query_no_truncate zusätzliche Ressourcen und kann die Serverleistung beeinträchtigen.

[ @query_result_no_padding = ] query_result_no_padding

Der Typ ist Bit. Der Standardwert ist 0. Wenn Sie auf 1festlegen, werden die Abfrageergebnisse nicht aufgefüllt, was möglicherweise die Dateigröße reduziert. Wenn Sie auf 1 festlegen @query_result_no_padding und den parameter @query_result_width festlegen, überschreibt der parameter @query_result_no_padding den parameter @query_result_width.

In diesem Fall tritt kein Fehler auf.

Der folgende Fehler kann auftreten, wenn sie @query_result_no_padding auf 1 festlegen und einen Parameter für @query_no_truncate bereitstellen:

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.

Wenn Sie die @query_result_no_padding auf 1 und den parameter @query_no_truncate festlegen, wird ein Fehler ausgelöst.

[ @mailitem_id = ] mailitem_id [ OUTPUT ]

Optionaler Ausgabeparameter gibt den der mailitem_id Nachricht zurück. @mailitem_id vom Typ int.

Rückgabecodewerte

Ein Rückgabecode von 0 bedeutet Erfolg. Ein beliebiger anderer Wert steht für Fehler. Der Fehlercode für die fehlerhafte Anweisung wird in der @@ERROR Variablen gespeichert.

Resultsets

Bei Erfolg wird die Nachricht "E-Mail in der Warteschlange" zurückgegeben.

Bemerkungen

Vor der Verwendung muss Datenbank-E-Mail mithilfe des Datenbank-E-Mail-Konfigurations-Assistenten oder sp_configureaktiviert werden.

sysmail_stop_spbeendet Datenbank-E-Mail, indem die Service Broker-Objekte beendet werden, die das externe Programm verwendet. sp_send_dbmailakzeptiert weiterhin E-Mails, wenn Datenbank-E-Mail mit sysmail_stop_spbeendet wird. Um Datenbank-E-Mail zu starten, verwenden Sie sysmail_start_sp.

Wenn @profile nicht angegeben ist, sp_send_dbmail wird ein Standardprofil verwendet. Falls der Benutzer, der die E-Mail-Nachricht sendet, über ein privates Standardprofil verfügt, verwendet Datenbank-E-Mail dieses Profil. Wenn der Benutzer über kein privates Standardprofil verfügt, sp_send_dbmail wird das öffentliche Standardprofil verwendet. Wenn kein privates Standardprofil für den Benutzer und kein öffentliches Standardprofil vorhanden ist, sp_send_dbmail wird ein Fehler zurückgegeben.

sp_send_dbmail unterstützt keine E-Mail-Nachrichten ohne Inhalt. Zum Senden einer E-Mail-Nachricht müssen Sie mindestens eine der @body, @query, @file_attachments oder @subject angeben. Andernfalls sp_send_dbmail wird ein Fehler zurückgegeben.

Datenbank-E-Mail verwendet den Microsoft Windows-Sicherheitskontext des aktuellen Benutzers, um den Zugriff auf Dateien zu steuern. Daher können Benutzer, die mit SQL Server-Authentifizierung authentifiziert sind, keine Dateien mithilfe von @file_attachments anfügen. Windows erlaubt es SQL Server nicht, Anmeldeinformationen von einem Remotecomputer an einen anderen Remotecomputer bereitzustellen. Daher können Datenbank-E-Mail möglicherweise keine Dateien von einer Netzwerkfreigabe anfügen, wenn der Befehl von einem anderen Computer als dem Computer ausgeführt wird, auf dem SQL Server ausgeführt wird.

Wenn sowohl @query als auch @file_attachments angegeben sind und die Datei nicht gefunden werden kann, wird die Abfrage weiterhin ausgeführt, aber die E-Mail wird nicht gesendet.

Wird eine Abfrage angegeben, wird das Resultset als Inlinetext formatiert. Binärdaten im Ergebnis werden im hexadezimalen Format gesendet.

Die Parameter @recipients, @copy_recipients und @blind_copy_recipients sind durch Semikolons getrennte Listen von E-Mail-Adressen. Mindestens einer dieser Parameter muss bereitgestellt werden, oder sp_send_dbmail gibt einen Fehler zurück.

Wenn sie ohne Transaktionskontext ausgeführt wirdsp_send_dbmail, startet Datenbank-E-Mail eine implizite Transaktion und führt einen Commit aus. Bei der Ausführung sp_send_dbmail innerhalb einer vorhandenen Transaktion ist Datenbank-E-Mail darauf angewiesen, dass der Benutzer änderungen entweder committet oder zurückrollt. Es wird keine innere Transaktion gestartet.

Berechtigungen

Führen Sie standardmäßig Berechtigungen für sp_send_dbmail alle Mitglieder der Datenbankrolle DatabaseMailUser in der msdb Datenbank aus. Wenn der Benutzer, der die Nachricht sendet, jedoch nicht berechtigt ist, das Profil für die Anforderung zu verwenden, sp_send_dbmail gibt einen Fehler zurück und sendet die Nachricht nicht.

Beispiele

A. Senden einer E-Mail-Nachricht

In diesem Beispiel wird eine E-Mail-Nachricht mit der E-Mail-Adresse myfriend@adventure-works.coman Ihren Freund gesendet. Die Nachricht hat den Betreff Automated Success Message. Der Nachrichtentext enthält den Satz '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. Senden einer E-Mail-Nachricht mit den Ergebnissen einer Abfrage

In diesem Beispiel wird eine E-Mail-Nachricht mit der E-Mail-Adresse yourfriend@adventure-works.coman Ihren Freund gesendet. Die Nachricht hat den Betreff Work Order Countund führt eine Abfrage aus, die die Anzahl der Arbeitsaufträge mit weniger DueDate als zwei Tagen nach dem 30. April 2022 anzeigt. Das Ergebnis wird als Textdatei von Datenbank-E-Mail angefügt.

EXEC msdb.dbo.sp_send_dbmail
    @profile_name = 'Adventure Works Administrator',
    @recipients = 'yourfriend@adventure-works.com',
    @query = 'SELECT COUNT(*) FROM AdventureWorks2012.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. Senden einer HTML-E-Mail-Nachricht

In diesem Beispiel wird eine E-Mail-Nachricht mit der E-Mail-Adresse yourfriend@adventure-works.coman Ihren Freund gesendet. Die Nachricht hat den Betreff Work Order Listund enthält ein HTML-Dokument, das die Arbeitsaufträge weniger DueDate als zwei Tage nach dem 30. April 2022 anzeigt. Das Ergebnis wird im HTML-Format von Datenbank-E-Mail gesendet.

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';

Siehe auch

• Datenbank-E-Mail
• Konfigurationsobjekte für Datenbank-E-Mail
• Gespeicherte Prozeduren für Datenbank-E-Mail (Transact-SQL)
• sp_addrolemember (Transact-SQL)