sp_send_dbmail (Transact-SQL)

Şunlar için geçerlidir:SQL ServerAzure SQL Yönetilen Örneği

Belirtilen alıcılara bir e-posta iletisi gönderir. İleti bir sorgu sonuç kümesi, dosya ekleri veya her ikisini de içerebilir. Posta Veritabanı Postası kuyruğuna başarıyla yerleştirildiğinde, sp_send_dbmail iletinin sonucunu mailitem_id döndürür. Bu saklı yordam veritabanındadır msdb .

Transact-SQL söz dizimi kuralları

Sözdizimi

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'

İletinin GÖNDERİlDİĞİ profilin adı. @profile_namesysname türündedir ve varsayılan değeri .NULL @profile_name, var olan bir Veritabanı Postası profilinin adı olmalıdır. hiçbir @profile_name belirtilmediğinde, sp_send_dbmail geçerli kullanıcı için varsayılan özel profili kullanır. Kullanıcının varsayılan özel profili yoksa, sp_send_dbmail veritabanı için msdb varsayılan genel profili kullanır. Kullanıcının varsayılan özel profili yoksa ve veritabanı için varsayılan genel profil yoksa @profile_name belirtilmelidir.

[ @recipients = ] 'alıcılar'

İletinin gönder iletişim kutusuna gönderilecek e-posta adreslerinin noktalı virgülle ayrılmış listesi. Alıcı listesi varchar(max) türündedir. Bu parametre isteğe bağlı olsa da @recipients, @copy_recipients veya @blind_copy_recipients en az biri belirtilmelidir veya sp_send_dbmail bir hata döndürür.

[ @copy_recipients = ] 'copy_recipients'

İletinin kopyalandığı e-posta adreslerinin noktalı virgülle ayrılmış listesi. Alıcıları kopyala listesi varchar(max) türündedir. Bu parametre isteğe bağlı olsa da @recipients, @copy_recipients veya @blind_copy_recipients en az biri belirtilmelidir veya sp_send_dbmail bir hata döndürür.

[ @blind_copy_recipients = ] 'blind_copy_recipients'

İletiyi gizli olarak kopyalamak için noktalı virgülle ayrılmış e-posta adresleri listesi. Gizli kopya alıcı listesi varchar(max) türündedir. Bu parametre isteğe bağlı olsa da @recipients, @copy_recipients veya @blind_copy_recipients en az biri belirtilmelidir veya sp_send_dbmail bir hata döndürür.

[ @from_address = ] 'from_address'

E-posta iletisinin 'kimden adresi' değeri. Bu, posta profilindeki ayarları geçersiz kılmak için kullanılan isteğe bağlı bir parametredir. Bu parametre varchar(max) türündedir. SMTP güvenlik ayarları, bu geçersiz kılmaların kabul edilir olup olmadığını belirler. Parametre belirtilmezse, varsayılan değer olur NULL.

[ @reply_to = ] 'reply_to'

E-posta iletisinin 'yanıt adresi' değeri. Geçerli bir değer olarak yalnızca bir e-posta adresi kabul eder. Bu, posta profilindeki ayarları geçersiz kılmak için kullanılan isteğe bağlı bir parametredir. Bu parametre varchar(max) türündedir. SMTP güvenlik ayarları, bu geçersiz kılmaların kabul edilir olup olmadığını belirler. Parametre belirtilmezse, varsayılan değer olur NULL.

[ @subject = ] N'subject'

E-posta iletisinin konusu. Konu nvarchar(255) türündedir. Konu belirtilmezse, varsayılan değer 'SQL Server İletisi'dir.

[ @body = ] N'body'

E-posta iletisinin gövdesi. İleti gövdesi nvarchar(max) türündedir ve varsayılan değeri olur NULL.

[ @body_format = ] 'body_format'

İleti gövdesinin biçimi. parametresi varchar(20) türündedir ve varsayılan değeri olur NULL. Belirtildiğinde, giden iletinin üst bilgileri ileti gövdesinin belirtilen biçime sahip olduğunu gösterecek şekilde ayarlanır. parametresi aşağıdaki değerlerden birini içerebilir:

• METNEÇEVİr (varsayılan)
• HTML

