Поделиться через

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

  • Статья

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

Аргументы

  • [ @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'
    Значение параметра «адрес отправителя» сообщения электронной почты. Это необязательный параметр, используемый для переопределения параметров в профиле электронной почты. Этот аргумент имеет тип varchar(MAX). Параметры безопасности SMTP определяют, будет ли принято переопределение настроек. Если параметр не указан, значение по умолчанию равно NULL.

  • [ @reply_to= ] 'reply_to'
    Значение параметра «обратный адрес» сообщения электронной почты. В качестве допустимого значения принимается только один адрес электронной почты. Это необязательный параметр, используемый для переопределения параметров в профиле электронной почты. Этот аргумент имеет тип varchar(MAX). Настройки безопасности SMTP определяют, будет ли принято переопределение настроек. Если параметр не указан, значение по умолчанию равно NULL.

  • [ @subject= ] 'subject'
    Тема сообщения электронной почты. Аргумент subject имеет тип nvarchar(255). Если тема не указана, то по умолчанию устанавливается «Сообщение SQL Server».

  • [ @body= ] 'body'
    Текст сообщения электронной почты. Аргумент message имеет тип nvarchar(max) и значение по умолчанию NULL.

  • [ @body_format= ] 'body_format'
    Формат текста сообщения. Аргумент имеет тип varchar(20) и значение по умолчанию NULL. Если установлено значение этого аргумента, то устанавливаются заголовки исходящих сообщений, что указывает на формат текста сообщения. Аргумент может содержать одно из следующих значений.

    • TEXT

    • HTML

    По умолчанию имеет значение TEXT.

  • [ @importance= ] 'importance'
    Важность сообщения. Аргумент имеет тип varchar(6). Аргумент может содержать одно из следующих значений.

    • Low

    • Normal

    • High

    По умолчанию имеет значение Normal.

  • [ @sensitivity= ] 'sensitivity'
    Пометка сообщения. Аргумент имеет тип varchar(12). Аргумент может содержать одно из следующих значений.

    • Normal

    • Personal

    • Private

    • Confidential

    По умолчанию имеет значение Normal.

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

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

  • [ @execute_query_database= ] 'execute_query_database'
    Контекст базы данных, в котором хранимая процедура запускает запрос. Аргумент имеет тип sysname и значение по умолчанию NULL. Данный аргумент применим только в том случае, если задан аргумент @query.

  • [ @attach_query_result_as_file= ] attach_query_result_as_file
    Указывает, возвращается ли результирующий набор запроса как прикрепленный файл. Аргумент attach_query_result_as_file имеет тип bit и значение по умолчанию NULL.

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

  • [ @query_attachment_filename= ] query_attachment_filename
    Указывает имя файла для результирующего набора вложения запроса. Аргумент query_attachment_filename имеет тип nvarchar(255) и значение по умолчанию NULL. Параметр не учитывается, если аргумент attach_query_result имеет значение 0. Если аргумент attach_query_result принимает значение 1, а значение данного параметра равно NULL, то компонент Database Mail создает произвольное имя файла..

  • [ @query_result_header= ] query_result_header
    Указывает, включают ли результаты запроса заголовки столбцов. Аргумент query_result_header имеет тип bit. Если значение равно 1, результаты запроса содержат заголовки столбцов. Если установлено значение 0, то результаты запроса не содержат заголовков столбцов. Данный аргумент имеет значение по умолчанию 1. Данный аргумент применим только в том случае, если задан аргумент @query.

  • [ @query_result_width = ] query_result_width
    Толщина линии для использования при форматировании результатов запроса (в символах). Аргумент query_result_width имеет тип int и значение по умолчанию 256. Его значение должно находиться в диапазоне от 10 до 32767. Данный параметр применим только в том случае, если задан аргумент @query.

  • [ @query_result_separator= ] '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 результаты запроса не дополняются пробелами, что может сократить размер файла. При установке параметру @query\_result\_no\_padding значения 1 и задании параметра @query\_result\_width параметр @query\_result\_no\_padding переопределяет параметр @query\_result\_width.

    Ошибки при этом не возникает.

    Если присвоить параметру @query\_result\_no\_padding значение 1 и задать параметр @query\_no\_truncate, возникает ошибка.

  • [ @mailitem_id= ] mailitem_id [ OUTPUT ]
    Необязательный выходной параметр, возвращающий идентификатор сообщения mailitem_id. Аргумент mailitem_id имеет тип int.

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

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

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

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

Замечания

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

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

Примеры

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

В данном примере посылается сообщение электронной почты Дэну Уилсону с использованием адреса danw@Adventure-Works.com. Сообщение имеет тему Automated Success Message. Текст сообщения содержит предложение 'The stored procedure finished successfully'.

EXEC msdb.dbo.sp_send_dbmail
    @profile_name = 'Adventure Works Administrator',
    @recipients = 'danw@Adventure-Works.com',
    @body = 'The stored procedure finished successfully.',
    @subject = 'Automated Success Message' ;

Б.Отправка сообщения электронной почты с результатами запроса

В данном примере посылается сообщение электронной почты Дэну Уилсону с использованием адреса danw@Adventure-Works.com. Сообщение имеет тему Work Order Count и выполняет запрос, который показывает количество заявок на выполнение работ с меньшим DueDate, чем через два дня после 30 апреля 2004 г. Компонент Database Mail прикрепляет результаты в виде текстового файла.

EXEC msdb.dbo.sp_send_dbmail
    @profile_name = 'Adventure Works Administrator',
    @recipients = 'danw@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 ;

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

В этом примере сообщение электронной почты посылается Дэну Уилсону по адресу danw@Adventure-Works.com. Сообщение имеет тему Work Order List и содержит документ HTML, который показывает количество заявок на выполнение работ с меньшим сроком DueDate, чем через два дня после 30 апреля 2004 г. Компонент 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
              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='danw@Adventure-Works.com',
    @subject = 'Work Order List',
    @body = @tableHTML,
    @body_format = 'HTML' ;

См. также

Справочник

Хранимые процедуры Database Mail (Transact-SQL)

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

Основные понятия

Компонент Database Mail

Объекты конфигурации компонента Database Mail