sp_send_dbmail (T-SQL)

Artikel
11/02/2023

Berlaku untuk:SQL Server Azure SQL Managed Instance

Mengirim pesan email ke penerima yang ditentukan. Pesan mungkin menyertakan kumpulan hasil kueri, lampiran file, atau keduanya. Ketika email berhasil ditempatkan dalam antrean Email Database, sp_send_dbmail mengembalikan mailitem_id pesan. Prosedur tersimpan ini ada di msdb database.

Konvensi sintaks transact-SQL

Sintaks

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

Argumen

[ @profile_name = ] 'profile_name'

Nama profil untuk mengirim pesan. @profile_name berjenis sysname, dengan default NULL. @profile_name harus berupa nama profil Email Database yang sudah ada. Ketika tidak ada @profile_name yang ditentukan, sp_send_dbmail menggunakan profil privat default untuk pengguna saat ini. Jika pengguna tidak memiliki profil privat default, sp_send_dbmail menggunakan profil publik default untuk msdb database. Jika pengguna tidak memiliki profil privat default dan tidak ada profil publik default untuk database, @profile_name harus ditentukan.

[ @recipients = ] 'penerima'

Daftar alamat email yang dibatasi titik koma untuk mengirim pesan. Daftar penerima berjenis varchar(max). Meskipun parameter ini bersifat opsional, setidaknya salah satu @recipients, @copy_recipients, atau @blind_copy_recipients harus ditentukan, atau sp_send_dbmail mengembalikan kesalahan.

[ @copy_recipients = ] 'copy_recipients'

Daftar alamat email yang dibatasi titik koma untuk menyalin pesan ke karbon. Daftar penerima salinan berjenis varchar(max). Meskipun parameter ini bersifat opsional, setidaknya salah satu @recipients, @copy_recipients, atau @blind_copy_recipients harus ditentukan, atau sp_send_dbmail mengembalikan kesalahan.

[ @blind_copy_recipients = ] 'blind_copy_recipients'

Daftar alamat email yang dibatasi titik koma untuk menyalin pesan buta karbon. Daftar penerima salinan buta berjenis varchar(max). Meskipun parameter ini bersifat opsional, setidaknya salah satu @recipients, @copy_recipients, atau @blind_copy_recipients harus ditentukan, atau sp_send_dbmail mengembalikan kesalahan.

[ @from_address = ] 'from_address'

Nilai 'dari alamat' pesan email. Ini adalah parameter opsional yang digunakan untuk mengambil alih pengaturan di profil email. Parameter ini berjenis varchar(max). Pengaturan keamanan SMTP menentukan apakah penimpaan ini diterima. Jika tidak ada parameter yang ditentukan, defaultnya adalah NULL.

[ @reply_to = ] 'reply_to'

Nilai 'balas ke alamat' pesan email. Ini hanya menerima satu alamat email sebagai nilai yang valid. Ini adalah parameter opsional yang digunakan untuk mengambil alih pengaturan di profil email. Parameter ini berjenis varchar(max). Pengaturan keamanan SMTP menentukan apakah penimpaan ini diterima. Jika tidak ada parameter yang ditentukan, defaultnya adalah NULL.

[ @subject = ] N'subject'

Subjek pesan email. Subjek berjenis nvarchar(255). Jika tidak ada subjek yang ditentukan, defaultnya adalah 'Pesan SQL Server'.

[ @body = ] N'body'

Isi pesan email. Isi pesan berjenis nvarchar(max), dengan default NULL.

[ @body_format = ] 'body_format'

Format isi pesan. Parameter berjenis varchar(20), dengan default NULL. Ketika ditentukan, header pesan keluar diatur untuk menunjukkan bahwa isi pesan memiliki format yang ditentukan. Parameter mungkin berisi salah satu nilai berikut:

TEXT (default)
HTML

[ @importance = ] 'kepentingan'

Pentingnya pesan. Parameternya berjenis varchar(6). Parameter mungkin berisi salah satu nilai berikut:

