Articolo
03/31/2012

xp_sendmail (Transact-SQL)

Invia ai destinatari specificati un messaggio di posta elettronica, che può includere un allegato con il set di risultati della query. Questa stored procedure estesa utilizza SQL Mail per l'invio del messaggio.

Nota

Questa caratteristica verrà rimossa a partire da una delle prossime versioni di Microsoft SQL Server. Evitare di utilizzare questa caratteristica in un nuovo progetto di sviluppo e prevedere interventi di modifica nelle applicazioni in cui è attualmente implementata. Per inviare posta elettronica da SQL Server, utilizzare Posta elettronica database.

Icona di collegamento a un argomento Convenzioni della sintassi Transact-SQL

Sintassi

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' ]

Argomenti

[ @recipients=] **'**recipients [ ;... n] '
Elenco separato da punto e virgola dei destinatari del messaggio di posta elettronica.
[ @message=] 'message'
Corpo del messaggio da inviare. message non può essere superiore a 8.000 byte.
[ @query=] 'query'
Query di SQL Server valida il cui risultato viene inviato per posta elettronica. xp_sendmail utilizza una connessione associata per il parametro query. La connessione query stabilita da SQL Mail non viene bloccata da blocchi attivati dal client che invia la richiesta xp_sendmail. Di conseguenza xp_sendmail è più semplice da utilizzare dall'interno di trigger. L'istruzione query, tuttavia, non può fare riferimento alle tabelle logiche inserted e deleted, poiché sono disponibili solo all'interno di un trigger. querynon può essere superiore a 8.000 byte.
[ @attachments=] **'**attachments [ ;... n] '
Elenco dei file, separati da punto e virgola, da allegare al messaggio di posta elettronica. Se si utilizza il parametro @query con @attach_results impostato su TRUE, il parametro @attachments può specificare un solo file da allegare al messaggio di posta elettronica. In questo caso, per inviare più di un file è necessario eseguire xp_sendmail separatamente per ogni file allegato.
[ @copy_recipients=] **'**copy_recipients [ ;... n] '
Elenco separato da punto e virgola che identifica i destinatari di una copia del messaggio.
[ @blind_copy_recipients=] **'**blind_copy_recipients[ ;... n] '
Elenco facoltativo separato da punto e virgola che identifica i destinatari di una copia nascosta del messaggio.
[ @subject=] 'subject'
Parametro che specifica l'oggetto del messaggio. Se subjectviene omesso, il valore predefinito è "Messaggio SQL Server".
[ @type = ] 'type'
Tipo del messaggio di input in base alla definizione di posta elettronica MAPI:

IP[ M|C ].Vendorname.subclass

Se type è NULL, xp_sendmail utilizza un tipo di messaggio IPM. I tipi di messaggio che iniziano con IPM vengono visualizzati nella cartella Posta in arrivo del client di posta elettronica e vengono recuperati o letti da xp_findnextmsg. I tipi di messaggio che iniziano con IPC non vengono visualizzati nella cartella Posta in arrivo del client di posta elettronica e vengono recuperati o letti impostando il parametro type. Il valore predefinito è NULL. SQL Mail supporta i tipi di messaggio IPM e IPC.
[ @attach_results=] 'attach_value'
Parametro facoltativo che specifica che il set di risultati di una query deve essere inviato per posta elettronica come file allegato anziché essere inserito nel messaggio. Se @attachments è diverso da NULL e @attach_results è TRUE, il nome file assegnato ai risultati corrisponde al primo nome file in attachments. Se @attachments è NULL, viene generato un nome file con estensione txt. Il valore predefinito è FALSE, che significa che il set di risultati viene aggiunto nel messaggio.
[ @no_output=] 'output_value'
Parametro facoltativo che invia il messaggio senza restituire alcun output alla sessione client che ha inviato il messaggio. Il valore predefinito è FALSE, che significa che la sessione client di SQL Server riceve l'output.
[ @no_header=] 'header_value'
Parametro facoltativo che invia i risultati della query nel messaggio senza le informazioni delle intestazioni di colonna. Il valore predefinito è FALSE, che significa che le informazioni delle intestazioni di colonna vengono inviate insieme ai risultati della query.
[ @width=] width
Parametro facoltativo che imposta la lunghezza delle righe del testo di output per una query. Questo parametro è identico al parametro /w nell'utilità isql. Per le query che generano righe di output lunghe, utilizzare width con attach_results per inviare l'output senza interruzioni di riga in mezzo alle righe di output. La lunghezza predefinita è di 80 caratteri.
[ @separator=] 'separator'
Stringa di separazione tra le colonne del set di risultati. Per impostazione predefinita è uno spazio. L'utilizzo di un separatore di colonna semplifica l'analisi del set di risultati in fogli di calcolo e altre applicazioni. Utilizzare ad esempio separator con attach_results per inviare file con valori delimitati da virgole.
[ @echo_error=] 'echo_value'
Se TRUE, SQL Mail acquisisce tutti i messaggi del server o gli errori di DB-Library rilevati durante l'esecuzione della query e li aggiunge al messaggio di posta elettronica anziché scriverli nel log degli errori. Al messaggio viene inoltre aggiunto il numero delle righe restituite o delle righe interessate.

Nota

