sp_send_dbmail (Transact-SQL)

Belirtilen alıcılara e-posta iletisi gönderir. İleti bir sorgu sonuç kümesini, dosya eklerini veya her ikisini içerebilir. Posta başarıyla Database Mail sırasına yerleştirildiğinde, sp_send_dbmail iletinin mailitem_id değerini döndürür. Bu saklı yordam msdb veritabanındadır.

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

Bağımsız değişkenler

• [ @profil_adı= ] 'profile_name'
  İletinin gönderileceği profilin adıdır. profile_name sysname türündedir ve varsayılan değeri NULL'dır. profile_name var olan bir Database Mail profilinin adı olmalıdır. Hiçbir profile_name belirtilmediğinde, sp_send_dbmail geçerli kullanıcının varsayılan özel profilini kullanır. Kullanıcının varsayılan bir özel profili yoksa, sp_send_dbmail, msdb veritabanı için varsayılan genel profili kullanır. Kullanıcının varsayılan özel bir profili yoksa ve veritabanının varsayılan genel bir profili yoksa, @profile_name belirtilmelidir.

• [ @recipients= ] 'recipients'
  İletinin gönderileceği e-posta adreslerinin noktalı virgülle ayrılmış listesidir. Alıcı listesi varchar(max) türündedir. Bu parametre isteğe bağlı olmakla birlikte, en az bir @recipients, @copy_recipients veya @blind_copy_recipients belirtilmelidir; aksi halde sp_send_dbmail bir hata döndürür.

• [ @copy_recipients= ] 'copy_recipients'
  İletiyi kopya olarak göndermek için noktalı virgülle ayrılmış bir e-posta adres listesidir. Kopya alıcıları listesi varchar(max) türündedir. Bu parametre isteğe bağlı olmakla birlikte en az bir @recipients, @copy_recipients veya @blind_copy_recipients belirtilmelidir; aksi halde sp_send_dbmail bir hata döndürür.

• [ @blind_copy_recipients= ] 'blind_copy_recipients'
  İletiyi gizli kopya olarak göndermek için noktalı virgülle ayrılmış bir e-posta adres listesidir. Gizli kopya alıcıları listesi varchar(max) türündedir. Bu parametre seçeneğe bağlı olmakla birlikte, en az bir @recipients, @copy_recipients veya @blind_copy_recipients belirtilmelidir; aksi halde sp_send_dbmail bir hata döndürür.

• [ @from_address= ] 'from_address'
  E-posta iletisinin 'geldiği adres' değeridir. Bu, posta profilindeki ayarları etkisiz kılmak için kullanılan isteğe bağlı bir parametredir. Bu parametre varchar(MAX) türündedir. Bu geçersiz kılmaların kabul edilip edilmeyeceğini SMTP güvenlik ayarları belirler. Hiçbir parametre belirtilmezse, varsayılan değer NULL'dır.

• [ @reply_to= ] 'reply_to'
  E-posta iletisinin 'yanıtlama adresi' değeridir. Geçerli değer olarak yalnızca bir e-posta adresini kabul eder. Bu, posta profilindeki ayarları etkisiz kılmak için kullanılan isteğe bağlı bir parametredir. Bu parametre varchar(MAX) türündedir. Bu geçersiz kılmaların kabul edilip edilmeyeceğini SMTP güvenlik ayarları belirler. Hiçbir parametre belirtilmezse, varsayılan değer NULL'dır.

• [ @subject= ] 'subject'
  E-posta iletisinin konusudur. Konu nvarchar(255) türündedir. Hiçbir konu belirtilmezse, varsayılan değer 'SQL Server İletisi'dir.

• [ @body= ] 'body'
  E-posta iletisinin gövdesidir. İleti gövdesi nvarchar(max) türündedir ve varsayılan değeri NULL'dır.

