Хранимая процедура sp_send_dbmail (Transact-SQL)

Область применения: SQL Server Управляемый экземпляр SQL Azure

Отправляет сообщение электронной почты указанным получателям. Сообщение может включать результирующий набор запросов, вложения файлов или оба. Когда почта успешно помещается в очередь 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 = ] "получатели"

Список адресов электронной почты с разделителями с запятой для отправки сообщения. Список получателей имеет тип 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 "важность"

Важность сообщения. Параметр имеет тип varchar(6). Параметр может содержать одно из следующих значений:

• Low
• Normal (по умолчанию)
• High

[ = ] @sensitivity 'конфиденциальность'

Конфиденциальность сообщения. Параметр имеет тип varchar(12). Параметр может содержать одно из следующих значений:

• Normal (по умолчанию)
• Personal
• Private
• Confidential

[ @file_attachments = ] N'file_attachments'

Список имен файлов, разделенных точкой с запятой, для присоединения к сообщению электронной почты. Файлы в списке должны указываться как абсолютные пути. Список вложений имеет тип nvarchar(max). По умолчанию компонент Database Mail ограничивает размер файлов вложений до 1 МБ на файл.

Внимание

Этот параметр недоступен в Управляемый экземпляр SQL Azure, так как он не может получить доступ к локальной файловой системе.

[ @query = ] N'query'

Выполнение запроса. Результаты запроса могут прикрепляться в виде файла или включаться в текст сообщения электронной почты. Запрос имеет тип nvarchar(max) и может содержать любые допустимые инструкции Transact-SQL. Запрос выполняется в отдельном сеансе, поэтому локальные переменные в вызове sp_send_dbmail скрипта недоступны для запроса.

При использовании параметра @query субъект, который выполняетсяsp_send_dbmail, должен быть подключен как отдельный, а не как часть группы, будь то идентификатор Microsoft Entra (ранее Azure Active Directory) или группа Windows Active Directory. Имена входа SQL Server, удостоверения Windows и удостоверения Microsoft Entra могут выполнять запрос, но члены группы не могут, из-за Управляемый экземпляр SQL Azure олицетворения и ограничений 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 имеет тип бита с значением по умолчанию0.

Если значение равно 0, результаты запроса включаются в текст сообщения электронной почты после содержимого параметра @body . Если значение равно 1, результаты возвращаются в виде вложения. Этот параметр применим только при указании @query .

[ @query_attachment_filename = ] N'query_attachment_filename'

Указывает имя файла для результирующего набора вложения запроса. @query_attachment_filename имеет тип nvarchar(255) с значением по умолчаниюNULL. Этот параметр игнорируется при @attach_query_result_as_file0. Если @attach_query_result_as_file и этот параметр имеет значение 1 NULL, Database Mail создает произвольное имя файла.

[ @query_result_header = ] query_result_header

Указывает, включают ли результаты запроса заголовки столбцов. Значение query_result_header имеет бит типа. Если значение равно 1, результаты запроса содержат заголовки столбцов. Если значение равно 0, результаты запроса не включают заголовки столбцов. Этот параметр по умолчанию используется 1. Этот параметр применим только при указании @query .

При настройке @query_result_header и настройке @query_no_truncate 0 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. Указанное значение должно быть между 10 и 32767. Этот параметр применим только при указании @query .

[ @query_result_separator = ] 'query_result_separator'

Символ, используемый для разделения столбцов в выходных данных запроса. Разделитель имеет тип char(1). По умолчанию используется ' ' значение (пробел).

[ @exclude_query_output = ] exclude_query_output

Указывает, должен ли результат выполнения запроса возвращаться в сообщении электронной почты. @exclude_query_output бит с значением по умолчанию0. Если этот параметр имеет значение 0, выполнение sp_send_dbmail хранимой процедуры выводит сообщение, возвращаемое в результате выполнения запроса на консоли. Если этот параметр задан 1, выполнение хранимой процедуры не выводит ни одного из сообщений о выполнении sp_send_dbmail запроса на консоли.

