sp_send_dbmail (Transact-SQL)

Dotyczy:SQL Server Azure SQL Managed Instance

Wysyła wiadomość e-mail do określonych adresatów. Komunikat może zawierać zestaw wyników zapytania, załączniki plików lub oba te elementy. Gdy poczta zostanie pomyślnie umieszczona w kolejce Poczta bazy danych, sp_send_dbmail zwraca mailitem_id komunikat . Ta procedura składowana znajduje się w msdb bazie danych.

Transact-SQL konwencje składni

Składnia

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'

Nazwa profilu do wysłania wiadomości z. @profile_name jest typu sysname z wartością domyślną NULL. @profile_name musi być nazwą istniejącego profilu poczty bazy danych. Jeśli nie określono @profile_name , sp_send_dbmail używa domyślnego profilu prywatnego dla bieżącego użytkownika. Jeśli użytkownik nie ma domyślnego profilu prywatnego, sp_send_dbmail użyj domyślnego profilu publicznego dla msdb bazy danych. Jeśli użytkownik nie ma domyślnego profilu prywatnego i nie ma domyślnego profilu publicznego dla bazy danych, należy określić @profile_name .

[ @recipients = ] "odbiorcy"

Rozdzielana średnikami lista adresów e-mail do wysłania wiadomości. Lista adresatów jest typu varchar(max). Mimo że ten parametr jest opcjonalny, co najmniej jeden z @recipients, @copy_recipients lub @blind_copy_recipients musi zostać określony lub sp_send_dbmail zwraca błąd.

[ @copy_recipients = ] 'copy_recipients'

Rozdzielana średnikami lista adresów e-mail do skopiowania wiadomości do wiadomości. Lista adresatów kopiowania jest typu varchar(max). Mimo że ten parametr jest opcjonalny, co najmniej jeden z @recipients, @copy_recipients lub @blind_copy_recipients musi zostać określony lub sp_send_dbmail zwraca błąd.

[ @blind_copy_recipients = ] 'blind_copy_recipients'

Rozdzielana średnikami lista adresów e-mail do ślepego węgla skopiuj wiadomość do. Lista adresatów kopii ślepej jest typu varchar(max). Mimo że ten parametr jest opcjonalny, co najmniej jeden z @recipients, @copy_recipients lub @blind_copy_recipients musi zostać określony lub sp_send_dbmail zwraca błąd.

[ @from_address = ] 'from_address'

Wartość "from address" wiadomości e-mail. Jest to opcjonalny parametr używany do zastępowania ustawień w profilu poczty. Ten parametr jest typu varchar(max). Ustawienia zabezpieczeń SMTP określają, czy te przesłonięcia są akceptowane. Jeśli nie określono parametru, wartość domyślna to NULL.

[ @reply_to = ] 'reply_to'

Wartość "odpowiedz na adres" wiadomości e-mail. Akceptuje tylko jeden adres e-mail jako prawidłową wartość. Jest to opcjonalny parametr używany do zastępowania ustawień w profilu poczty. Ten parametr jest typu varchar(max). Ustawienia zabezpieczeń SMTP określają, czy te przesłonięcia są akceptowane. Jeśli nie określono parametru, wartość domyślna to NULL.

[ @subject = ] N'subject'

Temat wiadomości e-mail. Temat jest typu nvarchar(255). Jeśli nie określono tematu, wartość domyślna to "Komunikat programu SQL Server".

[ @body = ] N'body'

Treść wiadomości e-mail. Treść komunikatu jest typu nvarchar(max), z wartością domyślną NULL.

[ @body_format = ] 'body_format'

Format treści wiadomości. Parametr jest typu varchar(20), z wartością domyślną NULL. Po określeniu nagłówki komunikatu wychodzącego są ustawione tak, aby wskazywały, że treść komunikatu ma określony format. Parametr może zawierać jedną z następujących wartości:

TEKST (wartość domyślna)
HTML

[ @importance = ] "ważność"

