xp_sendmail (Transact-SQL)

Отправляет электронные сообщения, которые могут содержать вложение результирующего набора запроса, указанным получателям. Эта расширенная хранимая процедура использует службу SQL Mail для отправки сообщений.

Примечание
В будущей версии Microsoft SQL Server эта возможность будет удалена. Избегайте использования этой возможности в новых разработках и запланируйте изменение существующих приложений, в которых она применяется. Чтобы отправить почту из SQL Server, используйте компонент Компонент Database Mail.

Синтаксические обозначения в Transact-SQL

Синтаксис

xp_sendmail { [ @recipients= ] 'recipients [ ;...n ]' } 
     [ ,[ @message= ] 'message' ] 
     [ ,[ @query= ] 'query' ] 
     [ ,[ @attachments= ] 'attachments [ ;...n ]' ] 
     [ ,[ @copy_recipients= ] 'copy_recipients [ ;...n ]'
     [ ,[ @blind_copy_recipients= ] 'blind_copy_recipients [ ;...n ]'
     [ ,[ @subject= ] 'subject' ]
     [ ,[ @type= ] 'type' ] 
     [ ,[ @attach_results= ] 'attach_value' ]
     [ ,[ @no_output= ] 'output_value' ] 
     [ ,[ @no_header= ] 'header_value' ] 
     [ ,[ @width= ] width ] 
     [ ,[ @separator= ] 'separator' ] 
     [ ,[ @echo_error= ] 'echo_value' ] 
     [ ,[ @set_user= ] 'user' ] 
     [ ,[ @dbuse= ] 'database' ]

Аргументы

• [ @recipients=] **'**recipients [ ;... n] '
  Список получателей письма, разделенных точкой с запятой.

• [ @message=] 'message'
  Тело отправляемого сообщения. Аргумент message может иметь размер до 8 000 байт.

• [ @query=] 'query'
  Правильный запрос SQL Server, результат которого будет отправлен в сообщении. Процедура xp_sendmail использует логическую привязку для аргумента query. Соединение query, созданное службой SQL Mail, не блокируется блокировками клиента, который отправляет запрос к процедуре xp_sendmail. Это облегчает применение процедуры xp_sendmail из триггеров. Аргумент query, однако, не может ссылаться на логические таблицы inserted и deleted, так как эти таблицы доступны только внутри триггера. Инструкция query может иметь размер до 8 000 байт.

• [ @attachments=] **'**attachments [ ;... n] '
  Список разделенных точкой с запятой файлов, которые необходимо прикрепить к почтовому сообщению. При использовании аргумента @query и при аргументе @attach_results, равном TRUE, аргумент @attachments может задать только один файл, который будет прикреплен к почтовому сообщению. В этом случае для отправки нескольких файлов необходимо выполнить процедуру xp_sendmail отдельно для каждого прикрепляемого файла.

• [ @copy_recipients=] **'**copy_recipients [ ;... n] '
  Список получателей копии письма, разделенных точкой с запятой.

• [ @blind_copy_recipients=] **'**blind_copy_recipients[ ;... n] '
  Необязательный список получателей тайной копии письма, разделенных точкой с запятой.

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

• [ @type=] 'type'
  Тип входного сообщения, основанный на определении MAPI почты:

  IP[ M|C ].Vendorname.subclass

  Если аргумент type равен NULL, процедура xp_sendmail использует тип сообщений IPM. Типы сообщений, начинающиеся с IPM, появляются в ящике входящих сообщений почтового клиента и находятся или прочитываются процедурой xp_findnextmsg. Типы сообщений, начинающиеся с IPC, не появляются в ящике входящей почты почтового клиента и должны быть найдены или прочитаны с помощью установки аргумента type. Значение по умолчанию равно NULL. Служба SQL Mail поддерживает типы сообщений IPM и IPC.

• [ @attach_results=] 'attach_value'
  Необязательный параметр, указывающий на то, что результирующий набор запроса должен быть отправлен в качестве прикрепленного файла, вместо того чтобы добавляться к телу письма. Если аргумент @attachments не равен NULL и аргумент @attach_results равен TRUE, то первое имя файла в аргументе attachments используется в качестве имени файла для результатов. Если аргумент @attachments равен NULL, имя файла формируется с расширением TXT. Значение по умолчанию равно FALSE, что означает, что результирующий набор добавляется к телу сообщения.

• [ @no_output=] 'output_value'
  Необязательный параметр, который отправляет почту, но не возвращает выходные данные сеансу клиента, который отправляет почту. Значение по умолчанию равно FALSE, что значит, что сеанс клиента SQL Server получает выходные данные.

• [ @no_header=] 'header_value'
  Необязательный параметр, который отправляет результаты запроса, но не отправляет сведения о заголовке столбца вместе с результатами запроса. Значение по умолчанию равно FALSE, что означает, что сведения о заголовке столбца отправляются вместе с результатами запроса.

• [ @width=] width
  Необязательный параметр, устанавливающий ширину линии выходного текста для запроса. Этот параметр идентичен параметру /w в программе isql. Для запросов, возвращающих длинные выходные строки, используйте аргумент width с аргументом attach_results для отправки выходных данных без разрывов линии в середине выходных линий. Ширина по умолчанию составляет 80 символов.

• [ @separator=] 'separator'
  Строка-разделитель столбцов для каждого столбца в результирующем наборе. По умолчанию разделителем столбцов является пробел. Использование разделителя столбцов позволяет упростить анализ результирующего набора в электронных таблицах и других приложениях. Например, можно использовать аргумент separator с аргументом attach_results для отправки файлов со значениями, разделенными запятой.

• [ @echo_error=] 'echo_value'
  Если равно TRUE, приводит к тому, что служба SQL Mail захватывает любое сообщение сервера или ошибки DB-Library, возникшее во время выполнения запроса, и добавляет их к почтовому сообщению, вместо того чтобы записывать их в журнал ошибок. Также в почтовое сообщение добавляется число возвращенных или задействованных строк.

  Примечание
  Если аргумент echo_error имеет значение TRUE, то процедура xp_sendmail возвращает состояние 0 (успешное завершение), если почта отправлена успешно, даже если возникли ошибки или сообщения DB-Library или запрос не вернул результатов.

• [ @set_user=] 'user'
  Контекст безопасности, в котором должен выполняться запрос. Если аргумент user не указан, контекст безопасности по умолчанию устанавливается равным пользователю, выполняющему процедуру xp_sendmail.

• [ @dbuse=] 'database'
  Контекст базы данных, в котором должен выполняться запрос. По умолчанию равен NULL, что означает, что пользователь помещен в базу данных по умолчанию.

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

0 (успешное завершение) или 1 (неуспешное завершение)

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

При успешном выполнении процедура xp_sendmail возвращает сообщение.

Замечания

Сеанс службы SQL Mail должен быть запущен перед выполнением процедуры xp_sendmail. Сеансы могут быть запущены автоматически или при помощи процедуры xp_startmail. Дополнительные сведения об автоматической настройке сеанса службы SQL Mail см. в разделе Конфигурирование профилей электронной почты Extended MAPI. Один сеанс службы SQL Mail поддерживает всех пользователей для экземпляра SQL Server, но одновременно только один пользователь может отправлять сообщение. Другие пользователи, отправляющие почтовые сообщения, автоматически ждут своей очереди, до тех пор, пока сообщение первого пользователя не будет отправлено.

Если указан аргумент query, процедура xp_sendmail входит в SQL Server в качестве клиента и выполняет указанный запрос. Служба SQL Mail создает отдельное подключение к SQL Server; она не использует то же подключение, что и начальное клиентское подключение, выполняющее процедуру xp_sendmail.

Примечание

Выполнению инструкции query может препятствовать блокировка, удерживаемая клиентским соединением, выполняющим процедуру xp_sendmail. Например, при обновлении таблицы во время транзакции и создании триггера для обновления, который пробует выбрать сведения той же строки, которая обновляется в качестве параметра query, подключение службы SQL Mail будет блокировано монопольной блокировкой строки начальным клиентским подключением.

Процедура xp_sendmail выполняется в контексте безопасности SQL Server. Имеющий права пользователь процедуры xp_sendmail может получить доступ к вложенным в почтовое сообщение файлам в контексте безопасности администратора. Если пользователи, не являющиеся системным администратором, должны получить доступ к xp_sendmail и нужно защититься от несанкционированного доступа к прикрепленным файлам, системный администратор может создать хранимую процедуру, которая вызывает xp_sendmail и предоставляет необходимую функциональность, но которая не распространяет значение параметра attachments. Данная хранимая процедура должна быть определена в базе данных msdb. Потом системный администратор выдает пользователям разрешение на выполнение хранимой процедуры без предоставления разрешения на соответствующую процедуру xp_sendmail.

Процедура xp_sendmail отправляет сообщение и результирующий набор запроса или вложение указанным получателям и использует логическую привязку для параметра query. Соединение query , созданное службой SQL Mail, не блокируется блокировками клиента, который отправляет запрос к процедуре xp_sendmail. Это облегчает применение процедуры xp_sendmail из триггеров. Инструкция query, однако, не может ссылаться на логические таблицы inserted и deleted, которые доступны только внутри триггера.

Примечание
Нарушение доступа может произойти при попытке запустить процедуру xp_sendmail, если почтовая станция и адресная книга находятся в общей папке, к которой учетная запись службы MSSQLServer не может получить доступ из-за отсутствия необходимых разрешений.

Процедура xp_sendmail не полностью поддерживает тип данных xml. Запросы, которые используют тип данных xml, могут быть неверно отформатированы. Используйте компонент Компонент Database Mail для отправки электронных сообщений, которые включают данные xml.

Разрешения

Требует членства в предопределенной роли сервера sysadmin, но разрешения EXECUTE могут предоставляться другим пользователям. Тем не менее в целях безопасности разрешения для этой хранимой процедуры следует ограничить членами предопределенной роли сервера sysadmin.

Примеры

A. Отправка сообщения одному получателю

Этот пример отправляет сообщение пользователю Dan Wilson (адрес электронной почты danw) о том, что база данных master заполнена.

EXEC master.dbo.xp_sendmail 
    @recipients=N'danw@Adventure-Works.com',
    @message=N'The master database is full.' ;

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

Этот пример отправляет сообщение пользователям Dan Wilson и Ashvini Sharma (адрес электронной почты ashvinis) с копией, отправляемой Peter Connelly (адрес электронной почты peterc). В этом примере также указывается тема сообщения.

EXEC master.dbo.xp_sendmail 
    @recipients=N'danw@Adventure-Works.com;ashvinis@Adventure-Works.com',
     @message=N'The master database is full.',
     @copy_recipients=N'peterc@Adventure-Works.com',
     @subject=N'Master database status' ;
GO

В. Отправка результатов

В следующем примере результаты процедуры sp_configure отправляются пользователю Dan Wilson.

EXEC master.dbo.xp_sendmail 
    @recipients=N'danw@Adventure-Works.com',
    @query = N'EXEC sp_configure' ;
GO

Г. Отправка результатов в прикрепленном файле

В этом примере результаты запроса SELECT * FROM INFORMATION_SCHEMA.TABLES отправляются пользователю Dan Wilson в виде вложенного текстового файла. Пример содержит строку темы для письма и сообщение, которое появится перед вложением. Параметр @width используется для предотвращения разрывов выходных линий.

EXEC master.dbo.xp_sendmail
    @recipients = N'danw@Adventure-Works.com', 
    @query = N'SELECT * FROM INFORMATION_SCHEMA.TABLES',
    @subject = N'SQL Server Report',
    @message = N'The contents of INFORMATION_SCHEMA.TABLES:',
    @attach_results = 'TRUE',
    @width = 250 ;

Д. Отправка сообщений длиннее 7 990 байт

Этот пример показывает, как отправить сообщение размером более 7 990 байт. Так как сообщение message ограничено длиной типа данных VARCHAR (как и все параметры хранимых процедур, для снижения потерь строк), этот пример записывает длинное сообщение в глобальную временную таблицу, состоящую из одного текстового столбца. Затем содержимое этой временной таблицы отправляется в сообщении электронной почты с помощью аргумента @query.

CREATE TABLE ##mail_body(c1 NVARCHAR(4000)) ;

DECLARE @cmd VARCHAR(56) ;

INSERT ##mail_body(c1)
VALUES ('Put your long message here.') ;

SET @cmd = 'SELECT c1 FROM ##mail_body' ;

EXEC master.dbo.xp_sendmail 
    @recipients = 'danw@Adventure-Works.com', 
    @query = @cmd,
    @no_header= 'TRUE' ;

DROP TABLE ##mail_body ;

См. также

Справочник

sp_processmail (Transact-SQL)

Системные хранимые процедуры (Transact-SQL)

xp_deletemail (Transact-SQL)

xp_findnextmsg (Transact-SQL)

xp_readmail (Transact-SQL)

xp_startmail (Transact-SQL)

xp_stopmail (Transact-SQL)

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