SendGrid: Web API v3利用時にボディパラメータを上書き可能にする（ドキュメント）

developerguide/src/docs/asciidoc/notification/mail.adoc

@@ -226,7 +226,10 @@ SendGrid固有オプションは以下の手順で設定します。詳しい実
 ==== 注意事項
 固有オプションを設定する場合、以下の点に注意してください。
 
-* Mail インスタンスに設定されている情報から作成するオプション（例: personalizations, content など）は設定できません。設定した場合、そのオプションは上書きされます。
+* Mail インスタンスに設定されている情報から作成される本文パラメータ（例: `personalizations`, `content` など）と同名の SendGrid 固有オプション値を設定した場合、Mail インスタンスから生成される本文パラメータが優先され、同名で追加した固有オプション値はサニタイズ（無効化）されます。
+** 標準の機能では対応できない設定を行いたい場合は固有オプションを利用しますが、デフォルトでは `personalizations`, `content` など既存の本文パラメータと衝突する特定の固有オプション値はサニタイズされ、メール送信リクエストには反映されません。 +
+メール送信リクエストに反映したい場合は SendGridV3MailService の `canOverwriteBodyParameter` プロパティを `true` に設定することで、これらの固有オプション値はサニタイズされず、固有オプションで指定した値で既存の本文パラメータを上書きできるようになります。 +
+実装と結果については、後述の「<<mail_configure_SendGridV3MailService_canOverwriteBodyParameter_example>>」を参照してください。
 * 固有オプションを設定した場合、存在の有無にかかわらずSendGridメール送信リクエストのボディに追加されます。
 ** アプリケーションのセキュリティ上のリスク軽減のため、ユーザー入力値を無加工でオプションの値として設定しないでください。
 ** 意図しないオプションが設定されないように、事前にバリデーションを行うことを推奨します。
@@ -274,7 +277,8 @@ private void sendMailWithSendGridOptions() {
             "html", "<strong>This is the footer html.</strong>"
         )
     ));
-    // 上記の指定で、以下のような値が追加されます。
+
+    // 上記の指定で、メール送信時のリクエストボディに以下のような値が追加されます。
     // 
     // {
     //   "asm": {
@@ -294,3 +298,67 @@ private void sendMailWithSendGridOptions() {
     manager.sendMail(sendGridMail);
 }
 ----
+
+[[mail_configure_SendGridV3MailService_canOverwriteBodyParameter_example]]
+==== SendGridV3MailService のプロパティ canOverwriteBodyParameter 設定による動作の変化
+SendGridV3MailService のプロパティ `canOverwriteBodyParameter` の設定によって、優先する項目を制御できます。 +
+`false` に設定した場合、Mail オブジェクトから生成される本文パラメータが優先され、同名の固有オプション値はサニタイズされます。 +
+`true` に設定した場合、Mail オブジェクトから生成される本文パラメータを SendGrid 固有オプションで上書きできます。
+
+ServiceConfig SendGridV3MailService の設定の詳細は <<../../serviceconfig/index.adoc#MailService_SendGridV3MailService, MailService - SendGridV3MailService>> を参照してください。
+
+[source,java]
+----
+import org.iplass.mtp.mail.Mail;
+import org.iplass.mtp.mail.MailManager;
+import org.iplass.mtp.mail.sendgrid.SendGridMail;
+
+private void sendMailWithSendGridOptions() {
+    MailManager manager = ManagerLocator.manager(MailManager.class);
+
+    Mail mail = manager.createMail();
+
+    // mail に対して、送信先等を設定する
+    // :
+    // :
+    // <a> Mail オブジェクトに本文を設定する
+	mail.setMessage("これは本文です");
+
+    // Mail オブジェクトを SendGridMail にキャスト
+    SendGridMail sendGridMail = (SendGridMail)mail;
+
+    // <b> SendGrid固有オプションとして content を設定する
+    sendGridMail.putBodyParameter("content", List.of(Map.of(
+        "type", "text/plain",
+        "value", "SendGrid固有オプションで設定した本文です"
+    )));
+
+    // 上記の実装で canOverwriteBodyParameter の設定により、SendGrid API実行時のリクエストボディは以下のように変化します。
+    // 
+    // ＜ デフォルトの設定（canOverwriteBodyParameter = false）の場合 ＞
+    // <a> で設定した Mail オブジェクトから生成される content パラメータが優先されます。<b> で設定した同名の固有オプションの値はサニタイズされます。
+    // 
+    // {
+    //   "content": [
+    //     {
+    //       "type": "text/plain",
+    //       "value": "これは本文です"
+    //     }
+    //   ]
+    // }
+
+    // ＜ canOverwriteBodyParameter を true に設定した場合 ＞
+    // <a> で設定した Mail オブジェクトから生成される content パラメータが上書きされ、<b> で設定した固有オプションの値が利用されます。
+    //
+    // {
+    //   "content": [
+    //     {
+    //       "type": "text/plain",
+    //       "value": "SendGrid固有オプションで設定した本文です"
+    //     }
+    //   ]
+    // }
+
+    manager.sendMail(sendGridMail);
+}
+----