Znaczenie wiadomości. Parametr jest typu varchar(6). Parametr może zawierać jedną z następujących wartości:

Low
Normal (ustawienie domyślne)
High

[ @sensitivity = ] 'czułość'

Czułość komunikatu. Parametr jest typu varchar(12). Parametr może zawierać jedną z następujących wartości:

Normal (ustawienie domyślne)
Personal
Private
Confidential

[ @file_attachments = ] N'file_attachments'

Rozdzielana średnikami lista nazw plików do dołączenia do wiadomości e-mail. Pliki na liście muszą być określone jako ścieżki bezwzględne. Lista załączników jest typu nvarchar(max). Domyślnie poczta bazy danych ogranicza załączniki plików do 1 MB na plik.

Ważne

Ten parametr nie jest dostępny w usłudze Azure SQL Managed Instance, ponieważ nie może uzyskać dostępu do lokalnego systemu plików.

[ @query = ] N'query'

Zapytanie do wykonania. Wyniki zapytania można dołączyć jako plik lub dołączyć do treści wiadomości e-mail. Zapytanie jest typu nvarchar(max)i może zawierać dowolne prawidłowe instrukcje Transact-SQL. Zapytanie jest wykonywane w oddzielnej sesji, więc zmienne lokalne w wywołaniu sp_send_dbmail skryptu nie są dostępne dla zapytania.

Jeśli używasz parametru @query , podmiot zabezpieczeń, który wykonuje sp_send_dbmail , musi być połączony jako osoba, a nie jako część grupy, niezależnie od tego, czy identyfikator Entra firmy Microsoft (dawniej Azure Active Directory) czy grupa usługi Windows Active Directory. Identyfikatory logowania programu SQL Server, tożsamości systemu Windows i tożsamości firmy Microsoft Entra mogą wykonywać zapytanie, ale członkowie grupy nie mogą, ze względu na personifikację usługi Azure SQL Managed Instance i ograniczenia EXECUTE AS.

[ @execute_query_database = ] 'execute_query_database'

Kontekst bazy danych, w którym procedura składowana uruchamia zapytanie. Parametr jest typu sysname z wartością domyślną bieżącej bazy danych. Ten parametr ma zastosowanie tylko wtedy, gdy określono @query .

[ @attach_query_result_as_file = ] attach_query_result_as_file

Określa, czy zestaw wyników zapytania jest zwracany jako dołączony plik. @attach_query_result_as_file jest bitem typu z wartością domyślną 0.

Gdy wartość to 0, wyniki zapytania są uwzględniane w treści wiadomości e-mail po zawartości parametru @body . Gdy wartość to 1, wyniki są zwracane jako załącznik. Ten parametr ma zastosowanie tylko wtedy, gdy określono @query .

[ @query_attachment_filename = ] N'query_attachment_filename'

Określa nazwę pliku do użycia dla zestawu wyników załącznika zapytania. @query_attachment_filename jest typu nvarchar(255), z wartością domyślną NULL. Ten parametr jest ignorowany, gdy @attach_query_result_as_file to 0. Gdy @attach_query_result_as_file i 1 ten parametr to NULL, poczta bazy danych tworzy dowolną nazwę pliku.

[ @query_result_header = ] query_result_header

Określa, czy wyniki zapytania zawierają nagłówki kolumn. Wartość query_result_header jest bitem typu. Gdy wartość to 1, wyniki zapytania zawierają nagłówki kolumn. Gdy wartość to 0, wyniki zapytania nie zawierają nagłówków kolumn. Ten parametr domyślnie ma wartość 1. Ten parametr ma zastosowanie tylko wtedy, gdy określono @query .

Może wystąpić następujący błąd podczas ustawiania @query_result_header wartości0 i ustawienia @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

Szerokość wiersza w postaci znaków do formatowania wyników zapytania. @query_result_width jest typu int z wartością domyślną 256. Podana wartość musi zawierać się między 10 i 32767. Ten parametr ma zastosowanie tylko wtedy, gdy określono @query .

[ @query_result_separator = ] 'query_result_separator'