Se echo_error è TRUE, xp_sendmail restituisce il valore di stato 0 (operazione riuscita) se il messaggio è stato inviato correttamente, anche in presenza di errori o messaggi di DB-Library o se la query non restituisce alcun risultato.
[ @set_user=] 'user'
Contesto di protezione in cui deve essere eseguita la query. Se user viene omesso, viene utilizzato per impostazione predefinita il contesto di protezione dell'utente che esegue xp_sendmail.
[ @dbuse=] 'database'
Contesto del database in cui deve essere eseguita la query. Il valore predefinito è NULL, che significa che l'utente viene inserito nel database predefinito.

Valori restituiti

0 (esito positivo) o 1 (esito negativo)

Set di risultati

Se l'esito è positivo, xp_sendmail restituisce un messaggio.

Osservazioni

Prima di eseguire xp_sendmail è necessario avviare la sessione di SQL Mail. Le sessioni possono essere avviate automaticamente o tramite xp_startmail. Per ulteriori informazioni sull'impostazione dell'avvio automatico di una sessione di SQL Mail, vedere Configurazione dei profili di posta MAPI estesa. Una sessione di SQL Mail supporta tutti gli utenti per l'istanza di SQL Server, ma solo un utente alla volta può inviare un messaggio. Gli altri utenti che inviano messaggi di posta elettronica devono attendere che il messaggio del primo utente venga inviato.

Se si specifica query, xp_sendmail accede a SQL Server come client ed esegue la query specificata. SQL Mail stabilisce una connessione distinta a SQL Server e non condivide la connessione originale del client che esegue xp_sendmail.

Nota

È possibile bloccare query tramite un blocco mantenuto attivo dalla connessione client che ha eseguito xp_sendmail. Se ad esempio si aggiorna una tabella in una transazione e si crea un trigger per l'aggiornamento che tenta di selezionare le stesse informazioni di riga aggiornate del parametro query, la connessione di SQL Mail viene bloccata dal blocco esclusivo attivato sulla riga dalla connessione client iniziale.

xp_sendmail viene eseguita nel contesto di protezione di SQL Server. Un utente valido di xp_sendmail può accedere ai file per allegarli a un messaggio di posta elettronica nel contesto di protezione di un amministratore. Se un utente diverso dall'amministratore di sistema deve accedere a xp_sendmail e si desidera garantire la protezione da accessi non protetti agli allegati, l'amministratore di sistema può creare una stored procedure che chiama xp_sendmail e offre le funzionalità necessarie senza esporre il parametro attachments. Tale stored procedure deve essere definita nel database master. A questo punto, l'amministratore di sistema concede l'autorizzazione di esecuzione per la stored procedure agli utenti desiderati senza concedere l'autorizzazione per la stored procedure xp_sendmail sottostante.

xp_sendmail invia un messaggio e il set di risultati di una query o un allegato ai destinatari specificati, utilizzando una connessione associata per il parametro query. La connessione query stabilita da SQL Mail non viene bloccata da blocchi attivati dal client che invia la richiesta xp_sendmail. Di conseguenza xp_sendmail è più semplice da utilizzare dall'interno di trigger. L'istruzione query, tuttavia, non può fare riferimento alle tabelle logiche inserted e deleted, disponibili solo all'interno di un trigger.

Nota

Quando la centrale e la rubrica si trovano in una condivisione file per cui il servizio MSSQLServer non dispone delle autorizzazioni di accesso necessarie, è possibile che si verifichi una violazione di accesso in seguito al tentativo di esecuzione di xp_sendmail.

xp_sendmail non supporta completamente il tipo di dati xml. È possibile che il formato delle query che utilizzano il tipo di dati xml non sia corretto. Utilizzare Posta elettronica database per inviare posta elettronica con dati xml.

Autorizzazioni

È richiesta l'appartenenza al ruolo predefinito del server sysadmin, ma è possibile concedere autorizzazioni EXECUTE ad altri utenti. Per motivi di protezione, è tuttavia consigliabile concedere le autorizzazioni per l'esecuzione di questa stored procedure solo ai membri del ruolo predefinito del server sysadmin.

Esempi

A. Invio di un messaggio a un solo destinatario

Nell'esempio seguente viene inviato un messaggio all'utente Dan Wilson (il cui account di posta elettronica è danw) per segnalare che il database master è pieno.

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

B. Invio di un messaggio a più destinatari

Nell'esempio seguente il messaggio viene inviato agli utenti Dan Wilson e Ashvini Sharma (il cui account di posta elettronica è ashvinis) e in copia a Peter Connelly (il cui account di posta elettronica è peterc). Viene inoltre specificato l'oggetto del messaggio.

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

C. Invio di risultati

Nell'esempio seguente vengono inviati i risultati della stored procedure sp_configure a Dan Wilson.

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

D. Invio di risultati come file allegato

Nell'esempio seguente all'utente Dan Wilson vengono inviati i risultati della query SELECT * FROM INFORMATION_SCHEMA.TABLES come file di testo allegato. Vengono inclusi l'oggetto del messaggio e un messaggio da visualizzare prima dell'allegato. Per evitare interruzioni di riga nell'output viene utilizzato il parametro @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 ;

E. Invio di messaggi che includono più di 7.990 byte

Nell'esempio seguente viene illustrato come inviare un messaggio che include più di 7.990 byte. Poiché la lunghezza massima di message non può superare la lunghezza di un valore VARCHAR (meno l'overhead di riga, come per tutti i parametri di stored procedure), nell'esempio il messaggio lungo viene scritto in una tabella temporanea globale costituita da una sola colonna di testo. Il contenuto di tale tabella temporanea viene quindi inviato tramite posta elettronica utilizzando il parametro @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 ;