Low
Normal (default)
High

[ @sensitivity = ] 'sensitivitas'

Sensitivitas pesan. Parameternya berjenis varchar(12). Parameter mungkin berisi salah satu nilai berikut:

Normal (default)
Personal
Private
Confidential

[ @file_attachments = ] N'file_attachments'

Daftar nama file yang dibatasi titik koma untuk dilampirkan ke pesan email. File dalam daftar harus ditentukan sebagai jalur absolut. Daftar lampiran berjenis nvarchar(max). Secara default, Email Database membatasi lampiran file menjadi 1 MB per file.

Penting

Parameter ini tidak tersedia di Azure SQL Managed Instance, karena tidak dapat mengakses sistem file lokal.

[ @query = ] N'query'

Kueri yang akan dijalankan. Hasil kueri dapat dilampirkan sebagai file, atau disertakan dalam isi pesan email. Kueri berjenis nvarchar(max), dan dapat berisi pernyataan Transact-SQL yang valid. Kueri dijalankan dalam sesi terpisah, sehingga variabel lokal dalam panggilan sp_send_dbmail skrip tidak tersedia untuk kueri.

Saat Anda menggunakan parameter @query , prinsipal yang dijalankan harus dihubungkan sp_send_dbmail sebagai individu, bukan sebagai bagian dari grup, baik ID Microsoft Entra (sebelumnya Azure Active Directory) atau grup Windows Active Directory. Login SQL Server, identitas Windows, dan identitas Microsoft Entra dapat menjalankan kueri, tetapi anggota grup tidak dapat, karena peniruan Azure SQL Managed Instance dan batasan EXECUTE AS.

[ @execute_query_database = ] 'execute_query_database'

Konteks database tempat prosedur tersimpan menjalankan kueri. Parameter berjenis sysname, dengan default database saat ini. Parameter ini hanya berlaku jika @query ditentukan.

[ @attach_query_result_as_file = ] attach_query_result_as_file

Menentukan apakah kumpulan hasil kueri dikembalikan sebagai file terlampir. @attach_query_result_as_file berjenis bit, dengan default 0.

Saat nilainya adalah 0, hasil kueri disertakan dalam isi pesan email, setelah konten parameter @body . Ketika nilainya adalah 1, hasilnya dikembalikan sebagai lampiran. Parameter ini hanya berlaku jika @query ditentukan.

[ @query_attachment_filename = ] N'query_attachment_filename'

Menentukan nama file yang akan digunakan untuk kumpulan hasil lampiran kueri. @query_attachment_filename berjenis nvarchar(255), dengan default NULL. Parameter ini diabaikan ketika @attach_query_result_as_file adalah 0. Ketika @attach_query_result_as_file dan 1 parameter ini adalah NULL, Database Mail membuat nama file arbitrer.

[ @query_result_header = ] query_result_header

Menentukan apakah hasil kueri menyertakan header kolom. Nilai query_result_header berjenis bit. Saat nilainya adalah 1, hasil kueri berisi header kolom. Saat nilainya adalah 0, hasil kueri tidak menyertakan header kolom. Parameter ini default ke 1. Parameter ini hanya berlaku jika @query ditentukan.

Kesalahan berikut mungkin terjadi saat mengatur @query_result_header ke 0 dan mengatur @query_no_truncate ke 1:

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

[ @query_result_width = ] query_result_width

Lebar garis, dalam karakter, untuk digunakan untuk memformat hasil kueri. @query_result_width berjenis int, dengan default 256. Nilai yang disediakan harus antara 10 dan 32767. Parameter ini hanya berlaku jika @query ditentukan.

[ @query_result_separator = ] 'query_result_separator'

Karakter yang digunakan untuk memisahkan kolom dalam output kueri. Pemisah berjenis karakter(1). Default ke ' ' (spasi).

[ @exclude_query_output = ] exclude_query_output