Znak używany do oddzielania kolumn w danych wyjściowych zapytania. Separator jest typu char(1). Domyślnie to ' ' (spacja).

[ @exclude_query_output = ] exclude_query_output

Określa, czy zwracać dane wyjściowe wykonania zapytania w wiadomości e-mail. @exclude_query_output jest bitowa z wartością domyślną 0. Gdy ten parametr ma 0wartość , wykonanie sp_send_dbmail procedury składowanej powoduje wyświetlenie komunikatu zwróconego w wyniku wykonania zapytania w konsoli programu . Gdy ten parametr ma 1wartość , wykonanie sp_send_dbmail procedury składowanej nie powoduje wyświetlenia żadnego komunikatu wykonywania zapytania w konsoli programu .

[ @append_query_error = ] append_query_error

Określa, czy wysyłać wiadomość e-mail po powrocie błędu z zapytania określonego w argumencie @query . @append_query_error jest bitowa z wartością domyślną 0. Gdy ten parametr to 1, poczta bazy danych wysyła wiadomość e-mail i zawiera komunikat o błędzie zapytania w treści wiadomości e-mail. Jeśli ten parametr to 0, poczta bazy danych nie wysyła wiadomości e-mail i sp_send_dbmail kończy się zwracanym kodem 1wskazującym błąd.

[ @query_no_truncate = ] query_no_truncate

