Хранимая процедура 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'
  Тема сообщения электронной почты. Тема имеет тип 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 МБ на файл. Дополнительные сведения см. в разделе Мастер настройки компонента Database Mail.

• [ @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 и значение по умолчанию 0.

  Если установлено значение 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. Если данный аргумент принимает значение 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 означает успешное завершение. Любое другое значение означает неуспешное завершение. Код ошибки для инструкции, выполнение которой завершилось неуспешно, хранится в переменной @@ERROR.

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

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

Замечания

Перед использованием компонент 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 = 'AdventureWorks2008R2 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 = 'AdventureWorks2008R2 Administrator',
    @recipients = 'danw@Adventure-Works.com',
    @query = 'SELECT COUNT(*) FROM AdventureWorks2008R2.Production.WorkOrder
                  WHERE DueDate > ''2006-04-30''
                  AND  DATEDIFF(dd, ''2006-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 AdventureWorks2008R2.Production.WorkOrder as wo
              JOIN AdventureWorks2008R2.Production.Product AS p
              ON wo.ProductID = p.ProductID
              WHERE DueDate > '2006-04-30'
                AND DATEDIFF(dd, '2006-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 и SQL Mail (Transact-SQL)

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

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

Компонент Database Mail

Профили Database Mail

Другие ресурсы

Мастер настройки компонента Database Mail