• [ @body_format= ] 'body_format'
  İleti gövdesinin biçimidir. Parametre varchar(20) türündedir ve varsayılan değeri NULL'dır. Belirtildiğinde giden iletilerin üstbilgisi ileti gövdesinin belirtilen biçimde olduğunu gösterecek şekilde ayarlanır. Parametre aşağıdaki değerlerden birini içerebilir:

  • TEXT

  • HTML

  Varsayılan değeri TEXT'tir.

• [ @importance= ] 'importance'
  İleti gövdesinin önem derecesidir. Parametre varchar(6) türündedir. Parametre aşağıdaki değerlerden birini içerebilir:

  • Düşük

  • Normal

  • Yüksek

  Varsayılan değeri Normal'dir.

• [ @sensitivity= ] 'sensitivity'
  İletinin hassaslık derecesidir. Parametre varchar(12) türündedir. Parametre aşağıdaki değerlerden birini içerebilir:

  • Normal

  • Kişisel

  • Özel

  • Gizli

  Varsayılan değeri Normal'dir.

• [ @file_attachments= ] 'file_attachments'
  İletiye eklenecek dosyaların noktalı virgülle ayrılmış bir listesidir. Listedeki dosyalar mutlak yol olarak belirtilmelidir Ek listesi nvarchar(max) türündedir. Varsayılan olarak Database Mail dosya eklerini dosya başına 1 MB ile sınırlar.

• [ @query= ] 'query'
  Yürütülecek bir sorgudur. Sorgunun sonuçları bir dosya olarak eklenebilir veya e-posta iletisinin gövdesine dahil edilebilir. Sorgu nvarchar(max) türündedir ve herhangi bir geçerli Transact-SQL deyimini içerebilir. Sorgunun ayrı bir oturumda yürütüldüğüne, dolayısıyla komut dizisindeki sp_send_dbmail'i çağıran yerel değişkenlerin sorguda kullanılamayacağına dikkat edin.

• [ @execute_query_database= ] 'execute_query_database'
  Saklı yordamın sorguyu çalıştırdığı veritabanı bağlamıdır. Parametre sysname türündedir ve varsayılan değeri geçerli veritabanıdır. Bu parametre yalnızca @query belirtilirse uygulanır.

• [ @attach_query_result_as_file= ] attach_query_result_as_file
  Sorgu kümesinin ek bir dosya olarak döndürülüp döndürülmeyeceğini belirtir. attach_query_result_as_file bit türündedir ve varsayılan değeri 0'dır.

  Değeri 0 olduğunda, sorgu sonuçları e-posta iletisinin gövdesine, @body parametresinin içeriğinin ardına eklenir. Değeri 1 olduğunda, sonuçlar bir ek olarak döndürülür. Bu parametre yalnızca @query belirtilirse uygulanır.

• [ @query_attachment_filename= ] query_attachment_filename
  Sorgu ekinin sonuç kümesinin kullanacağı dosya adını belirtir. query_attachment_filename, nvarchar(255) türündedir ve varsayılan değeri NULL'dır. Bu parametre attach_query_result 0 olduğunda yoksayılır. attach_query_result 1 ve bu parametre NULL olduğunda, Database Mail rastgele bir dosya adı oluşturur.

• [ @query_result_header= ] query_result_header
  Sorgu sonuçlarının sütun üstbilgisi içerip içermeyeceğini belirtir. query_result_header değeri bit türündedir. Değer 1 olduğunda, sorgu sonuçları sütun üstbilgileri içerir. Değer 0 olduğunda, sorgu sonuçları sütun üstbilgileri içermez. Bu parametrenin varsayılan değeri 1'dir. Bu parametre yalnızca @query belirtilirse uygulanır.

• [ @query_result_width = ] query_result_width
  Sorgunun sonuçlarının biçimlendirmek için kullanılan, karakter olarak satır genişliğidir. query_result_width, int türündedir ve varsayılan değeri 256'dır. Sağlanan değer 10 ile 32767 arasında olmalıdır. Bu parametre yalnızca @query belirtilirse uygulanır.

