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

  • Статья

Изменения: 5 декабря 2005 г.

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

    ms190307.note(ru-ru,SQL.90).gifПримечание.
    При использовании с большими объемами данных аргумент @query_no_truncate занимает дополнительные ресурсы и может понизить производительность сервера.

  • [ @query_result_no_padding= ] query_result_no_padding ]
    Имеет тип bit. Значение по умолчанию равно 0. Если присвоить значение 1, результаты запроса не заполняются, возможно, уменьшая тем самым размер файла.

    Если @query\_result\_no\_padding присвоить значение 1 и установить параметр @query\_result\_width parameter, параметр @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 (успешное завершение) или 1 (неуспешное завершение)

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

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

Замечания

Перед использованием компонент Database Mail должен быть включен с помощью мастера настройки компонента Database Mail, средства настройки контактной зоны SQL Server или процедуры 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 = 'AdventureWorks 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 = 'AdventureWorks Administrator',
    @recipients = 'danw@Adventure-Works.com',
    @query = 'SELECT COUNT(*) FROM AdventureWorks.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 и SQL Mail (Transact-SQL)
Хранимая процедура sp_addrolemember (Transact-SQL)

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

Компонент Database Mail
Профили Database Mail
Мастер настройки компонента Database Mail
Настройка контактной зоны SQL Server

Справка и поддержка

Получение помощи по SQL Server 2005

Журнал изменений

Версия Журнал

5 декабря 2005 г.
Добавления
  • Описано поведение транзакции в процедуре sp_send_dbmail.