sp_send_dbmail (Transact-SQL)

[アーティクル]
08/21/2024

適用対象: SQL Server Azure SQL Managed Instance

指定した受信者に電子メールメッセージを送信します。メッセージには、クエリ結果セット、添付ファイル、またはその両方が含まれる場合があります。メールがデータベースメールキューに正常に配置されると、sp_send_dbmailはメッセージのmailitem_idを返します。このストアドプロシージャは、 msdb データベースにあります。

Transact-SQL 構文表記規則

構文

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

引数

[ @profile_name = ] 'profile_name'

メッセージを送信するプロファイルの名前。 @profile_nameは sysname 型で、既定値は NULL です。 @profile_nameは、既存のデータベースメールプロファイルの名前である必要があります。 @profile_nameが指定されていない場合、sp_send_dbmailは現在のユーザーの既定のプライベートプロファイルを使用します。ユーザーが既定のプライベートプロファイルを持っていない場合、 sp_send_dbmail は msdb データベースの既定のパブリックプロファイルを使用します。ユーザーに既定のプライベートプロファイルがなく、データベースの既定のパブリックプロファイルがない場合は、 @profile_name を指定する必要があります。

[ @recipients = ] 'recipients'

メッセージを送信する電子メールアドレスのセミコロン区切りのリスト。受信者リストの種類は varchar(max)です。このパラメーターは省略可能ですが、少なくとも 1 つの @recipients、 @copy_recipients、または @blind_copy_recipients を指定するか、 sp_send_dbmail エラーを返す必要があります。

[ @copy_recipients = ] 'copy_recipients'

メッセージのカーボンコピー先の電子メールアドレスのセミコロン区切りのリスト。コピー先リストは、 varchar(max)型です。このパラメーターは省略可能ですが、少なくとも 1 つの @recipients、 @copy_recipients、または @blind_copy_recipients を指定するか、 sp_send_dbmail エラーを返す必要があります。

[ @blind_copy_recipients = ] 'blind_copy_recipients'

メッセージのコピー先のブラインドカーボンの電子メールアドレスのセミコロン区切りのリスト。ブラインドコピー受信者リストは、 varchar(max)型です。このパラメーターは省略可能ですが、少なくとも 1 つの @recipients、 @copy_recipients、または @blind_copy_recipients を指定するか、 sp_send_dbmail エラーを返す必要があります。

[ @from_address = ] 'from_address'

電子メールメッセージの "from address" の値。これは、メールプロファイルの設定をオーバーライドするために使用される省略可能なパラメーターです。このパラメーターの型は varchar(max)です。オーバーライドが許可されるかどうかは、SMTP のセキュリティ設定によって決まります。パラメーターが指定されていない場合、既定値は NULL です。

[ @reply_to = ] 'reply_to'

電子メールメッセージの "アドレスへの返信" の値。有効な値として受け取る電子メールアドレスは 1 つだけです。これは、メールプロファイルの設定をオーバーライドするために使用される省略可能なパラメーターです。このパラメーターの型は varchar(max)です。オーバーライドが許可されるかどうかは、SMTP のセキュリティ設定によって決まります。パラメーターが指定されていない場合、既定値は NULL です。

[ @subject = ] N'subject'

電子メールメッセージの件名です。件名は nvarchar(255) 型です。件名が指定されていない場合、既定値は "SQL Server メッセージ" です。

[ @body = ] N'body'

電子メールメッセージの本文。メッセージ本文は nvarchar(max) 型で、既定値は NULL です。

[ @body_format = ] 'body_format'

メッセージ本文の形式。パラメーターは varchar(20) 型で、既定値は NULL です。指定した場合、送信メッセージのヘッダーには、メッセージの本文が指定の形式であることを示す文字列が設定されます。パラメーターには、次のいずれかの値が含まれる場合があります。

TEXT (既定)
HTML

[ @importance = ] 'importance'

