sp_send_dbmail (Transact-SQL)

platí pro:SQL Serverazure SQL Managed Instance

Odešle e-mailovou zprávu určeným příjemcům. Zpráva může obsahovat sadu výsledků dotazu, přílohy souborů nebo obojí. Po úspěšném umístění pošty do fronty sp_send_dbmail Databázová pošta vrátí mailitem_id zprávu. Tato uložená procedura je v msdb databázi.

Transact-SQL konvence syntaxe

Syntaxe

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 ]
[ ; ]

Arguments

[ @profile_name = ] 'profile_name'

Název profilu, ze který chcete zprávu odeslat. @profile_name je typu sysname s výchozím nastavením NULL. @profile_name musí být název existujícího profilu databázové pošty. Pokud není zadán žádný @profile_name , sp_send_dbmail použije pro aktuálního uživatele výchozí privátní profil. Pokud uživatel nemá výchozí privátní profil, sp_send_dbmail použije pro databázi výchozí veřejný profil msdb . Pokud uživatel nemá výchozí privátní profil a pro databázi neexistuje žádný výchozí veřejný profil, musí být zadán @profile_name .

[ @recipients = ] 'příjemci'

Seznam e-mailových adres oddělených středníkem pro odeslání zprávy. Seznam příjemců je typu varchar(max). I když je tento parametr volitelný, musí být zadán alespoň jeden z @recipients, @copy_recipients nebo @blind_copy_recipients nebo sp_send_dbmail vrací chybu.

[ @copy_recipients = ] 'copy_recipients'

Středník oddělený seznam e-mailových adres pro kopírování zprávy do uhlíku. Seznam příjemců kopírování je typu varchar(max). I když je tento parametr volitelný, musí být zadán alespoň jeden z @recipients, @copy_recipients nebo @blind_copy_recipients nebo sp_send_dbmail vrací chybu.

[ @blind_copy_recipients = ] 'blind_copy_recipients'

Středník oddělený seznam e-mailových adres, do které se zpráva zkopíruje do slepého uhlíku. Seznam příjemců nevidomých kopií je typu varchar(max). I když je tento parametr volitelný, musí být zadán alespoň jeden z @recipients, @copy_recipients nebo @blind_copy_recipients nebo sp_send_dbmail vrací chybu.

[ @from_address = ] 'from_address'

Hodnota "z adresy" e-mailové zprávy. Jedná se o volitelný parametr, který slouží k přepsání nastavení v profilu pošty. Tento parametr je typu varchar(max). Nastavení zabezpečení SMTP určuje, jestli jsou tato přepsání přijata. Pokud není zadán žádný parametr, je NULLvýchozí hodnota .

[ @reply_to = ] 'reply_to'

Hodnota odpovědi na adresu e-mailové zprávy. Přijímá jako platnou hodnotu jenom jednu e-mailovou adresu. Jedná se o volitelný parametr, který slouží k přepsání nastavení v profilu pošty. Tento parametr je typu varchar(max). Nastavení zabezpečení SMTP určuje, jestli jsou tato přepsání přijata. Pokud není zadán žádný parametr, je NULLvýchozí hodnota .

[ @subject = ] N'subject'

Předmět e-mailové zprávy. Předmět je typu nvarchar(255). Pokud není zadán žádný předmět, výchozí hodnota je ZPRÁVA SQL Serveru.

[ @body = ] N'body'

Text e-mailové zprávy. Text zprávy je typu nvarchar(max), s výchozí hodnotou NULL.

[ @body_format = ] 'body_format'

Formát textu zprávy. Parametr je typu varchar(20) s výchozím parametrem NULL. Po zadání jsou záhlaví odchozí zprávy nastavena tak, aby indikovala, že text zprávy má zadaný formát. Parametr může obsahovat jednu z následujících hodnot:

• TEXT (výchozí)
• jazyk HTML

[ @importance = ] 'důležitost'

Důležitost zprávy. Parametr je typu varchar(6). Parametr může obsahovat jednu z následujících hodnot:

• Low
• Normal (výchozí)
• High

[ @sensitivity = ] 'citlivost'

Citlivost zprávy. Parametr je typu varchar(12). Parametr může obsahovat jednu z následujících hodnot:

• Normal (výchozí)
• Personal
• Private
• Confidential

[ @file_attachments = ] N'file_attachments'

Seznam názvů souborů oddělených středníkem, který se má připojit k e-mailové zprávě. Soubory v seznamu musí být zadány jako absolutní cesty. Seznam příloh je typu nvarchar(max). Ve výchozím nastavení databázová pošta omezuje přílohy souborů na 1 MB na soubor.

Důležité

Tento parametr není ve službě Azure SQL Managed Instance dostupný, protože nemá přístup k místnímu systému souborů.

[ @query = ] N'query'

Dotaz, který se má provést. Výsledky dotazu lze připojit jako soubor nebo zahrnout do textu e-mailové zprávy. Dotaz je typu nvarchar(max) a může obsahovat jakékoli platné příkazy Transact-SQL. Dotaz se spustí v samostatné relaci, takže pro dotaz nejsou k dispozici místní proměnné ve volání sp_send_dbmail skriptu.

