Gmail メッセージの閲覧時にカードベースのインターフェースを提供するだけでなく、Gmail を拡張する Google Workspace アドオンは、ユーザーが新しいメッセージを作成したり、既存のメッセージに返信したりするときに別のインターフェースを提供できます。これにより、Google Workspace アドオンでユーザーのメール作成タスクを自動化できます。
アドオンの作成 UI へのアクセス
アドオンのコンポーザ UI を表示する方法は 2 つあります。1 つ目は、アドオンが開いている状態で新しい下書きの作成または返信を開始する方法です。2 つ目の方法は、下書きの作成中にアドオンを起動することです。
いずれの場合も、アドオンは、アドオンのマニフェストで定義されている対応するコンポーズ トリガー関数を実行します。作成トリガー関数は、その作成アクションの作成 UI を作成します。この UI は Gmail でユーザーに表示されます。
作成アドオンの構築
アドオンに作成機能を追加する一般的な手順は次のとおりです。
- アドオン スクリプト プロジェクトのマニフェストに
gmail.composeTriggerフィールドを追加し、マニフェストのスコープを更新して、作成アクションに必要なスコープを含めます。 - トリガーが起動したときにコンポーズ UI をビルドするコンポーズ トリガー関数を実装します。Compose トリガー関数は、単一の
Cardオブジェクトか、Compose アクションの Compose UI を構成するCardオブジェクトの配列を返します。 - ユーザーの Compose UI 操作に応答するために必要な関連するコールバック関数を実装します。これらの関数は、作成アクション自体（作成 UI の表示のみを引き起こす）ではありません。作成 UI のさまざまな要素が選択されたときに何が起こるかを制御する個々の関数です。たとえば、ボタンを含む UI カードには、通常、ユーザーがそのボタンをクリックしたときに実行されるコールバック関数が関連付けられています。下書きメッセージのコンテンツを更新するウィジェットのコールバック関数は、
UpdateDraftActionResponseオブジェクトを返す必要があります。
トリガー関数を構成する
アドオンの作成 UI は、アドオンのメッセージ UI と同じ方法で構築されます。Apps Script のカード サービスを使用してカードを構築し、ウィジェットを配置します。
マニフェストで定義した gmail.composeTrigger.selectActions[].runFunction を実装する必要があります。コンポーズ トリガー関数は、単一の Card オブジェクトか、そのアクションのコンポーズ UI を構成する Card オブジェクトの配列のいずれかを返す必要があります。これらの関数はコンテキスト トリガー関数と非常によく似ており、同じ方法でカードをビルドする必要があります。
トリガー イベント オブジェクトを構成する
作成アクションが選択されると、対応する作成トリガー関数が実行され、イベント オブジェクトがパラメータとして関数に渡されます。イベント オブジェクトは、アドオンのコンテキストと作成中の下書きに関する情報をトリガー関数に渡すことができます。
イベント オブジェクトでの情報の配置方法について詳しくは、イベント オブジェクトの構造をご覧ください。イベント オブジェクトに含まれる情報は、gmail.composeTrigger.draftAccess マニフェスト フィールドの値によって部分的に制御されます。
gmail.composeTrigger.draftAccessマニフェスト フィールドがNONEであるか、含まれていない場合、イベント オブジェクトには最小限の情報しか含まれません。gmail.composeTrigger.draftAccessがMETADATAに設定されている場合、作成トリガー関数に渡されるイベント オブジェクトには、作成中のメールの受信者のリストが入力されます。
アクティブな下書きへのコンテンツの挿入
通常、Google Workspace アドオンの作成 UI には、メッセージの作成に役立つユーザー オプションとコントロールが用意されています。このようなユースケースでは、ユーザーが UI で選択を行うと、アドオンが選択内容を解釈し、現在の作業中のメールのドラフトをそれに応じて更新します。
現在のメールの下書きを簡単に更新できるように、カードサービスが次のクラスで拡張されました。
ContentType- 変更可能な HTML、変更不可能な HTML（Gmail ユーザーが編集できない）、またはプレーン テキスト コンテンツを追加するかどうかを定義する列挙型。UpdateDraftActionResponse- 現在の下書きメールを更新するアクションに対するレスポンスを表します。UpdateDraftActionResponseBuilder-UpdateDraftActionResponseオブジェクトのビルダー。UpdateDraftBodyAction- 現在の下書きメールの本文を更新するアクションを表します。UpdateDraftBodyType- 本文の変更方法を定義する列挙型。UpdateDraftSubjectAction- 現在の下書きメールの件名フィールドを更新するアクションを表します。UpdateDraftToRecipientsAction- 現在の下書きメールの宛先を更新するアクションを表します。UpdateDraftCcRecipientsAction- 現在の下書きメールの Cc 受信者を更新するアクションを表します。UpdateDraftBccRecipientsAction- 現在の下書きメールの Bcc 受信者を更新するアクションを表します。
通常、アドオンの作成 UI には、ユーザーがクリックして UI での選択を完了し、選択内容を作成中のメールに追加したいことを示すことができる [保存] ウィジェットまたは [挿入] ウィジェットが含まれています。このインタラクティビティを追加するには、ウィジェットに Action オブジェクトを関連付ける必要があります。このオブジェクトは、ウィジェットがクリックされたときに特定コールバック関数を実行するようアドオンに指示します。これらのコールバック関数を実装する必要があります。各コールバック関数は、現在のメールの下書きに加える変更の詳細を示す、ビルドされた UpdateDraftActionResponse オブジェクトを返す必要があります。
例 1
次のコード スニペットは、現在のメールの下書きの件名、宛先、Cc、Bcc の受信者を更新する Compose UI を構築する方法を示しています。
/**
* Compose trigger function that fires when the compose UI is
* requested. Builds and returns a compose UI for inserting images.
*
* @param {event} e The compose trigger event object. Not used in
* this example.
* @return {Card[]}
*/
function getComposeUI(e) {
return [buildComposeCard()];
}
/**
* Build a card to display interactive buttons to allow the user to
* update the subject, and To, Cc, Bcc recipients.
*
* @return {Card}
*/
function buildComposeCard() {
var card = CardService.newCardBuilder();
var cardSection = CardService.newCardSection().setHeader('Update email');
cardSection.addWidget(
CardService.newTextButton()
.setText('Update subject')
.setOnClickAction(CardService.newAction()
.setFunctionName('applyUpdateSubjectAction')));
cardSection.addWidget(
CardService.newTextButton()
.setText('Update To recipients')
.setOnClickAction(CardService.newAction()
.setFunctionName('updateToRecipients')));
cardSection.addWidget(
CardService.newTextButton()
.setText('Update Cc recipients')
.setOnClickAction(CardService.newAction()
.setFunctionName('updateCcRecipients')));
cardSection.addWidget(
CardService.newTextButton()
.setText('Update Bcc recipients')
.setOnClickAction(CardService.newAction()
.setFunctionName('updateBccRecipients')));
return card.addSection(cardSection).build();
}
/**
* Updates the subject field of the current email when the user clicks
* on "Update subject" in the compose UI.
*
* Note: This is not the compose action that builds a compose UI, but
* rather an action taken when the user interacts with the compose UI.
*
* @return {UpdateDraftActionResponse}
*/
function applyUpdateSubjectAction() {
// Get the new subject field of the email.
// This function is not shown in this example.
var subject = getSubject();
var response = CardService.newUpdateDraftActionResponseBuilder()
.setUpdateDraftSubjectAction(CardService.newUpdateDraftSubjectAction()
.addUpdateSubject(subject))
.build();
return response;
}
/**
* Updates the To recipients of the current email when the user clicks
* on "Update To recipients" in the compose UI.
*
* Note: This is not the compose action that builds a compose UI, but
* rather an action taken when the user interacts with the compose UI.
*
* @return {UpdateDraftActionResponse}
*/
function applyUpdateToRecipientsAction() {
// Get the new To recipients of the email.
// This function is not shown in this example.
var toRecipients = getToRecipients();
var response = CardService.newUpdateDraftActionResponseBuilder()
.setUpdateDraftToRecipientsAction(CardService.newUpdateDraftToRecipientsAction()
.addUpdateToRecipients(toRecipients))
.build();
return response;
}
/**
* Updates the Cc recipients of the current email when the user clicks
* on "Update Cc recipients" in the compose UI.
*
* Note: This is not the compose action that builds a compose UI, but
* rather an action taken when the user interacts with the compose UI.
*
* @return {UpdateDraftActionResponse}
*/
function applyUpdateCcRecipientsAction() {
// Get the new Cc recipients of the email.
// This function is not shown in this example.
var ccRecipients = getCcRecipients();
var response = CardService.newUpdateDraftActionResponseBuilder()
.setUpdateDraftCcRecipientsAction(CardService.newUpdateDraftCcRecipientsAction()
.addUpdateToRecipients(ccRecipients))
.build();
return response;
}
/**
* Updates the Bcc recipients of the current email when the user clicks
* on "Update Bcc recipients" in the compose UI.
*
* Note: This is not the compose action that builds a compose UI, but
* rather an action taken when the user interacts with the compose UI.
*
* @return {UpdateDraftActionResponse}
*/
function applyUpdateBccRecipientsAction() {
// Get the new Bcc recipients of the email.
// This function is not shown in this example.
var bccRecipients = getBccRecipients();
var response = CardService.newUpdateDraftActionResponseBuilder()
.setUpdateDraftBccRecipientsAction(CardService.newUpdateDraftBccRecipientsAction()
.addUpdateToRecipients(bccRecipients))
.build();
return response;
}
例 2
次のコード スニペットは、現在のメールの下書きに画像を挿入する Compose UI を作成する方法を示しています。
/**
* Compose trigger function that fires when the compose UI is
* requested. Builds and returns a compose UI for inserting images.
*
* @param {event} e The compose trigger event object. Not used in
* this example.
* @return {Card[]}
*/
function getInsertImageComposeUI(e) {
return [buildImageComposeCard()];
}
/**
* Build a card to display images from a third-party source.
*
* @return {Card}
*/
function buildImageComposeCard() {
// Get a short list of image URLs to display in the UI.
// This function is not shown in this example.
var imageUrls = getImageUrls();
var card = CardService.newCardBuilder();
var cardSection = CardService.newCardSection().setHeader('My Images');
for (var i = 0; i < imageUrls.length; i++) {
var imageUrl = imageUrls[i];
cardSection.addWidget(
CardService.newImage()
.setImageUrl(imageUrl)
.setOnClickAction(CardService.newAction()
.setFunctionName('applyInsertImageAction')
.setParameters({'url' : imageUrl})));
}
return card.addSection(cardSection).build();
}
/**
* Adds an image to the current draft email when the image is clicked
* in the compose UI. The image is inserted at the current cursor
* location. If any content of the email draft is currently selected,
* it is deleted and replaced with the image.
*
* Note: This is not the compose action that builds a compose UI, but
* rather an action taken when the user interacts with the compose UI.
*
* @param {event} e The incoming event object.
* @return {UpdateDraftActionResponse}
*/
function applyInsertImageAction(e) {
var imageUrl = e.parameters.url;
var imageHtmlContent = '<img style=\"display: block\" src=\"'
+ imageUrl + '\"/>';
var response = CardService.newUpdateDraftActionResponseBuilder()
.setUpdateDraftBodyAction(CardService.newUpdateDraftBodyAction()
.addUpdateContent(
imageHtmlContent,
CardService.ContentType.MUTABLE_HTML)
.setUpdateType(
CardService.UpdateDraftBodyType.IN_PLACE_INSERT))
.build();
return response;
}