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, gibt sp_send_dbmail den mailitem_id der Nachricht zurück. Diese gespeicherte Prozedur wird in der msdb -Datenbank gespeichert.

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 = ] 'subject' ]   
    [ , [ @body = ] 'body' ]   
    [ , [ @body_format = ] 'body_format' ]  
    [ , [ @importance = ] 'importance' ]  
    [ , [ @sensitivity = ] 'sensitivity' ]  
    [ , [ @file_attachments = ] 'attachment [ ; ...n ]' ]  
    [ , [ @query = ] 'query' ]  
    [ , [ @execute_query_database = ] 'execute_query_database' ]  
    [ , [ @attach_query_result_as_file = ] attach_query_result_as_file ]  
    [ , [ @query_attachment_filename = ] 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 kein profile_name angegeben ist, verwendet sp_send_dbmail das private Standardprofil für den aktuellen Benutzer. Wenn der Benutzer nicht über ein privates Standardprofil verfügt, verwendet sp_send_dbmail 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' Ist 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 von @recipients, @copy_recipients oder @blind_copy_recipients angegeben werden, oder sp_send_dbmail gibt einen Fehler zurück.

[ @copy_recipients = ] 'copy_recipients' Ist eine durch Semikolon 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 von @recipients, @copy_recipients oder @blind_copy_recipients angegeben werden, oder sp_send_dbmail gibt einen Fehler zurück.

[ @blind_copy_recipients = ] 'blind_copy_recipients' Ist eine durch Semikolon getrennte Liste von E-Mail-Adressen, in die die Nachricht blind kopiert werden soll. Die Liste der Blindkopieempfänger 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 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' Ist der Wert der "Antwort an 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 = ] 'subject' Ist der Betreff der E-Mail-Nachricht. Das Betreff ist vom Typ nvarchar(255). Wenn Sie keinen Betreff angeben, wird standardmäßig 'SQL Server-Nachricht' verwendet.

[ @body = ] 'body' Der Text der E-Mail-Nachricht. Der Nachrichtentext ist vom Typ nvarchar(max) mit dem Standardwert NULL.

[ @body_format = ] 'body_format' Ist 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

• HTML

Der Standardwert ist TEXT.

[ @importance = ] 'importance' Ist die Wichtigkeit der Nachricht. Der Parameter ist vom Typ varchar(6). Der Parameter kann einen der folgenden Werte enthalten:

• Niedrig

• Normal

• High

Der Standardwert ist Normal.

[ @sensitivity = ] 'sensitivity' Ist die Vertraulichkeit der Nachricht. Der Parameter ist vom Typ varchar(12). Der Parameter kann einen der folgenden Werte enthalten:

• Normal

• Persönlich

• Privat

• Vertraulich

Der Standardwert ist Normal.

[ @file_attachments = ] 'file_attachments' Ist 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 = ] 'query' Ist 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. Beachten Sie, dass die Abfrage in einer separaten Sitzung ausgeführt wird, sodass lokale Variablen im Skript, das sp_send_dbmail aufruft, für die Abfrage nicht verfügbar sind.

Hinweis

Wenn Sie parameter verwenden @query , muss der ausgeführte sp_send_dbmail Benutzer sql-Anmeldung sein oder direkt dem Prinzipal (Login) von Azure AD oder AD zugeordnet sein. Wenn der Benutzer Mitglied der Azure AD-Gruppe oder AD-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 der aktuellen Datenbank ist. Dieser Parameter ist nur anwendbar, wenn @query angegeben ist.

[ @attach_query_result_as_file = ] attach_query_result_as_file Gibt an, ob das Resultset der Abfrage als angefügte Datei zurückgegeben wird. attach_query_result_as_file ist vom Typ Bit mit dem Standardwert 0.

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

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

[ @query_result_header = ] query_result_header Gibt an, ob die Abfrageergebnisse Spaltenheader enthalten. Der query_result_header Wert ist vom Typ Bit. Bei einem Wert von 1 enthalten die Abfrageergebnisse Spaltenheader. Bei einem Wert von 0 enthalten die Abfrageergebnisse keine Spaltenheader. Dieser Parameter ist standardmäßig auf 1 festgelegt. Dieser Parameter ist nur anwendbar, wenn @query angegeben ist.

Hinweis

Der folgende Fehler kann auftreten, wenn @query_result_header auf 0 festgelegt und @query_no_truncate auf 1 festgelegt wird:
Msg 22050, Ebene 16, Zustand 1, Zeile 12: Fehler beim Initialisieren der sqlcmd-Bibliothek mit der Fehlernummer -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 mit dem Standardwert 256. Der Wert muss zwischen 10 and 32767 liegen. Dieser Parameter ist nur anwendbar, wenn @query angegeben ist.

[ @query_result_separator = ] 'query_result_separator' Ist das Zeichen, das zum Trennen von 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, wobei der Standardwert 0 ist. Wenn dieser Parameter 0 ist, gibt die 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 1 ist, werden bei der Ausführung der sp_send_dbmail gespeicherten Prozedur keine der Abfrageausführungsmeldungen in der Konsole ausgegeben.