• [ @query_result_separator= ] 'query_result_separator'
  Sorgu çıktısında sütunları ayırmak için kullanılan karakterdir. Ayırıcı char(1) türündedir. Varsayılan değer ' ' (boşluk) karakteridir.

• [ @exclude_query_output= ] exclude_query_output
  Yürütülen sorgunun çıktısının e-posta iletisinde döndürülüp döndürülemeyeceğini belirtir. exclude_query_output bit türündedir ve varsayılan değeri 0'dır. Parametre 0 olduğunda sp_send_dbmail saklı yordamının yürütülmesi, yürütülen sorgunun sonucu olarak döndürülen iletiyi konsola yazar. Parametre 1 olduğunda, sp_send_dbmail saklı yordamının yürütülmesi sorgu yürütme iletilerinin hiçbirini konsola yazmaz.

• [ @append_query_error= ] append_query_error
  @query değişkeninde belirtilen sorgudan bir hata döndüğünde e-postanın gönderilip gönderilmeyeceğini belirtir. append_query_error bit türündedir ve varsayılan değeri 0'dır. Bu parametre 1 olduğunda, Database Mail e-posta iletisini gönderir ve sorgu hata iletisini e-posta iletisinin gövdesine ekler. Bu parametre 0 olduğunda, Database Mail e-posta iletisini göndermez ve sp_send_dbmail, hata durumunu gösteren 1 kodu ile sona erer.

• [ @query_no_truncate= ] query_no_truncate
  Sorgunun büyük, değişken uzunlukta veri türlerinin (varchar(max), nvarchar(max), varbinary(max), xml, text, ntext, image ve kullanıcı tarafından tanımlanmış veri türleri) kısaltılmasını önleyen seçenekle yürütülüp yürütülmeyeceğini belirtir. Ayarlandığında, sorgu sonuçları sütun üstbilgileri içermez. query_no_truncate değeri bit türündedir. Değer 0 olduğunda veya belirtilmediğinde, sorgudaki sütunlar 256 karaktere kısaltılır. Değer 1 olduğunda, sorgudaki sütunlar kısaltılmaz. Bu parametrenin varsayılan değeri 0'dir.

  [!NOT]

  Büyük miktarda veriyle kullanıldığında, @query_no_truncate seçeneği ek kaynak tüketir ve sunucu performansını düşürebilir.

• [ @query_result_no_padding ] @query\_result\_no\_padding
  Türü bittir. Varsayılan değeri 0'dır. Değerini 1 olarak ayarladığınızda, sorgu sonuçlarına dolgu uygulanmaz; dosya boyutu olasılıkla küçülür.@query\_result\_no\_padding değerini 1 yapar ve @query\_result\_width parametresini ayarlarsanız, @query\_result\_no\_padding parametresi @query\_result\_width parametresinin üzerine yazar.

  Bu durumda hiçbir hata oluşmaz.

  @query\_result\_no\_padding değerini 1 yapar ve @query\_no\_truncate parametresini ayarlarsanız, bir hata oluşur.

• [ @mailitem_id= ] mailitem_id [ OUTPUT ]
  İsteğe bağlı çıktı parametresi iletinin mailitem_id değerini döndürür. mailitem_id int türündedir.

Dönüş Kodu Değerleri

Dönüş kodu olarak 0 başarı anlamına gelir. Diğer tüm değerler hata anlamına gelir. Deyimin hata kodu @@ERRROR değişkeninde depolanır.

Sonuç Kümeleri

Başarı durumunda "Posta sıraya alındı" iletisi döndürülür.

Açıklamalar

Kullanımdan önce Database Mail, Database Mail Yapılandırma Sihirbazı veya sp_configure ile etkinleştirilmelidir.

sysmail_stop_sp Database Mail'i harici programın kullandığı Hizmet Aracısı nesnelerini durdurarak durdurur. sp_send_dbmail, Database Mail sysmail_stop_sp kullanılarak durdurulduğunda posta kabul etmeye devam eder. Database Mail'i başlatmak için sysmail_start_sp yordamını kullanın.