Menentukan apakah akan mengembalikan output eksekusi kueri dalam pesan email. @exclude_query_output adalah bit, dengan default .0 Ketika parameter ini adalah 0, eksekusi prosedur tersimpan sp_send_dbmail mencetak pesan yang dikembalikan sebagai hasil dari eksekusi kueri di konsol. Ketika parameter ini adalah 1, eksekusi prosedur tersimpan sp_send_dbmail tidak mencetak salah satu pesan eksekusi kueri di konsol.

[ @append_query_error = ] append_query_error

Menentukan apakah akan mengirim email saat kesalahan kembali dari kueri yang ditentukan dalam argumen @query . @append_query_error adalah bit, dengan default 0. Ketika parameter ini adalah 1, Email Database mengirim pesan email dan menyertakan pesan kesalahan kueri dalam isi pesan email. Ketika parameter ini adalah 0, Email Database tidak mengirim pesan email, dan sp_send_dbmail diakhapi dengan kode 1pengembalian , menunjukkan kegagalan.

[ @query_no_truncate = ] query_no_truncate

Menentukan apakah akan menjalankan kueri dengan opsi yang menghindari pemotongan jenis data panjang variabel besar (varchar(max), nvarchar(max), varbinary(max), xml, teks, ntext, gambar, dan jenis data yang ditentukan pengguna). Saat diatur, hasil kueri tidak menyertakan header kolom. Nilai @query_no_truncate berjenis bit. Saat nilai ditentukan 0 atau tidak ditentukan, kolom dalam kueri terpotong menjadi 256 karakter. Saat nilainya adalah 1, kolom dalam kueri tidak terpotong. Parameter ini default ke 0.

Catatan

Saat digunakan dengan data dalam jumlah besar, opsi @query_no_truncate menggunakan sumber daya tambahan dan dapat memperlambat performa server.

[ @query_result_no_padding = ] query_result_no_padding

Jenisnya adalah bit. Default adalah 0. Saat Anda mengatur ke 1, hasil kueri tidak diisi, mungkin mengurangi ukuran file. Jika Anda mengatur @query_result_no_padding ke 1 dan Anda mengatur parameter @query_result_width , parameter @query_result_no_padding menimpa parameter @query_result_width .

Dalam hal ini, tidak ada kesalahan yang terjadi.

Kesalahan berikut mungkin terjadi saat mengatur @query_result_no_padding ke 1 dan menyediakan parameter untuk @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.

Jika Anda mengatur @query_result_no_padding ke 1 dan Anda mengatur parameter @query_no_truncate , kesalahan akan muncul.

[ @mailitem_id = ] mailitem_id [ OUTPUT ]

Parameter output opsional mengembalikan mailitem_id pesan. @mailitem_id berjenis int.

Mengembalikan nilai kode

Kode pengembalian berarti 0 berhasil. Nilai lain berarti kegagalan. Kode kesalahan untuk pernyataan yang gagal disimpan dalam @@ERROR variabel.

Tataan hasil

Setelah berhasil, mengembalikan pesan "Mail queued."

Keterangan

Sebelum digunakan, Email Database harus diaktifkan menggunakan Wizard Konfigurasi Email Database, atau sp_configure.

sysmail_stop_sp menghentikan Email Database dengan menghentikan objek Service Broker yang digunakan program eksternal. sp_send_dbmail masih menerima email ketika Email Database dihentikan menggunakan sysmail_stop_sp. Untuk memulai Email Database, gunakan sysmail_start_sp.

Saat @profile tidak ditentukan, sp_send_dbmail menggunakan profil default. Jika pengguna yang mengirim pesan email memiliki profil privat default, Database Mail menggunakan profil tersebut. Jika pengguna tidak memiliki profil privat default, sp_send_dbmail gunakan profil publik default. Jika tidak ada profil privat default untuk pengguna dan tidak ada profil publik default, sp_send_dbmail mengembalikan kesalahan.

sp_send_dbmail tidak mendukung pesan email tanpa isi. Untuk mengirim pesan email, Anda harus menentukan setidaknya salah satu @body, @query, @file_attachments, atau @subject. Jika tidak, sp_send_dbmail mengembalikan kesalahan.

