sp_send_dbmail (Transact-SQL)

  • Artikel

Gilt für:SQL ServerAzure SQL Managed Instance

Sendet eine E-Mail-Nachricht an die angegebenen Empfänger. Die Nachricht kann ein Abfrageergebnissatz, Dateianlagen oder beides enthalten. Wenn E-Mails erfolgreich in der Datenbank-E-Mail Warteschlange platziert werden, sp_send_dbmail wird die mailitem_id Nachricht zurückgegeben. 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" mit einem Standardwert von NULL. Die @profile_name muss der Name eines vorhandenen Datenbank-E-Mail Profils sein. Wenn keine @profile_name angegeben wird, sp_send_dbmail wird das standard private Profil für den aktuellen Benutzer verwendet. Wenn der Benutzer nicht über ein standardmäßiges privates Profil verfügt, sp_send_dbmail wird das standard öffentliche Profil für die msdb Datenbank verwendet. Wenn der Benutzer nicht über ein standardmäßiges privates Profil verfügt und für die Datenbank kein standard öffentliches Profil vorhanden ist, muss @profile_name angegeben werden.

[ @recipients = ] 'Empfänger'

Eine durch Semikolons 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 von @recipients, @copy_recipients oder @blind_copy_recipients angegeben werden oder sp_send_dbmail ein Fehler zurückgegeben werden.

[ @copy_recipients = ] 'copy_recipients'

Eine durch Semikolons getrennte Liste von E-Mail-Adressen, in die die Nachricht kopiert werden soll. Die Empfängerliste der Kopie ist vom Typ varchar(max). Obwohl dieser Parameter optional ist, muss mindestens einer von @recipients, @copy_recipients oder @blind_copy_recipients angegeben werden oder sp_send_dbmail ein Fehler zurückgegeben werden.

[ @blind_copy_recipients = ] 'blind_copy_recipients'

Eine durch Semikolons getrennte Liste von E-Mail-Adressen, in die die Nachricht blind kopiert werden soll. Die Empfängerliste für Blindkopien ist vom Typ varchar(max). Obwohl dieser Parameter optional ist, muss mindestens einer von @recipients, @copy_recipients oder @blind_copy_recipients angegeben werden oder sp_send_dbmail ein Fehler zurückgegeben werden.

[ @from_address = ] 'from_address'

Der Wert der "Von Adresse" 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, lautet NULLder Standardwert .

[ @reply_to = ] 'reply_to'

Der Wert der "Antwort auf 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, lautet NULLder Standardwert .

[ @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 der Standardeinstellung " NULL.

[ @body_format = ] 'body_format'

Das Format des Nachrichtentexts. Der Parameter ist vom Typ varchar(20) mit einem Standardwert von 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 = ] 'Vertraulichkeit'

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 verwaltete Instanz 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 ist vom Typ "nvarchar(max)" und kann alle gültigen Transact-SQL-Anweisungen enthalten. Die Abfrage wird in einer separaten Sitzung ausgeführt, sodass lokale Variablen im Skriptaufruf sp_send_dbmail für die Abfrage nicht verfügbar sind.

Wenn Sie den parameter @query verwenden, muss der Prinzipal, der ausgeführt sp_send_dbmail wird, als Einzelperson verbunden sein, nicht als Teil einer Gruppe, unabhängig davon, ob eine Microsoft Entra-ID (früher Azure Active Directory) oder Windows Active Directory-Gruppe. SQL Server-Anmeldungen, Windows-Identitäten und Microsoft Entra-Identitäten können die Abfrage ausführen, gruppenmitglieder können jedoch aufgrund von Azure SQL verwaltete Instanz Identitätswechsel und EXECUTE AS-Einschränkungen nicht.

[ @execute_query_database = ] 'execute_query_database'

Der Datenbankkontext, in dem die gespeicherte Prozedur die Abfrage ausführt. Der Parameter ist vom Typ "sysname" mit einer Standardeinstellung der aktuellen Datenbank. Dieser Parameter gilt nur, wenn @query angegeben wird.

