sp_send_dbmail (Transact-SQL)

發行項
08/21/2024

將電子郵件訊息傳送給指定的收件者。訊息可能包含查詢結果集、檔案附件或兩者。成功將郵件放置在 Database Mail 佇列中時， sp_send_dbmail 會 mailitem_id 傳回訊息的。這個預存程式位於 msdb 資料庫中。

Transact-SQL 語法慣例

語法

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

引數

[ @profile_name = ] 'profile_name'

要從中傳送訊息的配置檔名稱。 @profile_name的類型為 sysname，預設值為 NULL。 @profile_name必須是現有 Database Mail 設定檔的名稱。未 指定任何@profile_name 時， sp_send_dbmail 請使用目前用戶的預設私人配置檔。如果使用者沒有預設的私人配置檔， sp_send_dbmail 請使用資料庫的預設公用配置檔 msdb 。如果使用者沒有預設的私人配置檔，而且資料庫沒有預設的公用配置檔， 則必須指定@profile_name 。

[ @recipients = ] 'recipients'

要傳送郵件的電子郵件地址清單以分號分隔。收件者清單的類型 為 varchar（max）。雖然這個參數是選擇性的，但至少必須指定一個 @recipients、 @copy_recipients或 @blind_copy_recipients ，或 sp_send_dbmail 傳回錯誤。

[ @copy_recipients = ] 'copy_recipients'

要複製郵件的電子郵件位址以分號分隔的清單。複製收件者清單的類型 為 varchar（max）。雖然這個參數是選擇性的，但至少必須指定一個 @recipients、 @copy_recipients或 @blind_copy_recipients ，或 sp_send_dbmail 傳回錯誤。

[ @blind_copy_recipients = ] 'blind_copy_recipients'

以分號分隔的電子郵件地址清單，以盲目複製郵件。盲目複製收件者清單的類型 為 varchar（max）。雖然這個參數是選擇性的，但至少必須指定一個 @recipients、 @copy_recipients或 @blind_copy_recipients ，或 sp_send_dbmail 傳回錯誤。

[ @from_address = ] 'from_address'

電子郵件訊息的 'from address' 值。這是選擇性參數，用來覆寫郵件配置檔中的設定。此參數的類型為 varchar（max）。 SMTP 安全性設定會判斷是否接受這些覆寫。如果未指定任何參數，則預設值為 NULL。

[ @reply_to = ] 'reply_to'

電子郵件訊息的「回復位址」值。它只接受一個電子郵件地址作為有效值。這是選擇性參數，用來覆寫郵件配置檔中的設定。此參數的類型為 varchar（max）。 SMTP 安全性設定會判斷是否接受這些覆寫。如果未指定任何參數，則預設值為 NULL。

[ @subject = ] N'subject'

電子郵件訊息的主旨。主旨的類型為 nvarchar（255）。 如果未指定主旨，則預設值為「SQL Server 訊息」。

[ @body = ] N'body'

電子郵件訊息的本文。訊息本文的類型 為 nvarchar（max），預設值為 NULL。

[ @body_format = ] 'body_format'

訊息本文的格式。參數的類型為 varchar（20），預設值為 NULL。指定時，傳出訊息的標頭會設定為表示訊息本文具有指定的格式。參數可能包含下列其中一個值：

TEXT （預設值）
HTML

[ @importance = ] 'importance'

訊息的重要性。參數的類型為 varchar（6）。參數可能包含下列其中一個值：

Low
Normal (預設值)
High

[ @sensitivity = ] 'sensitivity'

訊息的敏感度。參數的類型為 varchar（12）。 參數可能包含下列其中一個值：

Normal (預設值)
Personal
Private
Confidential

[ @file_attachments = ] N'file_attachments'

要附加至電子郵件訊息之檔名的分號分隔清單。清單中的檔案必須指定為絕對路徑。附件清單的類型 為 nvarchar（max）。根據預設，Database Mail 會將檔案附件限製為每個檔案 1 MB。

重要

此參數無法在 Azure SQL 受控執行個體中使用，因為它無法存取本機文件系統。

[ @query = ] N'query'

要執行的查詢。查詢的結果可以附加為檔案，或包含在電子郵件訊息的本文中。此查詢的類型 為 nvarchar（max），而且可以包含任何有效的 Transact-SQL 語句。查詢會在個別會話中執行，因此呼叫的腳本 sp_send_dbmail 中的局部變數無法供查詢使用。

當您使用 @query 參數時，執行的 sp_send_dbmail 主體必須以個人身分連線，而不是作為群組的一部分，無論是Microsoft Entra ID（先前稱為 Azure Active Directory）還是 Windows Active Directory 群組。 SQL Server 登入、Windows 身分識別和Microsoft Entra 身分識別可以執行查詢，但群組成員因為 Azure SQL 受控執行個體模擬和 EXECUTE AS 限制而無法執行。

[ @execute_query_database = ] 'execute_query_database'

預存程式在其中執行查詢的資料庫內容。參數的類型 為 sysname，預設為目前資料庫。只有在指定@query時，此參數才適用。

[ @attach_query_result_as_file = ] attach_query_result_as_file

指定查詢的結果集是否以附加檔案的形式傳回。 @attach_query_result_as_file的類型為 bit，預設值為 0。

當值為 0時，查詢結果會包含在電子郵件訊息本文中，在 @body 參數的內容之後。當值為 1時，結果會以附件的形式傳回。只有在指定@query時，此參數才適用。

[ @query_attachment_filename = ] N'query_attachment_filename'

指定要用於查詢附件結果集的檔名。 @query_attachment_filename 類型為 nvarchar（255），預設值為 NULL。當 @attach_query_result_as_file 為 0時，會忽略此參數。當@attach_query_result_as_file 為 1 且此參數為 NULL時，Database Mail 會建立任意檔名。

[ @query_result_header = ] query_result_header

指定查詢結果是否包含資料行標頭。 query_result_header值的類型為 bit。當值為 1時，查詢結果會包含數據行標頭。當值為 0時，查詢結果不會包含數據行標頭。此參數預設為 1。只有在指定@query時，此參數才適用。

將 @query_result_header 設定為 0 ，並將 @query_no_truncate 1設定為時，可能會發生下列錯誤：

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

[ @query_result_width = ] query_result_width

要用來格式化查詢結果的行寬，以字元為單位。 @query_result_width的類型為 int，預設值為 256。所提供的值必須介於和 32767之間10。只有在指定@query時，此參數才適用。

[ @query_result_separator = ] 'query_result_separator'

用來分隔查詢輸出中數據行的字元。分隔符的類型 為 char（1）。預設為 ' ' （空格）。

[ @exclude_query_output = ] exclude_query_output

指定是否要在電子郵件訊息中傳回查詢執行的輸出。 @exclude_query_output為 bit，預設值為 0。當此參數為 0時，預存程式的執行 sp_send_dbmail 會列印在控制台上執行查詢的結果所傳回的訊息。當此參數為 1時，預存程式的執行 sp_send_dbmail 不會列印控制臺上的任何查詢執行訊息。

[ @append_query_error = ] append_query_error

指定當錯誤從 @query 自變數中指定的查詢傳回時，是否要傳送電子郵件。 @append_query_error為 bit，預設值為 0。當此參數為 1時，Database Mail 會傳送電子郵件訊息，並在電子郵件訊息本文中包含查詢錯誤訊息。當此參數為 0時，Database Mail 不會傳送電子郵件訊息，並以 sp_send_dbmail 傳回碼 1結尾，表示失敗。

[ @query_no_truncate = ] query_no_truncate

指定是否要使用選項來執行查詢，以避免截斷大型可變長度數據類型（varchar（max）、nvarchar（max）、varbinary（max）、xml、text、ntext、image 和使用者定義數據類型。設定時，查詢結果不會包含數據行標頭。 @query_no_truncate值的類型為 bit。當值未 0 指定時，查詢中的數據行會截斷為 256 個字元。當值為 1時，不會截斷查詢中的數據行。此參數預設為 0。

注意

搭配大量數據使用時， @query_no_truncate 選項會耗用額外的資源，而且可能會降低伺服器效能。

[ @query_result_no_padding = ] query_result_no_padding

此類型為 bit。預設值為 0。當您將設定為 1時，查詢結果不會填補，可能會減少檔案大小。如果您將設定為 1 並設定 @query_result_no_padding @query_result_width 參數，@query_result_no_padding參數會覆寫 @query_result_width 參數。

在此情況下，不會發生任何錯誤。

將 @query_result_no_padding 設定為 1 並提供 @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.

如果您將@query_result_no_padding設定為 1 ，而且您已設定 @query_no_truncate 參數，則會引發錯誤。

[ @mailitem_id = ] mailitem_id [ OUTPUT ]

選擇性輸出參數會傳 mailitem_id 回訊息的。 @mailitem_id的類型為 int。

傳回碼值

傳回碼表示 0 成功。任何其他值都表示失敗。失敗之語句的錯誤碼會儲存在變數中 @@ERROR 。

結果集