[ @importance = ] 'önem'

İletinin önemi. parametresi varchar(6) türündedir. parametresi aşağıdaki değerlerden birini içerebilir:

• Low
• Normal (varsayılan)
• High

[ @sensitivity = ] 'duyarlılık'

İletinin duyarlılığı. parametresi varchar(12) türündedir. parametresi aşağıdaki değerlerden birini içerebilir:

• Normal (varsayılan)
• Personal
• Private
• Confidential

[ @file_attachments = ] N'file_attachments'

E-posta iletisine eklenecek dosya adlarının noktalı virgülle ayrılmış listesi. Listedeki dosyalar mutlak yollar olarak belirtilmelidir. Ekler listesi nvarchar(max)türündedir. Varsayılan olarak, Veritabanı Postası dosya eklerini dosya başına 1 MB ile sınırlar.

Önemli

Bu parametre, yerel dosya sistemine erişemediğinden Azure SQL Yönetilen Örneği'nde kullanılamaz.

[ @query = ] N'query'

Yürütülecek bir sorgu. Sorgunun sonuçları dosya olarak eklenebilir veya e-posta iletisinin gövdesine eklenebilir. Sorgu nvarchar(max) türündedir ve geçerli Transact-SQL deyimleri içerebilir. Sorgu ayrı bir oturumda yürütülür, bu nedenle betik çağrısındaki sp_send_dbmail yerel değişkenler sorguda kullanılamaz.

@query parametresini kullandığınızda, yürüten sp_send_dbmail sorumlunun Bir Microsoft Entra Id (eski adı Azure Active Directory) veya Windows Active Directory grubu olsun, bir grubun parçası olarak değil bir birey olarak bağlanması gerekir. SQL Server oturum açma bilgileri, Windows kimlikleri ve Microsoft Entra kimlikleri sorguyu yürütebilir, ancak Azure SQL Yönetilen Örneği kimliğe bürünme ve AS YÜRÜTME sınırlamaları nedeniyle grup üyeleri yürütemez.

[ @execute_query_database = ] 'execute_query_database'

Saklı yordamın sorguyu çalıştırdığı veritabanı bağlamı. parametresi sysname türündedir ve geçerli veritabanının varsayılanıdır. Bu parametre yalnızca @query belirtilirse geçerlidir.

[ @attach_query_result_as_file = ] attach_query_result_as_file

Sorgunun sonuç kümesinin ekli dosya olarak döndürülp döndürülmeyeceğini belirtir. @attach_query_result_as_filebit türündedir ve varsayılan değeridir 0.

değeri olduğunda 0, sorgu sonuçları, @body parametresinin içeriğinden sonra e-posta iletisinin gövdesine eklenir. değeri olduğunda 1, sonuçlar ek olarak döndürülür. Bu parametre yalnızca @query belirtilirse geçerlidir.

[ @query_attachment_filename = ] N'query_attachment_filename'

Sorgu ekinin sonuç kümesi için kullanılacak dosya adını belirtir. @query_attachment_filenamenvarchar(255) türündedir ve varsayılan değeri olur NULL. @attach_query_result_as_file olduğunda bu parametre yoksayılır 0. @attach_query_result_as_file olduğunda 1 ve bu parametre iseNULL, Veritabanı Postası rastgele bir dosya adı oluşturur.

[ @query_result_header = ] query_result_header

Sorgu sonuçlarının sütun üst bilgileri içerip içermediğini belirtir. query_result_header değeri bit türündedir. değeri olduğunda 1, sorgu sonuçları sütun başlıkları içerir. değeri olduğunda 0, sorgu sonuçları sütun üst bilgilerini içermez. Bu parametre varsayılan olarak olarak gösterilir 1. Bu parametre yalnızca @query belirtilirse geçerlidir.

@query_result_header olarak ayarlanırken ve @query_no_truncate0olarak ayarlanırken 1aşağıdaki hata oluşabilir:

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

[ @query_result_width = ] query_result_width

Sorgunun sonuçlarını biçimlendirmek için kullanılacak karakter cinsinden çizgi genişliği. @query_result_width, varsayılan değeri olan int türündedir256. Sağlanan değer ile 32767arasında 10 olmalıdır. Bu parametre yalnızca @query belirtilirse geçerlidir.