[ @append_query_error = ] append_query_error

Указывает, следует ли отправлять сообщение электронной почты, когда ошибка возвращается из запроса, указанного в аргументе @query . @append_query_error бит с значением по умолчанию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 имеет бит типа. Если значение не 0 указано, столбцы в запросе усечены до 256 символов. Если значение равно 1, столбцы в запросе не усечены. Этот параметр по умолчанию используется 0.

Примечание.

При использовании с большими объемами данных параметр @query_no_truncate потребляет дополнительные ресурсы и может снизить производительность сервера.

[ @query_result_no_padding = ] query_result_no_padding

Тип имеет бит. Значение по умолчанию — 0. Если задано 1значение, результаты запроса не заполняются, возможно, уменьшая размер файла. Если задан @query_result_no_padding 1 параметр @query_result_width, параметр @query_result_no_padding перезаписывает параметр @query_result_width.

В этом случае ошибка не возникает.

При настройке @query_result_no_padding и предоставлении параметра для @query_no_truncate 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.

Если @query_result_no_padding задан и задан параметр @query_no_truncate1, возникает ошибка.

[ @mailitem_id = ] mailitem_id [ ВЫХОДНЫЕ ДАННЫЕ ]

Необязательный выходной mailitem_id параметр возвращает сообщение. @mailitem_id имеет тип int.

Значения кода возврата

Код возврата 0 означает успешность. Любое другое значение означает неуспешное завершение. Код ошибки для инструкции, которая завершилась сбоем, хранится в переменной @@ERROR .

Результирующий набор

В случае успешного выполнения возвращает сообщение «Письмо поставлено в очередь».

Замечания

Перед использованием компонент Database Mail необходимо включить с помощью мастера настройки компонента Database Mail или sp_configure.

sysmail_stop_sp останавливает Компонент Database Mail, остановив объекты Service Broker, которые использует внешняя программа. sp_send_dbmail по-прежнему принимает почту при остановке использования sysmail_stop_spкомпонента Database 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 предоставлять учетные данные с удаленного компьютера на другой удаленный компьютер. Таким образом, Компонент Database Mail может не в состоянии вложить файлы из сетевой папки в тех случаях, когда команда выполняется с компьютера, отличного от компьютера, на котором выполняется SQL Server.

Если указаны оба @query и @file_attachments, и файл не найден, запрос по-прежнему выполняется, но электронная почта не отправляется.

Если указывается запрос, то результирующий набор форматируется как встроенный текст. В результате двоичные данные посылаются в шестнадцатеричном формате.

Параметры @recipients, @copy_recipients и @blind_copy_recipients — это списки адресов электронной почты с запятой. Необходимо указать хотя бы один из этих параметров или sp_send_dbmail возвратить ошибку.

При выполнении sp_send_dbmail без контекста транзакции компонент Database Mail запускает и фиксирует неявную транзакцию. При выполнении sp_send_dbmail из существующей транзакции компонент Database Mail зависит от пользователя от фиксации или отката любых изменений. Он не запускает внутреннюю транзакцию.

Разрешения

Выполнение разрешений для sp_send_dbmail всех членов роли базы данных DatabaseMailUser в msdb базе данных по умолчанию. Однако если пользователь, отправляющий сообщение, не имеет разрешения на использование профиля запроса, sp_send_dbmail возвращает ошибку и не отправляет сообщение.

Примеры

А. Отправка сообщения электронной почты

В этом примере отправляется сообщение электронной почты другому с помощью адреса 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и выполняет запрос, показывающий количество рабочих заказов менее DueDate чем за два дня после 30 апреля 2022 года. Компонент 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 чем через два дня после 30 апреля 2022 года. Компонент 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';

Связанный контент

• Database Mail
• Объекты конфигурации компонента Database Mail
• Хранимые процедуры Database Mail (Transact-SQL)
• Хранимая процедура Хранимая процедура sp_addrolemember (Transact-SQL)