Email Database menggunakan konteks keamanan Microsoft Windows dari pengguna saat ini untuk mengontrol akses ke file. Oleh karena itu, pengguna yang diautentikasi dengan Autentikasi SQL Server tidak dapat melampirkan file menggunakan @file_attachments. Windows tidak memperbolehkan SQL Server menyediakan kredensial dari komputer jarak jauh ke komputer jarak jauh lainnya. Oleh karena itu, Email Database mungkin tidak dapat melampirkan file dari berbagi jaringan jika perintah dijalankan dari komputer selain komputer tempat SQL Server dijalankan.

Jika @query dan @file_attachments ditentukan dan file tidak dapat ditemukan, kueri masih dijalankan tetapi email tidak dikirim.

Saat kueri ditentukan, kumpulan hasil diformat sebagai teks sebaris. Data biner dalam hasil dikirim dalam format heksadesimal.

Parameter @recipients, @copy_recipients, dan @blind_copy_recipients adalah daftar alamat email yang dibatasi titik koma. Setidaknya salah satu parameter ini harus disediakan, atau sp_send_dbmail mengembalikan kesalahan.

Saat menjalankan sp_send_dbmail tanpa konteks transaksi, Database Mail memulai dan melakukan transaksi implisit. Saat menjalankan sp_send_dbmail dari dalam transaksi yang ada, Database Mail mengandalkan pengguna untuk menerapkan atau mengembalikan perubahan apa pun. Ini tidak memulai transaksi dalam.

Izin

Jalankan izin untuk sp_send_dbmail default ke semua anggota peran database DatabaseMailUser dalam msdb database. Namun, ketika pengguna yang mengirim pesan tidak memiliki izin untuk menggunakan profil untuk permintaan, sp_send_dbmail mengembalikan kesalahan dan tidak mengirim pesan.

Contoh

J. Mengirim pesan email

Contoh ini mengirim pesan email ke teman Anda menggunakan alamat myfriend@adventure-works.comemail . Pesan memiliki subjek Automated Success Message. Isi pesan berisi kalimat 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. Mengirim pesan email dengan hasil kueri

Contoh ini mengirim pesan email ke teman Anda menggunakan alamat yourfriend@adventure-works.comemail . Pesan memiliki subjek Work Order Count, dan menjalankan kueri yang memperlihatkan jumlah perintah kerja dengan DueDate kurang dari dua hari setelah 30 April 2022. Email Database melampirkan hasil sebagai file teks.

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. Mengirim pesan email HTML

Contoh ini mengirim pesan email ke teman Anda menggunakan alamat yourfriend@adventure-works.comemail . Pesan memiliki subjek Work Order List, dan berisi dokumen HTML yang menunjukkan perintah kerja dengan DueDate kurang dari dua hari setelah 30 April 2022. Email Database mengirimkan pesan dalam 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
            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';

sp_send_dbmail (T-SQL)

Sintaks

Argumen

[ @profile_name = ] 'profile_name'

[ @recipients = ] 'penerima'

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

[ @sensitivity = ] 'sensitivitas'

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

Mengembalikan nilai kode

Tataan hasil

Keterangan

Izin

Contoh

J. Mengirim pesan email

B. Mengirim pesan email dengan hasil kueri

C. Mengirim pesan email HTML

Saran dan Komentar

Saran dan Komentar

Sumber Daya Tambahan:

sp_send_dbmail (T-SQL)

Sintaks

Argumen

[ @profile_name = ] 'profile_name'

[ @recipients = ] 'penerima'

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

[ @sensitivity = ] 'sensitivitas'

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

Mengembalikan nilai kode

Tataan hasil

Keterangan

Izin

Contoh

J. Mengirim pesan email

B. Mengirim pesan email dengan hasil kueri

C. Mengirim pesan email HTML

Konten terkait

Saran dan Komentar

Saran dan Komentar

Sumber Daya Tambahan: