xp_sendmail (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.

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.

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

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

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

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

D. Invio di risultati come file allegato

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

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 ;

Vedere anche

Riferimento