serviceconfig/src/docs/asciidoc/core/mailservice_en.adoc

@@ -414,6 +414,7 @@ It is similar to the <<SendMailListener>> in MailServiceImpl.
 </service>
 ----
 
+[[MailService_SendGridV3MailService]]
 ==== [.eeonly]#Settings of SendGridV3MailService#
 
 To use SendGrid Web API v3, please specify and configure the SendGridV3MailService.
@@ -428,6 +429,14 @@ To use SendGrid Web API v3, please specify and configure the SendGridV3MailServi
 | listener | <<SendMailListener_s_v3, SendMailListener>>, Multiple | The listener for sending the mail.
 | retryIntervalMillis | long | The retry interval when the transmission fails.(in millisecond)
 | retryCount | int | The number of retry attempts for email transmission to fail.
+| canOverwriteBodyParameter | boolean | Whether to overwrite conflicting body parameters (such as `personalizations`, `content`, etc.) generated from the Mail settings in the SendGrid Web API v3 request with custom option parameters. The default value is `false`. +
+The Mail class used in the SendGrid Web API v3 request is SendGridMail. +
+SendGridMail has the putBodyParameter and setBodyParameters methods, which can be used to set custom option parameters.
+The added custom option parameters are added to the body of the SendGrid Web API v3 request. +
+If this parameter is `false`, then when an added custom option parameter has the same key as a body parameter created from the information set in SendGridMail (e.g., `personalizations`, `content`, etc.), the original body parameter value is kept and the conflicting custom option parameter value is sanitized. +
+By setting this parameter to `true`, in such key conflicts the values of the custom option parameters are used as-is (without sanitization), and they overwrite the existing conflicting body parameters.
+
+Also refer to the behavior <<../developerguide/notification/index.adoc#mail_configure_SendGridV3MailService_canOverwriteBodyParameter_example, changes caused by the canOverwriteBodyParameter setting in the SendGridV3MailService properties>>.
 |===
 
 [[HttpClientConfig]]
@@ -484,6 +493,9 @@ It is similar to the <<SendMailListener>> in MailServiceImpl.
 	<!-- The charset of the mail -->
 	<property name="charset" value="UTF-8" />
 
+	<!-- Whether to allow overwriting the body parameters in the SendGrid Web API v3 request -->
+	<property name="canOverwriteBodyParameter" value="false" />
+
 	<!-- ■ for develop only (additional="true") ■ -->
 	<!-- 
 	<property name="listener" class="org.iplass.mtp.mail.listeners.LoggingSendMailListener" additional="true"/>

serviceconfig/src/docs/asciidoc/core/mailservice_ja.adoc

@@ -415,6 +415,7 @@ MailServiceImplの<<SendMailListener>>と同様です。
 </service>
 ----
 
+[[MailService_SendGridV3MailService]]
 ==== [.eeonly]#SendGridV3MailServiceの設定#
 
 SendGrid Web API v3を利用する場合、SendGridV3MailServiceを設定します。
@@ -429,6 +430,14 @@ SendGrid Web API v3を利用する場合、SendGridV3MailServiceを設定しま
 | listener | <<SendMailListener_s_v3, SendMailListener>>、複数指定可 | メール送信時のListener。
 | retryIntervalMillis | long | 送信失敗時のリトライ間隔（ミリ秒）。
 | retryCount | int | 送信失敗時のリトライ回数。
+| canOverwriteBodyParameter | boolean | SendGrid Web API v3のリクエストで、メール設定から生成される競合するボディパラメータ（例: `personalizations`, `content` など）を固有オプションパラメータで上書きするかを設定します。デフォルト値は `false` です。 +
+SendGrid Web API v3のリクエストで利用する Mail クラスは SendGridMail です。 +
+SendGridMail には putBodyParameter メソッドと setBodyParameters メソッドがあり、これを利用して固有オプションパラメータを設定することができます。
+追加した固有オプションパラメータは SendGrid Web API v3 のリクエストのボディに追加されます。 +
+この際、本パラメータが `false` の場合、追加した固有オプションパラメータのうち、SendGridMail に設定されている情報から作成される本文パラメータ（例: `personalizations`, `content` など）と同名のものはサニタイズされ、SendGridMail から生成された本文パラメータ側が優先されます。 +
+本パラメータを `true` に設定すると、これら同名の追加した固有オプションパラメータはサニタイズされずに優先的に利用され、SendGridMail から生成される本文パラメータを上書きします。
+
+<<../developerguide/notification/index.adoc#mail_configure_SendGridV3MailService_canOverwriteBodyParameter_example, SendGridV3MailService のプロパティ canOverwriteBodyParameter 設定による動作の変化>>も参照してください。
 |===
 
 [[HttpClientConfig]]
@@ -486,6 +495,8 @@ MailServiceImplの<<SendMailListener>>と同様です。
 	<!-- メールの文字コード -->
 	<property name="charset" value="UTF-8" />	
 
+	<!-- ボディパラメータを上書き可能とする -->
+	<property name="canOverwriteBodyParameter" value="false" />
 
 	<!-- ■ for develop only (additional="true") ■ -->
 	<!--