[ @query_result_separator = ] 'query_result_separator'

Sorgu çıkışındaki sütunları ayırmak için kullanılan karakter. Ayırıcı char(1) türündedir. Varsayılan olarak ' ' (boşluk) kullanılır.

[ @exclude_query_output = ] exclude_query_output

E-posta iletisinde sorgu yürütme çıktısının döndürülüp döndürülmeyeceğini belirtir. @exclude_query_outputbittir ve varsayılan değeridir 0. Bu parametre olduğunda 0saklı yordamın sp_send_dbmail yürütülmesi, konsolda sorgu yürütmesinin sonucu olarak döndürülen iletiyi yazdırır. Bu parametre olduğunda 1saklı yordamın sp_send_dbmail yürütülmesi konsoldaki sorgu yürütme iletilerinin hiçbirini yazdırmaz.

[ @append_query_error = ] append_query_error

@query bağımsız değişkeninde belirtilen sorgudan bir hata döndürdüğünde e-posta gönderilip gönderilmeymeyeceğini belirtir. @append_query_errorbittir ve varsayılan değeridir 0. Bu parametre olduğunda 1, Veritabanı Postası e-posta iletisini gönderir ve e-posta iletisinin gövdesine sorgu hata iletisini ekler. Bu parametre olduğunda 0, Veritabanı Postası e-posta iletisini göndermez ve sp_send_dbmail hata olduğunu belirten dönüş koduyla 1biter.

[ @query_no_truncate = ] query_no_truncate