@profile belirtilmediğinde, sp_send_dbmail varsayılan bir profili kullanır. E-posta iletisini gönderen kullanıcının varsayılan bir özel profili varsa, Database Mail o profili kullanır. Kullanıcının varsayılan bir özel profili yoksa, sp_send_dbmail varsayılan genel profili kullanır. Kullanıcının varsayılan özel bir profili ve varsayılan genel bir profil yoksa, sp_send_dbmail 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_attachments veya @subject alanlarından en az birini belirtmelisiniz. Aksi halde sp_send_dbmail bir hata döndürür.

Database Mail, dosyalara erişimi denetlemek için geçerli kullanıcının Microsoft Windows güvenlik bağlamını kullanır. Dolayısıyla SQL Server Kimlik Doğrulaması ile kimlik doğrulayan 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. Dolayısıyla Database Mail, komutun SQL Server'ın çalıştığı bilgisayardan farklı bir bilgisayarda çalıştırıldığı durumlarda bir ağ paylaşımından dosya ekleyemeyebilir.

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

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

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

sp_send_dbmail yordamı bir işlem bağlamı olmadan yürütüldüğünde, Database Mail örtülü bir işlem başlatır ve yürütür. sp_send_dbmail yordamı bir işlemin içinden yürütüldüğünde, Database Mail, yapılan değişikliklerin kullanıcı tarafından yürütülmesini veya geri alınmasını bekler. Bir iç işlem başlatmaz.

İzinler

sp_send_dbmail yürütme izinleri, varsayılan olarak msdb veritabanındaki DatabaseMailUser veritabanı rolünün tüm üyelerine verilir. Ancak, iletiyi gönderen kullanıcı istek için profili kullanma iznine sahip olmadığında, sp_send_dbmail bir hata döndürür ve ileti göndermez.

Örnekler

A.E-posta iletisi gönderme

Bu örnek, danw@Adventure-Works.com adresini kullanarak Dan Wilson'a bir e-posta iletisi göndermektedir. İletinin konusu Automated Success Message metnidir. İletinin gövdesinde 'The stored procedure finished successfully' tümcesi bulunmaktadır.

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

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

B.Bir sorgunun sonuçlarıyla bir e-posta iletisi gönderme

Bu örnek, danw@Adventure-Works.com adresini kullanarak Dan Wilson'a bir e-posta iletisi göndermektedir. İletinin konusu Work Order Count ifadesidir ve 30 Nisan 2004'ten sonra en çok iki gün içinde DueDate gelen iş emirlerinin sayısını gösteren bir sorguyu yürütmektedir. Database Mail sonucu bir metin dosyası olarak eklemektedir.

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

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

C.HTML e-posta iletisi gönderme

Bu örnek, danw@Adventure-Works.com adresini kullanarak Dan Wilson'a bir e-posta iletisi göndermektedir. İletinin konusu Work Order List ifadesidir ve 30 Nisan 2004'ten sonra en çok iki gün içinde DueDate gelen iş emirlerini gösteren bir HTML belgesi içermektedir. Database Mail 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
              JOIN AdventureWorks.Production.Product AS p
              ON wo.ProductID = p.ProductID
              WHERE DueDate > '2004-04-30'
                AND DATEDIFF(dd, '2004-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='danw@Adventure-Works.com',
    @subject = 'Work Order List',
    @body = @tableHTML,
    @body_format = '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
              JOIN AdventureWorks.Production.Product AS p
              ON wo.ProductID = p.ProductID
              WHERE DueDate > '2004-04-30'
                AND DATEDIFF(dd, '2004-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='danw@Adventure-Works.com',
    @subject = 'Work Order List',
    @body = @tableHTML,
    @body_format = 'HTML' ;

Ayrıca bkz.

Başvuru

Veritabanı posta depolanan yordamlar (Transact-sql)

sp_addrolemember (Transact-sql)

Kavramlar

Veritabanı posta

Veritabanı posta yapılandırma nesneleri