メッセージの重要度。パラメーターの型は varchar(6)です。パラメーターには、次のいずれかの値が含まれる場合があります。

Low
Normal (既定)
High

[ @sensitivity = ] 'センシティビティ'

メッセージの秘密度。パラメーターの型は varchar(12)です。パラメーターには、次のいずれかの値が含まれる場合があります。

Normal (既定)
Personal
Private
Confidential

[ @file_attachments = ] N'file_attachments'

電子メールメッセージに添付するファイル名のセミコロン区切りのリスト。リスト内のファイルは絶対パスとして指定する必要があります。添付ファイルの一覧の種類は nvarchar(max)です。既定では、データベースメールの添付ファイルは 1 ファイルにつき 1 MB に制限されます。

重要

このパラメーターは、ローカルファイルシステムにアクセスできないため、Azure SQL Managed Instance では使用できません。

[ @query = ] N'query'

実行するクエリ。クエリの結果は、ファイルとして添付することも、電子メールメッセージの本文に含めることもできます。クエリの種類は nvarchar(max)で、任意の有効な Transact-SQL ステートメントを含めることができます。クエリは別のセッションで実行されるため、 sp_send_dbmail を呼び出すスクリプト内のローカル変数はクエリで使用できません。

@query パラメーターを使用する場合、sp_send_dbmail実行するプリンシパルは、Microsoft Entra ID (形式の Azure Active Directory) グループか Windows Active Directory グループかにかかわらず、グループの一部としてではなく、個人として接続する必要があります。 SQL Server ログイン、Windows ID、および Microsoft Entra ID はクエリを実行できますが、Azure SQL Managed Instance の偽装と EXECUTE AS の制限により、グループメンバーは実行できません。

[ @execute_query_database = ] 'execute_query_database'

ストアドプロシージャがクエリを実行するデータベースコンテキスト。パラメーターの型は sysname で、既定値は現在のデータベースです。このパラメーターは、 @query が指定されている場合にのみ適用されます。

[ @attach_query_result_as_file = ] attach_query_result_as_file

クエリの結果セットを添付ファイルとして返すかどうかを指定します。 @attach_query_result_as_file の種類は bit で、既定値は 0 です。

値が 0されると、 @body パラメーターの内容の後に、電子メールメッセージの本文にクエリ結果が含まれます。値が 1されると、結果が添付ファイルとして返されます。このパラメーターは、 @query が指定されている場合にのみ適用されます。

[ @query_attachment_filename = ] N'query_attachment_filename'

クエリ添付ファイルの結果セットに使用するファイル名を指定します。 @query_attachment_filename は nvarchar(255) 型で、既定値は NULL です。 @attach_query_result_as_fileが0されている場合、このパラメーターは無視されます。 @attach_query_result_as_fileが1され、このパラメーターがNULLされると、データベースメールは任意のファイル名を作成します。

[ @query_result_header = ] query_result_header

クエリの結果に列のヘッダーを含めるかどうかを指定します。 query_result_header値の種類は bit です。値が 1されると、クエリ結果に列ヘッダーが含まれます。値が 0されている場合、クエリ結果には列ヘッダーは含まれません。このパラメーターの既定値は 1 です。このパラメーターは、 @query が指定されている場合にのみ適用されます。

@query_result_headerを0に設定し、@query_no_truncateを1に設定すると、次のエラーが発生する可能性があります。

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

[ @query_result_width = ] query_result_width

クエリの結果の書式設定に使用する行の幅 (文字単位)。 @query_result_widthは int 型で、既定値は 256 です。指定する値は、 10 と 32767の間である必要があります。このパラメーターは、 @query が指定されている場合にのみ適用されます。

[ @query_result_separator = ] 'query_result_separator'

クエリの出力で列の区切りに使用された文字。区切り記号は char(1) 型です。既定値は ' ' (スペース) です。

[ @exclude_query_output = ] exclude_query_output

電子メールメッセージ内にクエリ実行の出力を返すかどうかを指定します。 @exclude_query_output は bit で、既定値は 0 です。このパラメーターを 0すると、 sp_send_dbmail ストアドプロシージャの実行によって、コンソールでのクエリ実行の結果として返されるメッセージが出力されます。このパラメーターが 1されている場合、 sp_send_dbmail ストアドプロシージャの実行では、コンソールにクエリ実行メッセージは出力されません。

[ @append_query_error = ] append_query_error

@query引数で指定したクエリからエラーが返されたときに電子メールを送信するかどうかを指定します。 @append_query_error は bit で、既定値は 0 です。このパラメーターを1すると、データベースメールは電子メールメッセージを送信し、電子メールメッセージの本文にクエリエラーメッセージを含めます。このパラメーターが0されると、データベースメールは電子メールメッセージを送信せず、sp_send_dbmailはエラーを示すリターンコード 1で終わります。

[ @query_no_truncate = ] query_no_truncate

大きな可変長データ型 (varchar(max)の切り捨てを回避するオプションを使用してクエリを実行するかどうかを指定します。 nvarchar(max)、 varbinary(max)、 xml、 text、 ntext、 image、およびユーザー定義データ型)。設定すると、クエリ結果に列ヘッダーは含まれません。 @query_no_truncate値の種類は bit です。値が 0 または指定されていない場合、クエリ内の列は 256 文字に切り捨てられます。値が 1されている場合、クエリ内の列は切り捨てられません。このパラメーターの既定値は 0 です。

Note

大量のデータと共に使用すると、 @query_no_truncate オプションによって追加のリソースが消費され、サーバーのパフォーマンスが低下する可能性があります。

[ @query_result_no_padding = ] query_result_no_padding

型は bit です。既定値は、0 です。 1に設定すると、クエリ結果が埋め込まれるので、ファイルサイズが小さくなる可能性があります。 @query_result_no_paddingを 1 に設定し、@query_result_width パラメーターを設定すると、@query_result_no_padding パラメーターによって @query_result_width パラメーターが上書きされます。

この場合、エラーは発生しません。

@query_result_no_paddingを1に設定し、@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.

@query_result_no_paddingを 1 に設定し、@query_no_truncate パラメーターを設定すると、エラーが発生します。

[ @mailitem_id = ] mailitem_id [ OUTPUT ]

省略可能な出力パラメーターは、メッセージの mailitem_id を返します。 @mailitem_id は int 型です。

リターンコードの値

0のリターンコードは成功を意味します。その他の値は失敗を意味します。失敗したステートメントのエラーコードは、 @@ERROR 変数に格納されます。

結果セット

成功すると、"メールがキューに登録されました。" というメッセージが返されます。

解説

データベースメールを使用する前に、データベースメール構成ウィザードまたはsp_configureを使用して有効にする必要があります。

sysmail_stop_spは、外部プログラムが使用する Service Broker オブジェクトを停止することによって、データベースメールを停止します。 sp_send_dbmailは、sysmail_stop_spを使用してデータベースメールが停止した場合でもメールを受け入れます。データベースメールを開始するには、sysmail_start_spを使用します。

@profileが指定されていない場合、sp_send_dbmailは既定のプロファイルを使用します。電子メールメッセージを送信するユーザーに既定のプライベートプロファイルがある場合、データベースメールではそのプロファイルが使用されます。ユーザーに既定のプライベートプロファイルがない場合、 sp_send_dbmail は既定のパブリックプロファイルを使用します。ユーザーの既定のプライベートプロファイルがなく、既定のパブリックプロファイルがない場合、 sp_send_dbmail はエラーを返します。

sp_send_dbmail では、コンテンツのない電子メールメッセージはサポートされません。電子メールメッセージを送信するには、少なくとも 1 つの @body、 @query、 @file_attachments、または @subjectを指定する必要があります。それ以外の場合、 sp_send_dbmail はエラーを返します。