Sorgunun büyük değişken uzunluklu veri türlerinin (varchar(max), nvarchar(max), varbinary(max), xml, metin, ntext, görüntü ve kullanıcı tanımlı veri türlerinin kesilmesini önleyen seçenekle yürütülip yürütülmeyeceğini belirtir. Ayarlandığında, sorgu sonuçları sütun üst bilgilerini içermez. @query_no_truncate değeri bit türündedir. Değer 0 belirtildiğinde veya belirtilmediğinde, sorgudaki sütunlar 256 karaktere kadar kesilir. değeri olduğunda 1, sorgudaki sütunlar kesilmez. Bu parametre varsayılan olarak olarak gösterilir 0.

Uyarı

@query_no_truncate seçeneği büyük miktarda veriyle kullanıldığında ek kaynaklar kullanır ve sunucu performansını yavaşlatabilir.

[ @query_result_no_padding = ] query_result_no_padding

Türü bittir. Varsayılan değer: 0. olarak 1ayarladığınızda, sorgu sonuçları doldurulmayarak büyük olasılıkla dosya boyutunu küçültür. olarak ayarlarsanız @query_result_no_padding1 ve @query_result_width parametresini ayarlarsanız , @query_result_no_padding parametresi @query_result_width parametresinin üzerine yazar.

Bu durumda hata oluşmaz.

@query_result_no_padding ayarlanırken ve @query_no_truncate1için bir parametre sağlanırken aşağıdaki hata oluşabilir:

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.

@query_result_no_padding1 ve @query_no_truncate parametresini ayarlarsanız bir hata oluşur.

[ @mailitem_id = ] mailitem_id [ OUTPUT ]

İsteğe bağlı çıkış parametresi iletinin değerini döndürür mailitem_id . @mailitem_idint türündedir.

Dönüş kodu değerleri

dönüş kodu 0 başarılı anlamına gelir. Diğer herhangi bir değer hata anlamına gelir. Başarısız olan deyiminin hata kodu değişkeninde @@ERROR depolanır.

Sonuç kümesi

Başarılı olduğunda, "Posta kuyruğa alındı" iletisini döndürür.

Açıklamalar

Kullanmadan önce Veritabanı Postası, Veritabanı Posta Yapılandırma Sihirbazı veya sp_configurekullanılarak etkinleştirilmelidir.

sysmail_stop_sp dış programın kullandığı Hizmet Aracısı nesnelerini durdurarak Veritabanı Postası'nı durdurur. sp_send_dbmail Veritabanı Postası kullanılarak sysmail_stop_spdurdurulduğunda hala postayı kabul eder. Veritabanı Postası'na başlamak için kullanın sysmail_start_sp.

@profile belirtilmediğinde varsayılan sp_send_dbmail bir profil kullanır. E-posta iletisini gönderen kullanıcının varsayılan özel profili varsa, Veritabanı Postası bu profili kullanır. Kullanıcının varsayılan özel profili yoksa, sp_send_dbmail varsayılan genel profili kullanır. Kullanıcı için varsayılan özel profil yoksa ve varsayılan genel profil yoksa, sp_send_dbmail bir hata döndürür.

sp_send_dbmail içeriği olmayan e-posta iletilerini desteklemez. E-posta iletisi göndermek için @body, @query, @file_attachmentsveya@subject en az birini belirtmeniz gerekir. Aksi takdirde bir sp_send_dbmail hata döndürür.

Veritabanı Postası, SQL Server için hizmet hesabının güvenlik bağlamında çalışır. Bu nedenle, SQL Server kimlik doğrulamasıyla kimlik doğrulaması yapılan kullanıcılar @file_attachments kullanarak dosya ekleyemez. Windows, SQL Server'ın uzak bir bilgisayardan başka bir uzak bilgisayara kimlik bilgileri sağlamasına izin vermez. Bu nedenle Veritabanı Postası, komutun SQL Server'ın üzerinde çalıştığı bilgisayardan başka bir bilgisayardan çalıştırıldığı durumlarda ağ paylaşımından dosya ekleyemeyebilir.

Hem @query hem de @file_attachments belirtilirse ve dosya bulunamazsa, sorgu yine yürütülür ancak e-posta gönderilmez.

Sorgu belirtildiğinde sonuç kümesi satır içi metin olarak biçimlendirilir. Sonuçtaki ikili veriler onaltılık biçimde gönderilir.

@recipients, @copy_recipients ve @blind_copy_recipients parametreleri, e-posta adreslerinin noktalı virgülle ayrılmış listeleridir. Bu parametrelerden en az biri sağlanmalıdır veya sp_send_dbmail bir hata döndürür.

İşlem bağlamı olmadan yürütülürken sp_send_dbmail , Veritabanı Postası başlar ve örtük bir işlem işler. Veritabanı Postası, mevcut bir işlemin içinden yürütürken sp_send_dbmail , kullanıcının değişiklikleri işlemesine veya geri almasına dayanır. bir iç işlem başlatmaz.

Permissions

Veritabanındaki DatabaseMailUserRole veritabanı rolünün tüm üyeleri için sp_send_dbmail varsayılan olarak izinleri yürütürmsdb. Ancak, iletiyi gönderen kullanıcının istek için profili kullanma izni olmadığında bir sp_send_dbmail hata döndürür ve iletiyi göndermez.

Örnekler

A. E-posta iletisi gönderme

Bu örnek, e-posta adresini myfriend@adventure-works.comkullanarak arkadaşınıza bir e-posta iletisi gönderir. İletinin konusu Automated Success Messagevardır. İletinin gövdesi tümcesini The stored procedure finished successfullyiçerir.

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. Sorgunun sonuçlarını içeren bir e-posta iletisi gönderme

Bu örnek, e-posta adresini yourfriend@adventure-works.comkullanarak arkadaşınıza bir e-posta iletisi gönderir. İletinin konusu Work Order Countvardır ve 30 Nisan 2022'den sonra iki günden az iş emri sayısını gösteren bir DueDate sorgu yürütür. Veritabanı Postası sonucu bir metin dosyası olarak ekler.

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. HTML e-posta iletisi gönderme

Bu örnek, e-posta adresini yourfriend@adventure-works.comkullanarak arkadaşınıza bir e-posta iletisi gönderir. İletinin konusu Work Order Listvardır ve 30 Nisan 2022'den sonra iki günden az bir süreyle iş siparişlerini gösteren bir DueDate HTML belgesi içerir. Veritabanı Postası iletiyi HTML biçiminde gönderir.

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

İlgili içerik

• Veritabanı Postası
• Veritabanı Posta Yapılandırma Nesneleri
• Veritabanı Posta saklı yordamları (Transact-SQL)
• Veritabanı Postası dış programı
• sp_addrolemember (Transact-SQL)