Pokud použijete parametr @query , musí být objekt zabezpečení, který se spouští sp_send_dbmail , připojený jako jednotlivec, nikoli jako součást skupiny, ať už jde o ID Microsoft Entra (dříve Azure Active Directory) nebo skupinu Windows Active Directory. Přihlašovací jména SQL Serveru, identity Windows a identity Microsoft Entra mohou spouštět dotaz, ale členové skupiny nemůžou kvůli omezení zosobnění služby Azure SQL Managed Instance a spuštění as.

[ @execute_query_database = ] 'execute_query_database'

Kontext databáze, ve kterém uložená procedura spouští dotaz. Parametr je typu sysname s výchozím nastavením aktuální databáze. Tento parametr lze použít pouze v případě , že je zadán @query.

[ @attach_query_result_as_file = ] attach_query_result_as_file

Určuje, zda je sada výsledků dotazu vrácena jako připojený soubor. @attach_query_result_as_file je bit typu, s výchozím nastavením 0.

Pokud je 0hodnota , výsledky dotazu se za obsah @body parametru zahrnou do textu e-mailové zprávy. Pokud je 1hodnota , výsledky se vrátí jako příloha. Tento parametr lze použít pouze v případě , že je zadán @query.

[ @query_attachment_filename = ] N'query_attachment_filename'

Určuje název souboru, který se má použít pro sadu výsledků přílohy dotazu. @query_attachment_filename je typu nvarchar(255) s výchozím nastavením NULL. Tento parametr je ignorován při @attach_query_result_as_file je 0. Pokud je @attach_query_result_as_file a tento parametr je 1NULL, Database Mail vytvoří libovolný název souboru.

[ @query_result_header = ] query_result_header

Určuje, jestli výsledky dotazu obsahují záhlaví sloupců. Hodnota query_result_header je bit typu. Pokud je 1hodnota, výsledky dotazu obsahují záhlaví sloupců. Pokud je 0hodnota , výsledky dotazu neobsahují záhlaví sloupců. Tento parametr má výchozí hodnotu 1. Tento parametr lze použít pouze v případě , že je zadán @query.

Při nastavení @query_result_header0 a nastavení @query_no_truncate na 1:

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

[ @query_result_width = ] query_result_width

Šířka čáry ve znaznachu, která se má použít k formátování výsledků dotazu. @query_result_width je typu int s výchozím nastavením 256. Zadaná hodnota musí být mezi 10 a 32767. Tento parametr lze použít pouze v případě , že je zadán @query.

[ @query_result_separator = ] 'query_result_separator'

Znak použitý k oddělení sloupců ve výstupu dotazu. Oddělovač je typu char(1). Výchozí hodnota ' ' je (mezera).

[ @exclude_query_output = ] exclude_query_output

Určuje, jestli se má vrátit výstup spuštění dotazu v e-mailové zprávě. @exclude_query_output je bit s výchozím nastavením 0. Pokud je 0tento parametr , spuštění sp_send_dbmail uložené procedury vytiskne zprávu vrácenou jako výsledek spuštění dotazu v konzole. Pokud je 1tento parametr , spuštění sp_send_dbmail uložené procedury netiskne žádné zprávy o spuštění dotazu v konzole.

[ @append_query_error = ] append_query_error

Určuje, jestli se má e-mail odeslat, když se vrátí chyba z dotazu zadaného v argumentu @query . @append_query_error je bit s výchozím nastavením 0. Pokud je 1tento parametr, odešle databázová pošta e-mailovou zprávu a do textu e-mailové zprávy zahrne chybovou zprávu dotazu. Pokud je 0tento parametr , Databázová pošta neodesílá e-mailovou zprávu a sp_send_dbmail končí návratovým kódem 1, který označuje selhání.

[ @query_no_truncate = ] query_no_truncate

Určuje, jestli se má dotaz spustit s možností, která zabraňuje zkrácení datových typů velkých proměnných délky (varchar(max), nvarchar(max), varbinary(max), xml, text, ntext, obrázek a uživatelsky definované datové typy). Pokud je tato sada nastavená, výsledky dotazu neobsahují záhlaví sloupců. Hodnota @query_no_truncate je bit typu. Pokud je 0 hodnota zadaná nebo není zadaná, sloupce v dotazu se zkrátí na 256 znaků. Pokud je 1hodnota , sloupce v dotazu nejsou zkráceny. Tento parametr má výchozí hodnotu 0.

Poznámka:

Při použití s velkým množstvím dat využívá @query_no_truncate možnost další prostředky a může zpomalit výkon serveru.

[ @query_result_no_padding = ] query_result_no_padding

Typ je bit. Výchozí hodnota je 0. Pokud nastavíte hodnotu 1, výsledky dotazu nebudou vycpané, pravděpodobně se zmenšují velikost souboru. Pokud nastavíte @query_result_no_padding1 parametr @query_result_width a nastavíte ho, parametr @query_result_no_padding přepíše parametr @query_result_width .

V takovém případě nedojde k žádné chybě.

Při nastavování @query_result_no_padding1 a poskytnutí parametru pro @query_no_truncate může dojít k následující chybě:

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.