Określa, czy wykonać zapytanie z opcją, która pozwala uniknąć obcinania dużych typów danych o zmiennej długości (varchar(max), nvarchar(max), varbinary(max), xml, text, ntext, image i zdefiniowanych przez użytkownika typów danych. Po ustawieniu wyniki zapytania nie zawierają nagłówków kolumn. Wartość @query_no_truncate jest bitem typu. Jeśli wartość jest 0 określona, kolumny w zapytaniu obcinają do 256 znaków. Gdy wartość to 1, kolumny w zapytaniu nie są obcinane. Ten parametr domyślnie ma wartość 0.

Uwaga / Notatka

W przypadku użycia z dużą ilością danych opcja @query_no_truncate zużywa dodatkowe zasoby i może spowolnić wydajność serwera.

[ @query_result_no_padding = ] query_result_no_padding

Typ jest bitowy. Wartość domyślna to 0. W przypadku ustawienia 1wartości wyniki zapytania nie są dopełniane, co może zmniejszyć rozmiar pliku. Jeśli ustawisz @query_result_no_padding1 wartość i ustawisz parametr @query_result_width , parametr @query_result_no_padding zastępuje parametr @query_result_width .

W takim przypadku nie wystąpi błąd.

Podczas ustawiania @query_result_no_padding i podawania parametru dla 1@query_no_truncate może wystąpić następujący błąd:

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.

Jeśli ustawisz @query_result_no_padding1 i ustawisz parametr @query_no_truncate , zostanie zgłoszony błąd.

[ @mailitem_id = ] mailitem_id [ OUTPUT ]

Opcjonalny parametr wyjściowy zwraca mailitem_id komunikat . @mailitem_id jest typu int.

Zwracanie wartości kodu

Kod powrotu 0 oznacza powodzenie. Każda inna wartość oznacza niepowodzenie. Kod błędu instrukcji, która nie powiodła się, jest przechowywany w zmiennej @@ERROR .

Zestaw wyników

Po powodzeniu zwraca komunikat "Poczta w kolejce".

Uwagi

Przed użyciem poczta bazy danych musi być włączona przy użyciu Kreatora konfiguracji poczty bazy danych lub sp_configure.

sysmail_stop_sp zatrzymuje usługę Poczta bazy danych przez zatrzymanie obiektów brokera usług używanych przez program zewnętrzny. sp_send_dbmail nadal akceptuje pocztę, gdy poczta bazy danych została zatrzymana przy użyciu polecenia sysmail_stop_sp. Aby uruchomić usługę Poczta bazy danych, użyj polecenia sysmail_start_sp.

Jeśli @profile nie zostanie określony, sp_send_dbmail użyj profilu domyślnego. Jeśli użytkownik wysyłający wiadomość e-mail ma domyślny profil prywatny, usługa Database Mail używa tego profilu. Jeśli użytkownik nie ma domyślnego profilu prywatnego, sp_send_dbmail używa domyślnego profilu publicznego. Jeśli użytkownik nie ma domyślnego profilu prywatnego i nie ma domyślnego profilu publicznego, sp_send_dbmail zwraca błąd.

sp_send_dbmail nie obsługuje wiadomości e-mail bez zawartości. Aby wysłać wiadomość e-mail, należy określić co najmniej jedną z @body, @query, @file_attachments lub @subject. sp_send_dbmail W przeciwnym razie zwraca błąd.

Poczta bazy danych jest uruchamiana w kontekście zabezpieczeń konta usługi dla programu SQL Server. W związku z tym użytkownicy uwierzytelnieni za pomocą uwierzytelniania programu SQL Server nie mogą dołączać plików przy użyciu @file_attachments. System Windows nie zezwala programowi SQL Server na podanie poświadczeń z komputera zdalnego do innego komputera zdalnego. W związku z tym poczta bazy danych może nie być w stanie dołączyć plików z udziału sieciowego w przypadkach, gdy polecenie jest uruchamiane z komputera innego niż komputer, na którym działa program SQL Server.

Jeśli określono zarówno @query , jak i @file_attachments i nie można odnaleźć pliku, zapytanie jest nadal wykonywane, ale wiadomość e-mail nie jest wysyłana.

Po określeniu zapytania zestaw wyników jest sformatowany jako tekst wbudowany. Dane binarne w wyniku są wysyłane w formacie szesnastkowym.

Parametry @recipients, @copy_recipients i @blind_copy_recipients to rozdzielane średnikami listy adresów e-mail. Należy podać co najmniej jeden z tych parametrów lub sp_send_dbmail zwrócić błąd.

Podczas wykonywania sp_send_dbmail bez kontekstu transakcji poczta bazy danych uruchamia i zatwierdza niejawną transakcję. Podczas wykonywania sp_send_dbmail z poziomu istniejącej transakcji poczta bazy danych korzysta z użytkownika w celu zatwierdzenia lub wycofania wszelkich zmian. Nie uruchamia transakcji wewnętrznej.

Permissions

Wykonaj uprawnienia domyślne dla sp_send_dbmail wszystkich członków roli bazy danych DatabaseMailUserRole w msdb bazie danych. Jeśli jednak użytkownik wysyłający wiadomość nie ma uprawnień do używania profilu dla żądania, sp_send_dbmail zwraca błąd i nie wysyła komunikatu.

Przykłady

A. Wysyłanie wiadomości e-mail

Ten przykład wysyła wiadomość e-mail do znajomego przy użyciu adresu myfriend@adventure-works.come-mail . Komunikat zawiera temat Automated Success Message. Treść wiadomości zawiera zdanie 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. Wysyłanie wiadomości e-mail z wynikami zapytania

Ten przykład wysyła wiadomość e-mail do znajomego przy użyciu adresu yourfriend@adventure-works.come-mail . Komunikat zawiera temat Work Order Counti wykonuje zapytanie, które pokazuje liczbę zamówień pracy z DueDate mniej niż dwa dni po 30 kwietnia 2022 r. Poczta bazy danych dołącza wynik jako plik tekstowy.

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. Wysyłanie wiadomości e-mail w formacie HTML

Ten przykład wysyła wiadomość e-mail do znajomego przy użyciu adresu yourfriend@adventure-works.come-mail . Komunikat zawiera temat Work Order Listi zawiera dokument HTML, który pokazuje zamówienia pracy z DueDate mniej niż dwa dni po 30 kwietnia 2022 r. Poczta bazy danych wysyła wiadomość w formacie 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';

Sprzężenie zwrotne

Czy ta strona była pomocna?

Last updated on 2025-10-15