sp_send_dbmail (Transact-SQL)

Articolo
08/21/2024

Si applica a: SQL Server Istanza gestita di SQL di Azure

Invia un messaggio di posta elettronica ai destinatari specificati. Il messaggio potrebbe includere un set di risultati di query, allegati di file o entrambi. Quando la posta viene inserita correttamente nella coda Posta elettronica database, sp_send_dbmail restituisce l'oggetto mailitem_id del messaggio. Questa stored procedure si trova nel msdb database.

Convenzioni relative alla sintassi Transact-SQL

Sintassi

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 = ] N'subject' ]
    [ , [ @body = ] N'body' ]
    [ , [ @body_format = ] 'body_format' ]
    [ , [ @importance = ] 'importance' ]
    [ , [ @sensitivity = ] 'sensitivity' ]
    [ , [ @file_attachments = ] N'attachment [ ; ...n ]' ]
    [ , [ @query = ] N'query' ]
    [ , [ @execute_query_database = ] 'execute_query_database' ]
    [ , [ @attach_query_result_as_file = ] attach_query_result_as_file ]
    [ , [ @query_attachment_filename = ] N'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 ]
[ ; ]

Argomenti

[ @profile_name = ] 'profile_name'

Nome del profilo da cui inviare il messaggio. Il @profile_name è di tipo sysname, con un valore predefinito .NULL Il @profile_name deve essere il nome di un profilo di Posta elettronica database esistente. Quando non viene specificato alcun @profile_name , sp_send_dbmail usa il profilo privato predefinito per l'utente corrente. Se l'utente non ha un profilo privato predefinito, sp_send_dbmail usa il profilo pubblico predefinito per il msdb database. Se l'utente non ha un profilo privato predefinito e non esiste un profilo pubblico predefinito per il database, è necessario specificare @profile_name .

[ @recipients = ] 'recipients'

Elenco delimitato da punto e virgola di indirizzi di posta elettronica a cui inviare il messaggio. L'elenco dei destinatari è di tipo varchar(max). Anche se questo parametro è facoltativo, è necessario specificare almeno una delle @recipients, @copy_recipients o @blind_copy_recipients oppure sp_send_dbmail restituire un errore.

[ @copy_recipients = ] 'copy_recipients'

Elenco delimitato da punto e virgola di indirizzi di posta elettronica in cui copiare il messaggio in carbonio. L'elenco dei destinatari della copia è di tipo varchar(max). Anche se questo parametro è facoltativo, è necessario specificare almeno una delle @recipients, @copy_recipients o @blind_copy_recipients oppure sp_send_dbmail restituire un errore.

[ @blind_copy_recipients = ] 'blind_copy_recipients'

Elenco delimitato da punto e virgola di indirizzi di posta elettronica in cui copiare il messaggio. L'elenco dei destinatari della copia non vedente è di tipo varchar(max).The blind copy recipients list is of type varchar(max). Anche se questo parametro è facoltativo, è necessario specificare almeno una delle @recipients, @copy_recipients o @blind_copy_recipients oppure sp_send_dbmail restituire un errore.

[ @from_address = ] 'from_address'

Valore dell'indirizzo "dall'indirizzo" del messaggio di posta elettronica. Si tratta di un parametro facoltativo utilizzato per eseguire l'override delle impostazioni nel profilo di posta elettronica. Questo parametro è di tipo varchar(max). Le impostazioni di sicurezza SMTP determinano se questi override vengono accettati. Se non viene specificato alcun parametro, il valore predefinito è NULL.

[ @reply_to = ] 'reply_to'

Valore del messaggio di posta elettronica "rispondi all'indirizzo". Accetta un solo indirizzo di posta elettronica come valore valido. Si tratta di un parametro facoltativo utilizzato per eseguire l'override delle impostazioni nel profilo di posta elettronica. Questo parametro è di tipo varchar(max). Le impostazioni di sicurezza SMTP determinano se questi override vengono accettati. Se non viene specificato alcun parametro, il valore predefinito è NULL.

[ @subject = ] N'subject'

Oggetto del messaggio di posta elettronica. Il soggetto è di tipo nvarchar(255). Se l'oggetto viene omesso, il valore predefinito è "Messaggio SQL Server".

[ @body = ] N'body'

Corpo del messaggio di posta elettronica. Il corpo del messaggio è di tipo nvarchar(max), con un valore predefinito .NULL

[ @body_format = ] 'body_format'

Formato del corpo del messaggio. Il parametro è di tipo varchar(20), con un valore predefinito .NULL Se specificato, le intestazioni del messaggio in uscita vengono impostate in modo da indicare che per il corpo del messaggio è impostato il formato specificato. Il parametro può contenere uno dei valori seguenti:

TEXT (impostazione predefinita)
HTML

[ @importance = ] 'importance'

Importanza del messaggio. Il parametro è di tipo varchar(6). Il parametro può contenere uno dei valori seguenti:

Low
Normal (predefinito)
High

[ @sensitivity = ] 'sensitivity'

Riservatezza del messaggio. Il parametro è di tipo varchar(12). Il parametro può contenere uno dei valori seguenti:

Normal (predefinito)
Personal
Private
Confidential

[ @file_attachments = ] N'file_attachments'

Elenco delimitato da punto e virgola di nomi di file da allegare al messaggio di posta elettronica. I file nell'elenco devono essere specificati come percorsi assoluti. L'elenco allegati è di tipo nvarchar(max). Per impostazione predefinita, Posta elettronica database limita le dimensioni degli allegati a 1 MB per file.

Importante

Questo parametro non è disponibile in Istanza gestita di SQL di Azure, perché non è in grado di accedere al file system locale.

[ @query = ] N'query'

Query da eseguire. I risultati della query possono essere allegati come file o inclusi nel corpo del messaggio di posta elettronica. La query è di tipo nvarchar(max)e può contenere qualsiasi istruzione Transact-SQL valida. La query viene eseguita in una sessione separata, quindi le variabili locali nella chiamata sp_send_dbmail allo script non sono disponibili per la query.

Quando si usa il parametro @query , l'entità che viene eseguita sp_send_dbmail deve essere connessa come utente singolo, non come parte di un gruppo, indipendentemente dal fatto che un ID Microsoft Entra (in precedenza Azure Active Directory) o un gruppo di Windows Active Directory. Gli account di accesso di SQL Server, le identità di Windows e le identità di Microsoft Entra possono eseguire la query, ma i membri del gruppo non possono, a causa di Istanza gestita di SQL di Azure limitazioni di rappresentazione e EXECUTE AS.

[ @execute_query_database = ] 'execute_query_database'

Contesto del database all'interno del quale la stored procedure esegue la query. Il parametro è di tipo sysname, con un valore predefinito del database corrente. Questo parametro è applicabile solo se viene specificato @query .

[ @attach_query_result_as_file = ] attach_query_result_as_file

Specifica se il set di risultati della query viene restituito come file allegato. @attach_query_result_as_file è di tipo bit, con un valore predefinito .0

Quando il valore è 0, i risultati della query vengono inclusi nel corpo del messaggio di posta elettronica, dopo il contenuto del parametro @body . Quando il valore è 1, i risultati vengono restituiti come allegato. Questo parametro è applicabile solo se viene specificato @query .

[ @query_attachment_filename = ] N'query_attachment_filename'

Specifica il nome di file da utilizzare per il set di risultati dell'allegato query. @query_attachment_filename è di tipo nvarchar(255), con un valore predefinito .NULL Questo parametro viene ignorato quando @attach_query_result_as_file è 0. Quando @attach_query_result_as_file è 1 e questo parametro è NULL, Posta elettronica database crea un nome file arbitrario.

[ @query_result_header = ] query_result_header

Specifica se includere le intestazioni di colonna nei risultati della query. Il valore query_result_header è di tipo bit. Quando il valore è 1, i risultati della query contengono intestazioni di colonna. Quando il valore è 0, i risultati della query non includono intestazioni di colonna. Per impostazione predefinita, questo parametro è 1. Questo parametro è applicabile solo se viene specificato @query .

L'errore seguente può verificarsi quando si imposta @query_result_header su 0 e impostando @query_no_truncate su 1:

Msg 22050, Level 16, State 1, Line 12: Failed to initialize sqlcmd library with error number -2147024809.

[ @query_result_width = ] query_result_width

Larghezza della riga, in caratteri, da utilizzare per formattare i risultati della query. Il @query_result_width è di tipo int, con un valore predefinito .256 Il valore specificato deve essere compreso tra 10 e 32767. Questo parametro è applicabile solo se viene specificato @query .

[ @query_result_separator = ] 'query_result_separator'

Carattere utilizzato per separare le colonne nell'output della query. Il separatore è di tipo char(1).The separator is of type char(1). Il valore predefinito è ' ' (spazio).

[ @exclude_query_output = ] exclude_query_output

Specifica se restituire l'output dell'esecuzione della query nel messaggio di posta elettronica. @exclude_query_output è bit, con un valore predefinito .0 Quando questo parametro è 0, l'esecuzione della sp_send_dbmail stored procedure stampa il messaggio restituito come risultato dell'esecuzione della query nella console. Quando questo parametro è 1, l'esecuzione della sp_send_dbmail stored procedure non stampa alcun messaggio di esecuzione della query nella console.

[ @append_query_error = ] append_query_error

Specifica se inviare il messaggio di posta elettronica quando viene restituito un errore dalla query specificata nell'argomento @query . @append_query_error è bit, con un valore predefinito .0 Quando questo parametro è 1, Posta elettronica database invia il messaggio di posta elettronica e include il messaggio di errore della query nel corpo del messaggio di posta elettronica. Quando questo parametro è 0, Posta elettronica database non invia il messaggio di posta elettronica e sp_send_dbmail termina con il codice 1restituito , che indica un errore.

[ @query_no_truncate = ] query_no_truncate

Specifica se eseguire la query con l'opzione che consente di evitare il troncamento di tipi di dati di lunghezza variabile di grandi dimensioni (varchar(max), nvarchar(max), varbinary(max), xml, text, ntext, image e tipi di dati definiti dall'utente. Se impostata, i risultati della query non includono intestazioni di colonna. Il valore @query_no_truncate è di tipo bit. Quando il valore è 0 o meno specificato, le colonne nella query vengono troncate a 256 caratteri. Quando il valore è 1, le colonne nella query non vengono troncate. Per impostazione predefinita, questo parametro è 0.

Nota

Se usato con grandi quantità di dati, l'opzione @query_no_truncate utilizza risorse aggiuntive e può rallentare le prestazioni del server.

[ @query_result_no_padding = ] query_result_no_padding

Il tipo è bit. Il valore predefinito è 0. Quando si imposta su 1, i risultati della query non vengono riempiti, riducendo eventualmente le dimensioni del file. Se si imposta su e si imposta @query_result_no_padding il parametro @query_result_width, il parametro @query_result_no_padding sovrascrive il parametro @query_result_width.1

In questo caso, non si verifica alcun errore.

L'errore seguente può verificarsi quando si imposta @query_result_no_padding su 1 e si specifica un parametro per @query_no_truncate:

Msg 22050, Level 16, State 1, Line 0: Failed to execute the query because the @query_result_no_append and @query_no_truncate options are mutually exclusive.

Se si imposta il @query_result_no_padding su 1 e si imposta il parametro @query_no_truncate , viene generato un errore.

[ @mailitem_id = ] mailitem_id [ OUTPUT ]

Il parametro di output facoltativo restituisce l'oggetto mailitem_id del messaggio. @mailitem_id è di tipo int.

Valori del codice restituito

Un codice restituito indica l'esito 0 positivo. Qualsiasi altro valore indica esito negativo. Il codice di errore per l'istruzione non riuscita viene archiviato nella @@ERROR variabile .

Set di risultati

In caso di esito positivo, viene restituito il messaggio "Posta elettronica accodata".

Osservazioni:

Prima di usare, è necessario abilitare Posta elettronica database tramite la Configurazione guidata Posta elettronica database o sp_configure.

sysmail_stop_sparresta Posta elettronica database arrestando gli oggetti di Service Broker utilizzati dal programma esterno. sp_send_dbmailaccetta comunque la posta quando Posta elettronica database viene interrotto tramite sysmail_stop_sp. Per avviare Posta elettronica database, usare sysmail_start_sp.

Quando @profile non viene specificato, sp_send_dbmail usa un profilo predefinito. Se l'utente che invia il messaggio di posta elettronica dispone di un profilo privato predefinito, Posta elettronica database utilizzerà tale profilo. Se l'utente non ha un profilo privato predefinito, sp_send_dbmail usa il profilo pubblico predefinito. Se non è presente alcun profilo privato predefinito per l'utente e nessun profilo pubblico predefinito, sp_send_dbmail restituisce un errore.

sp_send_dbmail non supporta i messaggi di posta elettronica senza contenuto. Per inviare un messaggio di posta elettronica, è necessario specificare almeno una delle @body, @query, @file_attachments o @subject. In caso contrario, sp_send_dbmail restituisce un errore.

Per controllare l'accesso ai file, Posta elettronica database utilizza il contesto di sicurezza di Windows dell'utente corrente. Pertanto, gli utenti autenticati con l'autenticazione di SQL Server non possono allegare file usando @file_attachments. Windows non consente a SQL Server di fornire le credenziali da un computer remoto a un altro computer remoto. Pertanto, Posta elettronica database potrebbe non essere in grado di allegare file da una condivisione di rete nei casi in cui il comando viene eseguito da un computer diverso dal computer in cui è in esecuzione SQL Server.

Se vengono specificati sia @query che @file_attachments e non è possibile trovare il file, la query viene comunque eseguita ma il messaggio di posta elettronica non viene inviato.

Se si specifica una query, il set dei risultati viene formattato come testo incorporato. I dati binari nel risultato vengono inviati in formato esadecimale.

I parametri @recipients, @copy_recipients e @blind_copy_recipients sono elenchi delimitati da punti e virgola di indirizzi di posta elettronica. È necessario specificare almeno uno di questi parametri o sp_send_dbmail restituire un errore.

Quando si esegue sp_send_dbmail senza un contesto di transazione, Posta elettronica database avvia ed esegue il commit di una transazione implicita. Quando si esegue sp_send_dbmail da una transazione esistente, Posta elettronica database si basa sull'utente per eseguire il commit o il rollback di eventuali modifiche. Non avvia una transazione interna.

Autorizzazioni

Autorizzazioni di esecuzione per impostazione predefinita per sp_send_dbmail tutti i membri del ruolo del database DatabaseMailUser nel msdb database. Tuttavia, quando l'utente che invia il messaggio non dispone dell'autorizzazione per usare il profilo per la richiesta, sp_send_dbmail restituisce un errore e non invia il messaggio.

Esempi

R. Inviare un messaggio di posta elettronica

In questo esempio viene inviato un messaggio di posta elettronica all'amico utilizzando l'indirizzo myfriend@adventure-works.comdi posta elettronica . L'oggetto del messaggio è Automated Success Message. Il corpo del messaggio contiene la frase The stored procedure finished successfully.

EXEC msdb.dbo.sp_send_dbmail
    @profile_name = 'Adventure Works Administrator',
    @recipients = 'yourfriend@adventure-works.com',
    @body = 'The stored procedure finished successfully.',
    @subject = 'Automated Success Message';

B. Inviare un messaggio di posta elettronica con i risultati di una query

In questo esempio viene inviato un messaggio di posta elettronica all'amico utilizzando l'indirizzo yourfriend@adventure-works.comdi posta elettronica . Il messaggio ha l'oggetto Work Order Counted esegue una query che mostra il numero di ordini di lavoro con meno DueDate di due giorni dopo il 30 aprile 2022. I risultati vengono allegati come file di testo.

EXEC msdb.dbo.sp_send_dbmail
    @profile_name = 'Adventure Works Administrator',
    @recipients = 'yourfriend@adventure-works.com',
    @query = 'SELECT COUNT(*) FROM AdventureWorks2022.Production.WorkOrder
                  WHERE DueDate > ''2022-04-30''
                  AND  DATEDIFF(dd, ''2022-04-30'', DueDate) < 2',
    @subject = 'Work Order Count',
    @attach_query_result_as_file = 1;

C. Inviare un messaggio di posta elettronica HTML

In questo esempio viene inviato un messaggio di posta elettronica all'amico utilizzando l'indirizzo yourfriend@adventure-works.comdi posta elettronica . Il messaggio contiene l'oggetto Work Order Liste contiene un documento HTML che mostra gli ordini di lavoro con meno DueDate di due giorni dopo il 30 aprile 2022. Il messaggio viene inviato in formato 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
            INNER JOIN AdventureWorks.Production.Product AS p
                ON wo.ProductID = p.ProductID
            WHERE DueDate > '2022-04-30'
                AND DATEDIFF(dd, '2022-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 = 'yourfriend@adventure-works.com',
    @subject = 'Work Order List',
    @body = @tableHTML,
    @body_format = 'HTML';

Condividi tramite

sp_send_dbmail (Transact-SQL)

Sintassi

Argomenti

[ @profile_name = ] 'profile_name'

[ @recipients = ] 'recipients'

[ @copy_recipients = ] 'copy_recipients'

[ @blind_copy_recipients = ] 'blind_copy_recipients'

[ @from_address = ] 'from_address'

[ @reply_to = ] 'reply_to'

[ @subject = ] N'subject'

[ @body = ] N'body'

[ @body_format = ] 'body_format'

[ @importance = ] 'importance'

[ @sensitivity = ] 'sensitivity'

[ @file_attachments = ] N'file_attachments'

[ @query = ] N'query'

[ @execute_query_database = ] 'execute_query_database'

[ @attach_query_result_as_file = ] attach_query_result_as_file

[ @query_attachment_filename = ] N'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 ]

Valori del codice restituito

Set di risultati

Osservazioni:

Autorizzazioni

Esempi

R. Inviare un messaggio di posta elettronica

B. Inviare un messaggio di posta elettronica con i risultati di una query

C. Inviare un messaggio di posta elettronica HTML

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

sp_send_dbmail (Transact-SQL)

Sintassi

Argomenti

[ @profile_name = ] 'profile_name'

[ @recipients = ] 'recipients'

[ @copy_recipients = ] 'copy_recipients'

[ @blind_copy_recipients = ] 'blind_copy_recipients'

[ @from_address = ] 'from_address'

[ @reply_to = ] 'reply_to'

[ @subject = ] N'subject'

[ @body = ] N'body'

[ @body_format = ] 'body_format'

[ @importance = ] 'importance'

[ @sensitivity = ] 'sensitivity'

[ @file_attachments = ] N'file_attachments'

[ @query = ] N'query'

[ @execute_query_database = ] 'execute_query_database'

[ @attach_query_result_as_file = ] attach_query_result_as_file

[ @query_attachment_filename = ] N'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 ]

Valori del codice restituito

Set di risultati

Osservazioni:

Autorizzazioni

Esempi

R. Inviare un messaggio di posta elettronica

B. Inviare un messaggio di posta elettronica con i risultati di una query

C. Inviare un messaggio di posta elettronica HTML

Contenuto correlato

Commenti e suggerimenti

Risorse aggiuntive