データベースメールでは、ファイルへのアクセス制御に現在のユーザーの Windows セキュリティコンテキストが使用されます。そのため、SQL Server 認証で認証されたユーザーは、 @file_attachmentsを使用してファイルを添付できません。 Windows では、SQL Server がリモートコンピューターから別のリモートコンピューターに資格情報を提供することはできません。そのため、SQL Server が実行されているコンピューター以外のコンピューターからコマンドを実行した場合、データベースメールはネットワーク共有からファイルをアタッチできない可能性があります。

@queryと@file_attachmentsの両方が指定されていて、ファイルが見つからない場合、クエリは引き続き実行されますが、電子メールは送信されません。

クエリを指定すると、結果セットはインラインテキストとして書式設定されます。結果セットにあるバイナリデータは 16 進数形式で送信されます。

パラメーター @recipients、 @copy_recipients、および @blind_copy_recipients は、電子メールアドレスのセミコロン区切りのリストです。これらのパラメーターのうち少なくとも 1 つを指定するか、エラー sp_send_dbmail 返す必要があります。

トランザクションコンテキストなしでsp_send_dbmailを実行すると、データベースメールが開始され、暗黙的なトランザクションがコミットされます。既存のトランザクション内からsp_send_dbmailを実行する場合、データベースメールはユーザーに依存して変更をコミットまたはロールバックします。内部トランザクションは開始されません。

アクセス許可

msdb データベースの DatabaseMailUser データベースロールのすべてのメンバーに対する既定のsp_send_dbmailの実行アクセス許可。ただし、メッセージを送信するユーザーに要求のプロファイルを使用するアクセス許可がない場合、 sp_send_dbmail はエラーを返し、メッセージを送信しません。

例

A. 電子メールメッセージを送信する

この例では、電子メールアドレス myfriend@adventure-works.comを使用して、友人に電子メールメッセージを送信します。メッセージには件名が Automated Success Message。メッセージの本文には、 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. クエリの結果を含む電子メールメッセージを送信する

この例では、電子メールアドレス yourfriend@adventure-works.comを使用して、友人に電子メールメッセージを送信します。メッセージには件名 Work Order Countがあり、2022 年 4 月 30 日から 2 日以内に DueDate された作業指示書の数を示すクエリが実行されます。データベースメール結果をテキストファイルとして添付します。

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: HTML 電子メールメッセージを送信する

この例では、電子メールアドレス yourfriend@adventure-works.comを使用して、友人に電子メールメッセージを送信します。メッセージには件名 Work Order Listがあり、2022 年 4 月 30 日から 2 日以内に DueDate の作業指示書を示す HTML ドキュメントが含まれています。データベースメールでは、このメッセージが 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 (Transact-SQL)

構文

引数

[ @profile_name = ] 'profile_name'

[ @recipients = ] 'recipients'

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

[ @sensitivity = ] 'センシティビティ'

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

リターンコードの値

結果セット

解説

アクセス許可

例

A. 電子メールメッセージを送信する

B. クエリの結果を含む電子メールメッセージを送信する

C: HTML 電子メールメッセージを送信する

フィードバック

その他のリソース

次の方法で共有

sp_send_dbmail (Transact-SQL)

構文

引数

[ @profile_name = ] 'profile_name'

[ @recipients = ] 'recipients'

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

[ @sensitivity = ] 'センシティビティ'

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

リターン コードの値

結果セット

解説

アクセス許可

例

A. 電子メール メッセージを送信する

B. クエリの結果を含む電子メール メッセージを送信する

C: HTML 電子メール メッセージを送信する

関連するコンテンツ

フィードバック

その他のリソース

リターンコードの値

A. 電子メールメッセージを送信する

B. クエリの結果を含む電子メールメッセージを送信する

C: HTML 電子メールメッセージを送信する