[ @append_query_error = ] append_query_error Gibt an, ob die E-Mail gesendet werden soll, wenn ein Fehler von der im @query-Argument angegebenen Abfrage zurückgegeben wird. append_query_error ist Bit, wobei der Standardwert 0 ist. Ist dieser Parameter auf 1 festgelegt, sendet Datenbank-E-Mail die E-Mail-Nachricht und bezieht die Abfragefehlermeldung in den Text der E-Mail-Nachricht ein. Wenn dieser Parameter 0 ist, sendet Datenbank-E-Mail die E-Mail-Nachricht nicht, und sp_send_dbmail endet mit Rückgabecode 1, 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 fetgelegt, enthalten die Abfrageergebnisse keine Spaltenheader. Der query_no_truncate Wert ist vom Typ Bit. Bei einem Wert von 0 oder wenn kein Wert angegeben ist, werden die Spalten in der Abfrage auf 256 Zeichen abgeschnitten. Bei einem Wert von 1 werden die Spalten in der Abfrage nicht abgeschnitten. Dieser Parameter hat den Standardwert 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. Die Standardeinstellung ist 0. Wenn Sie ihn auf 1 festlegen, werden die Abfrageergebnisse nicht aufgefüllt und die Dateigröße u. U. reduziert. Wenn @query_result_no_padding auf 1 und gleichzeitig den @query_result_width-Parameter festlegen, überschreibt der @query_result_no_padding-Parameter den @query_result_width-Parameter.

In diesem Fall tritt kein Fehler auf.

Hinweis

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, Ebene 16, Zustand 1, Zeile 0: Fehler beim Ausführen der Abfrage, da die Optionen @query_result_no_append und @query_no_truncate sich gegenseitig ausschließen.

Wenn Sie @query_result_no_padding auf 1 festlegen und den @query_no_truncate-Parameter ebenfalls festlegen, wird ein Fehler ausgelöst.

[ @mailitem_id = ] mailitem_id [ OUTPUT ] Optionaler Ausgabeparameter gibt den mailitem_id der Nachricht zurück. Die mailitem_id ist vom Typ int.

Rückgabecodewerte

Ein Rückgabecode von 0 steht für Erfolg. Ein beliebiger anderer Wert steht für Fehler. Der Fehlercode für die fehlerhafte Anweisung wird in der variablen @@ERROR 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_configure aktiviert werden.

sysmail_stop_sp beendet Datenbank-E-Mail, indem die vom externen Programm verwendeten Service Broker-Objekte beendet werden. sp_send_dbmail akzeptiert weiterhin E-Mails, wenn Datenbank-E-Mail nicht mehr sysmail_stop_sp verwendet wird. Starten Sie Datenbank-E-Mail mithilfe von sysmail_start_sp.

Wenn @profile nicht angegeben ist, verwendet sp_send_dbmail ein Standardprofil. 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, verwendet sp_send_dbmail das öffentliche Standardprofil. Wenn kein privates Standardprofil für den Benutzer und kein öffentliches Standardprofil vorhanden ist, gibt sp_send_dbmail einen Fehler zurück.

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 gibt sp_send_dbmail einen Fehler zurück.

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 mit @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 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 werden 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 semikolontrennte Listen von E-Mail-Adressen. Mindestens einer dieser Parameter muss angegeben werden, oder sp_send_dbmail einen Fehler zurückgibt.

Wenn sp_send_dbmail ohne Transaktionskontext ausgeführt wird, startet Datenbank-E-Mail eine implizite Transaktion und committ sie. Beim Ausführen von sp_send_dbmail aus einer vorhandenen Transaktion verlässt sich Datenbank-E-Mail darauf, dass der Benutzer änderungen entweder committ oder rollbackt. Es wird keine innere Transaktion gestartet.

Berechtigungen

Führen Sie Berechtigungen für sp_send_dbmail standardmäßig für 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, gibt sp_send_dbmail 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 eine E-Mail-Nachricht 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 mithilfe der E-Mail-Adresse eine E-Mail-Nachricht yourfriend@Adventure-Works.coman Ihren Freund gesendet. Die Nachricht hat den Betreff Work Order Count und führt eine Abfrage aus, die die Anzahl von Arbeitsaufträgen mit einem DueDate-Wert kleiner als zwei Tage nach dem 30. April 2004 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 > ''2004-04-30''  
                  AND  DATEDIFF(dd, ''2004-04-30'', DueDate) < 2' ,  
    @subject = 'Work Order Count',  
    @attach_query_result_as_file = 1 ;  

C. Senden einer E-Mail-Nachricht im HTML-Format

In diesem Beispiel wird mithilfe der E-Mail-Adresse eine E-Mail-Nachricht yourfriend@Adventure-Works.coman Ihren Freund gesendet. Die Nachricht hat den Betreff Work Order List und enthält ein HTML-Dokument, das die Anzahl von Arbeitsaufträgen mit einem DueDate-Wert kleiner als zwei Tage nach dem 30. April 2004 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  
              JOIN AdventureWorks.Production.Product AS p  
              ON wo.ProductID = p.ProductID  
              WHERE DueDate > '2004-04-30'  
                AND DATEDIFF(dd, '2004-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' ;  

Weitere Informationen

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