[ @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 ist vom Typ Bit mit einem Standardwert von 0.

Wenn der Wert lautet 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 wird.

[ @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 einem Standardwert von NULL. Dieser Parameter wird ignoriert, wenn @attach_query_result_as_file ist 0. Wenn @attach_query_result_as_file ist 1 und dieser Parameter lautetNULL, 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 lautet 1, enthalten abfrageergebnisse Spaltenüberschriften. Wenn der Wert lautet 0, enthalten abfrageergebnisse keine Spaltenüberschriften. Dieser Parameter ist standardmäßig auf 1. Dieser Parameter gilt nur, wenn @query angegeben wird.

Der folgende Fehler kann auftreten, wenn sie @query_result_header auf 0 @query_no_truncate festlegen:1

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 Ergebnisse der Abfrage verwendet werden soll. Die @query_result_width ist vom Typ "int" mit einem Standardwert von 256. Der angegebene Wert muss zwischen 10 und 32767. Dieser Parameter gilt nur, wenn @query angegeben wird.

[ @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). 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 einem Standardwert von 0. Wenn dieser Parameter lautet 0, druckt die Ausführung der sp_send_dbmail gespeicherten Prozedur die nachricht, die als Ergebnis der Abfrageausführung auf der Konsole zurückgegeben wird. Wenn dieser Parameter lautet 1, druckt die Ausführung der sp_send_dbmail gespeicherten Prozedur keine der Abfrageausführungsmeldungen in der Konsole.

[ @append_query_error = ] append_query_error

Gibt an, ob die E-Mail gesendet werden soll, wenn ein Fehler aus der abfrage zurückgegeben wird, die im argument @query angegeben ist. @append_query_error ist bit, mit einem Standardwert von 0. Wenn dieser Parameter lautet1, sendet Datenbank-E-Mail die E-Mail-Nachricht und enthält die Abfragefehlermeldung im Textkörper der E-Mail-Nachricht. Wenn dieser Parameter lautet0, sendet Datenbank-E-Mail die E-Mail-Nachricht nicht und sp_send_dbmail endet mit dem Rückgabecode1, der auf Fehler hinweist.

[ @query_no_truncate = ] query_no_truncate

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

Hinweis

Bei Verwendung mit großen Datenmengen verbraucht die option @query_no_truncate zusätzliche Ressourcen und kann die Serverleistung verlangsamen.

[ @query_result_no_padding = ] query_result_no_padding

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

In diesem Fall tritt kein Fehler auf.

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

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_padding1 festlegen und den @query_no_truncate-Parameter festlegen, wird ein Fehler ausgelöst.

[ @mailitem_id = ] mailitem_id [ OUTPUT ]

Optionaler Ausgabeparameter gibt die mailitem_id Nachricht zurück. @mailitem_id ist vom Typ "int" angegeben.

Rückgabecodewerte

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

Resultset

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

Hinweise

Vor der Verwendung muss Datenbank-E-Mail mit dem Konfigurations-Assistenten Datenbank-E-Mail oder sp_configureaktiviert sein.

sysmail_stop_spbeendet Datenbank-E-Mail, indem die vom externen Programm verwendeten Service Broker-Objekte beendet werden. sp_send_dbmailakzeptiert weiterhin E-Mails, wenn Datenbank-E-Mail nicht mehr verwendet sysmail_stop_spwird. 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 kein standardmäßiges privates Profil aufweist, sp_send_dbmail wird das öffentliche Standardprofil verwendet. Wenn für den Benutzer kein standardmäßiges privates Profil vorhanden ist 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 einen von @body, @query, @file_attachments oder @subject angeben. sp_send_dbmail Andernfalls wird ein Fehler zurückgegeben.

Datenbank-E-Mail verwendet den Sicherheitskontext von Microsoft Windows des aktuellen Benutzers, um den Zugriff auf Dateien zu steuern. Daher können Benutzer, die mit der SQL Server-Authentifizierung authentifiziert sind, keine Dateien mithilfe von @file_attachments anfügen. Windows lässt SQL Server nicht zu, Anmeldeinformationen von einem Remotecomputer an einen anderen Remotecomputer bereitzustellen. Daher können Datenbank-E-Mail möglicherweise keine Dateien aus 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, die E-Mail wird jedoch 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 angegeben oder ein Fehler zurückgegeben sp_send_dbmail werden.

Beim Ausführen sp_send_dbmail ohne Transaktionskontext startet Datenbank-E-Mail eine implizite Transaktion und führt einen Commit durch. Bei der Ausführung sp_send_dbmail innerhalb einer vorhandenen Transaktion ist Datenbank-E-Mail davon abhängig, dass der Benutzer entweder einen Commit ausführt oder änderungen zurückrollt. Eine innere Transaktion wird nicht gestartet.

Berechtigungen

Ausführen von Berechtigungen für sp_send_dbmail standardmäßige Elemente der Datenbankrolle "DatabaseMailUser " in der msdb Datenbank. Wenn der Benutzer, der die Nachricht sendet, jedoch nicht über die Berechtigung verfügt, 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 mithilfe der E-Mail-Adresse myfriend@adventure-works.comeine E-Mail-Nachricht an 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 mithilfe der E-Mail-Adresse yourfriend@adventure-works.comeine E-Mail-Nachricht an 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 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. Senden einer HTML-E-Mail-Nachricht

In diesem Beispiel wird mithilfe der E-Mail-Adresse yourfriend@adventure-works.comeine E-Mail-Nachricht an Ihren Freund gesendet. Die Nachricht hat den Betreff Work Order Listund enthält ein HTML-Dokument, das die Arbeitsaufträge mit weniger DueDate als zwei Tagen 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';

Zugehöriger Inhalt