Pokud nastavíte @query_result_no_padding1 a nastavíte parametr @query_no_truncate , vyvolá se chyba.

[ @mailitem_id = ] mailitem_id [ VÝSTUP ]

Volitelný výstupní parametr vrátí mailitem_id zprávu. @mailitem_id je typu int.

Hodnoty návratového kódu

Návratový 0 kód znamená úspěch. Jakákoli jiná hodnota znamená selhání. Kód chyby pro příkaz, který selhal, je uložen v @@ERROR proměnné.

Sada výsledků

Při úspěchu vrátí zprávu Pošta zařazená do fronty.

Poznámky

Před použitím musí být databázová pošta povolena pomocí Průvodce konfigurací databázové pošty nebo sp_configure.

sysmail_stop_sp zastaví databázovou poštu zastavením objektů Service Broker, které externí program používá. sp_send_dbmail stále přijímá poštu, pokud je databázová pošta zastavena pomocí sysmail_stop_sp. Chcete-li spustit databázová pošta, použijte sysmail_start_sppříkaz .

Pokud není zadaný @profile , sp_send_dbmail použije se výchozí profil. Pokud má uživatel odesílající e-mailovou zprávu výchozí privátní profil, použije tato databázová pošta tento profil. Pokud uživatel nemá výchozí privátní profil, sp_send_dbmail použije výchozí veřejný profil. Pokud pro uživatele neexistuje žádný výchozí privátní profil a žádný výchozí veřejný profil, sp_send_dbmail vrátí chybu.

sp_send_dbmail nepodporuje e-mailové zprávy bez obsahu. Chcete-li odeslat e-mailovou zprávu, je nutné zadat alespoň jeden z @body, @query, @file_attachments nebo @subject. sp_send_dbmail V opačném případě vrátí chybu.

Databázová pošta se spouští v kontextu zabezpečení účtu služby pro SQL Server. Proto uživatelé, kteří jsou ověřeni pomocí ověřování SQL Serveru, nemůžou připojit soubory pomocí @file_attachments. Systém Windows neumožňuje SYSTÉMU SQL Server poskytovat přihlašovací údaje ze vzdáleného počítače do jiného vzdáleného počítače. Proto nemusí být databázová pošta schopná připojit soubory ze sdílené síťové složky v případech, kdy je příkaz spuštěn z jiného počítače než z počítače, na kterém běží SQL Server.

Pokud jsou zadány @query i @file_attachments a soubor nelze najít, dotaz se přesto spustí, ale e-mail se neodesílají.

Při zadání dotazu se sada výsledků naformátuje jako vložený text. Binární data ve výsledku se odesílají v šestnáctkovém formátu.

Parametry @recipients, @copy_recipients a @blind_copy_recipients jsou seznam e-mailových adres oddělených středníkem. Je nutné zadat alespoň jeden z těchto parametrů nebo sp_send_dbmail vrátit chybu.

Při provádění sp_send_dbmail bez kontextu transakce spustí databázová pošta a potvrdí implicitní transakci. Při provádění sp_send_dbmail z existující transakce závisí databázová pošta na uživatele, aby buď potvrdit nebo vrátit zpět všechny změny. Nespustí vnitřní transakci.

Povolení

Spusťte oprávnění pro sp_send_dbmail výchozí nastavení pro všechny členy databázové role DatabaseMailUserRole v msdb databázi. Pokud ale uživatel, který zprávu odesílá, nemá oprávnění k použití profilu pro požadavek, sp_send_dbmail vrátí chybu a zprávu neodešle.

Examples

A. Odeslání e-mailové zprávy

Tento příklad odešle e-mailovou zprávu známému pomocí e-mailové adresy myfriend@adventure-works.com. Zpráva má předmět Automated Success Message. Text zprávy obsahuje větu The stored procedure finished successfully.

EXECUTE 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. Odeslání e-mailové zprávy s výsledky dotazu

Tento příklad odešle e-mailovou zprávu známému pomocí e-mailové adresy yourfriend@adventure-works.com. Zpráva obsahuje předmět Work Order Counta spustí dotaz, který zobrazuje počet pracovních objednávek s DueDate méně než dvěma dny po 30. dubnu 2022. Databázová pošta připojí výsledek jako textový soubor.

EXECUTE 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. Odeslání e-mailové zprávy HTML

Tento příklad odešle e-mailovou zprávu známému pomocí e-mailové adresy yourfriend@adventure-works.com. Zpráva obsahuje předmět Work Order Lista obsahuje dokument HTML, který zobrazuje pracovní objednávky s DueDate méně než dvěma dny po 30. dubnu 2022. Databázová pošta odešle zprávu ve formátu 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>';

EXECUTE msdb.dbo.sp_send_dbmail
    @recipients = 'yourfriend@adventure-works.com',
    @subject = 'Work Order List',
    @body = @tableHTML,
    @body_format = 'HTML';

Související obsah

• Databázová pošta
• Objekty konfigurace databázové pošty
• Uložené procedury databázové pošty (Transact-SQL)
• Externí program Databázová pošta
• sp_addrolemember (Transact-SQL)