成功時，會傳回訊息「郵件已排入佇列」。

備註

使用之前，必須使用 Database Mail 組態精靈或 sp_configure啟用 Database Mail。

sysmail_stop_sp 停止外部程式所使用的 Service Broker 物件，藉以停止 Database Mail。 sp_send_dbmail 使用停止 sysmail_stop_spDatabase Mail 時仍接受郵件。若要啟動 Database Mail 請使用 sysmail_start_sp。

未指定@profile時，sp_send_dbmail請使用預設配置檔。如果傳送電子郵件訊息的使用者具有預設的私人配置檔，Database Mail 會使用該配置檔。如果使用者沒有預設的私人配置檔， sp_send_dbmail 請使用預設的公用配置檔。如果使用者沒有預設的私人配置檔，也沒有預設的公用配置檔， sp_send_dbmail 則傳回錯誤。

sp_send_dbmail 不支援沒有內容的電子郵件訊息。若要傳送電子郵件訊息，您必須至少指定其中一個@body、@query、@file_attachments或@subject。否則， sp_send_dbmail 會傳回錯誤。

Database Mail 使用目前使用者的 Windows 安全性內容來控制檔案的存取。因此，使用 SQL Server 驗證進行驗證的使用者無法使用 @file_attachments 附加檔案。 Windows 不允許 SQL Server 提供從遠端電腦到另一部遠端電腦的認證。因此，如果從 SQL Server 執行所在電腦以外的電腦執行命令，Database Mail 可能無法從網路共用附加檔案。

如果同時 指定@query 和 @file_attachments ，而且找不到檔案，仍會執行查詢，但不會傳送電子郵件。

指定查詢時，結果集會格式化為內嵌文字。結果中的二進位數據會以十六進位格式傳送。

參數 @recipients、 @copy_recipients和 @blind_copy_recipients 都是以分號分隔的電子郵件地址清單。至少必須提供其中一個參數，或 sp_send_dbmail 傳回錯誤。

在沒有交易內容的情況下執行 sp_send_dbmail 時，Database Mail 會啟動並認可隱含交易。從現有交易內執行 sp_send_dbmail 時，Database Mail 會依賴使用者認可或回復任何變更。它不會啟動內部交易。

權限

針對資料庫中 DatabaseMailUser 資料庫角色msdb的所有成員執行預設許可權sp_send_dbmail。 不過，當傳送訊息的使用者沒有許可權使用要求的配置檔時， sp_send_dbmail 會傳回錯誤，而且不會傳送訊息。

範例

A. 傳送電子郵件訊息

此範例會使用電子郵件位址 myfriend@adventure-works.com，將電子郵件訊息傳送給您的朋友。訊息的主旨 Automated Success Message為。訊息的本文包含句子 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. 傳送含有查詢結果的電子郵件訊息

此範例會使用電子郵件位址 yourfriend@adventure-works.com，將電子郵件訊息傳送給您的朋友。訊息具有主旨 Work Order Count，並執行查詢，此查詢會顯示在 2022 年 4 月 30 日之後不到兩天的工作訂單 DueDate 數目。 Database Mail 會將結果附加為文本檔。

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. 傳送 HTML 電子郵件訊息

此範例會使用電子郵件位址 yourfriend@adventure-works.com，將電子郵件訊息傳送給您的朋友。郵件的主旨 Work Order List為，並包含 HTML 檔，其中顯示工作訂單 DueDate 在 2022 年 4 月 30 日之後不到兩天。 Database Mail 會以 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';

共用方式為

sp_send_dbmail (Transact-SQL)

語法

引數

[ @profile_name = ] 'profile_name'

[ @recipients = ] 'recipients'

[ @copy_recipients = ] 'copy_recipients'

[ @blind_copy_recipients = ] 'blind_copy_recipients'

[ @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'file_attachments'

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

傳回碼值

結果集

備註

權限

範例

A. 傳送電子郵件訊息

B. 傳送含有查詢結果的電子郵件訊息

C. 傳送 HTML 電子郵件訊息

意見反應

其他資源

共用方式為

sp_send_dbmail (Transact-SQL)

語法

引數

[ @profile_name = ] 'profile_name'

[ @recipients = ] 'recipients'

[ @copy_recipients = ] 'copy_recipients'

[ @blind_copy_recipients = ] 'blind_copy_recipients'

[ @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'file_attachments'

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

傳回碼值

結果集

備註

權限

範例

A. 傳送電子郵件訊息

B. 傳送含有查詢結果的電子郵件訊息

C. 傳送 HTML 電子郵件訊息

相關內容

意見反應

其他資源