Google Workspace アドオンは、ユーザーが Gmail のメールを読む際にカードベースのインターフェースを提供するだけでなく、ユーザーが新しいメッセージを作成したり既存のメッセージに返信したりする際に別のインターフェースを提供することができます。これにより、Google Workspace アドオンはユーザーのメール作成タスクを自動化できます。
アドオン作成 UI へのアクセス
アドオンの作成 UI を表示する方法は 2 つあります。1 つ目の方法は、アドオンがすでに開いているときに、新しい下書きまたは返信の作成を開始することです。2 つ目の方法は、ドラフトの作成中にアドオンを開始することです。
いずれの場合も、アドオンはアドオンのマニフェストで定義されている、対応する作成トリガー関数を実行します。作成トリガー関数により、その作成アクションの作成 UI が構築され、Gmail がユーザーに表示されます。
Compose アドオンをビルドする
以下の一般的な手順に沿って、作成機能をアドオンに追加できます。
gmail.composeTriggerフィールドをアドオン スクリプト プロジェクトのマニフェストに追加し、マニフェストのスコープを更新して、Compose アクションに必要なスコープを含めます。- トリガーの配信時に Compose UI を作成する Compose トリガー関数を実装します。Compose トリガー関数は、単一の
Cardオブジェクト、または Compose アクションの Compose UI を構成するCardオブジェクトの配列を返します。 - ユーザーの Compose UI の操作に応答するために必要な関連コールバック関数を実装します。これらの関数は Compose アクション自体ではなく、それによって Compose UI が表示されるだけです。むしろ、これらは Compose UI のさまざまな要素が選択されたときに行われる個々の関数です。たとえば、ボタンを含む UI カードには通常、ユーザーがそのボタンをクリックしたときに実行されるコールバック関数が関連付けられています。メッセージの下書きの内容を更新するウィジェットのコールバック関数は、
UpdateDraftActionResponseオブジェクトを返す必要があります。
Compose トリガー関数
アドオンの作成 UI は、アドオンのメッセージ UI と同じように構築されます。Apps Script のカードサービスを使用してカードを作成し、ウィジェットを埋めます。
マニフェストで定義した gmail.composeTrigger.selectActions[].runFunction を実装する必要があります。作成トリガー関数は、単一の Card オブジェクト、またはそのアクションの作成 UI を構成する Card オブジェクトの配列を返す必要があります。これらの関数は、コンテキスト トリガー関数とよく似ており、同じ方法でカードを作成する必要があります。
Compose トリガー イベント オブジェクト
作成アクションが選択されると、対応する作成トリガー関数が実行され、関数にパラメータとしてイベント オブジェクトが渡されます。イベント オブジェクトには、トリガーする関数に構成されているアドオンのコンテキストとドラフトに関する情報を含めることができます。
イベント オブジェクト内の情報の配置について詳しくは、イベント オブジェクト構造をご覧ください。イベント オブジェクトに含まれる情報は、gmail.composeTrigger.draftAccess マニフェスト フィールドの値によって部分的に制御されます。
gmail.composeTrigger.draftAccessマニフェスト フィールドがNONEであるか含まれていない場合、イベント オブジェクトには最小限の情報のみが含まれます。gmail.composeTrigger.draftAccessがMETADATAに設定されている場合、Compose トリガー関数に渡されるイベント オブジェクトには、作成されるメールの受信者のリストが入力されます。
アクティブな下書きへのコンテンツの挿入
通常、Google Workspace アドオンの作成 UI には、メッセージの作成に役立つユーザー オプションとコントロールが用意されています。このようなユースケースでは、ユーザーが UI で選択を行うと、アドオンが選択内容を解釈し、それに応じて現在の作業用メールの下書きを更新します。
現在の下書き用メールを簡単に更新できるように、カードサービスが拡張され、次のクラスが追加されました。
ContentType- 変更可能な HTML、変更できない HTML（Gmail ユーザーが編集できない）、書式なしテキストのコンテンツを追加するかどうかを定義する列挙型。UpdateDraftActionResponse- 現在の下書きのメールを更新するアクションに対するレスポンスを表します。UpdateDraftActionResponseBuilder-UpdateDraftActionResponseオブジェクトのビルダー。UpdateDraftBodyAction- 現在の下書きメールの本文を更新するアクションを表します。UpdateDraftBodyType- 本文の変更方法を定義する列挙型。UpdateDraftSubjectAction- 現在の下書きメールの件名フィールドを更新するアクションを表します。UpdateDraftToRecipientsAction- 現在の下書きメールの To 受信者を更新するアクションを表します。UpdateDraftCcRecipientsAction- 現在の下書きメールの Cc 受信者を更新するアクションを表します。UpdateDraftBccRecipientsAction- 現在の下書きメールの Bcc の受信者を更新するアクション。
通常、アドオンの作成 UI には「保存」または「挿入」ウィジェットが含まれており、ユーザーはこれをクリックして UI での選択を行い、作成しているメールに選択を追加することができます。このインタラクティビティを追加するには、ウィジェットに Action オブジェクトが関連付けられている必要があります。このオブジェクトは、ウィジェットがクリックされたときに特定のコールバック関数を実行するようアドオンに指示します。これらのコールバック関数を実装する必要があります。各コールバック関数は、ビルドされた UpdateDraftActionResponse オブジェクトを返します。このオブジェクトは、現在の下書きメールに加えた変更を詳述します。
例 1
次のコード スニペットは、件名、および現在のメールの下書きの宛先（Cc、Bcc）を更新する作成 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;
}