新しい Google Workspace アドオンをビルドする場合は、次の一般的な手順を行います。
- アドオンのプロジェクトを設定し、オーナーと共同編集者を選択します。
- アドオンの外観と動作を設計します。
- アドオンのプロジェクト マニフェストまたはデプロイ リソースを構成します。
- アドオンの外観と動作を定義するコードを記述します。
- アドオンの OAuth スコープを確認します。
- 拡張するホスト アプリケーション内でアドオンをテストします。
- アドオンを公開します。
アドオンのプロジェクトを設定し、オーナーと共同編集者を選択する
Apps Script でアドオンをビルドする場合は、Apps Script プロジェクトと Google Cloud プロジェクトの両方を作成します。Apps Script 以外の言語でアドオンをビルドする場合は、Google Cloud プロジェクトを作成するだけで済みます。
アドオンの開発を開始する前に、プロジェクトを所有し、共同編集者である他のアカウントを決めるために、単一のユーザー アカウントを選択します。プロジェクトのオーナーは、プロジェクト ファイルと関連設定の作成と管理を行います。共同編集者は、コーディングとテストを行うことができます。
Apps Script プロジェクト
アドオンの Apps Script プロジェクト ファイルを共有ドライブに構築して、1 つのアカウントに唯一のオーナーを割り当てることはできません。アドオン スクリプト ファイルを共有ドライブに配置すると、複数の共同編集者がスクリプト プロジェクトにアクセスすることが容易になります。
アドオンを公開する際は、単一のユーザー アカウントがパブリッシャーとして機能します。公開アカウントには、スクリプト プロジェクトに対する編集権限が必要ですが、オーナーである必要はありません。
Google Cloud プロジェクト
アドオンの Cloud プロジェクトに共同編集者を追加することをおすすめします。これにより、チームのメンバーはアドオンの Cloud 設定にいつでもアクセスできます。
アドオンの外観と動作を設計する
アドオンの外観と動作を指定します。アドオンがソリューションの提供を試みるユースケースを検討します。まずは簡単なデザインから始めて、徐々に改良を加えていきます。
アドオンのユーザー エクスペリエンスの設計方法については、Google Workspace アドオンのスタイルガイドをご覧ください。
アドオンのプロジェクト マニフェストを構成する
Apps Script プロジェクトでは、プロジェクト マニフェストは特別な JSON ファイルです。ライブラリの依存関係など、プロジェクトに関するさまざまな詳細情報を指定します。Google Workspace アドオンの場合、マニフェストには、ホスト アプリケーションがアドオンを正しく表示するために必要な基本情報も用意されています。
Apps Script でアドオンのマニフェストを構成する方法について詳しくは、マニフェストをご覧ください。
アドオンにコードと機能を追加する際は、必要に応じてマニフェストを編集して、必要なアドオンの外観と動作を生成します。
アドオンをコーディングする
アドオンにはカードベースのインターフェースを実装する必要があります。Apps Script のカードサービスを使用するか、別のコード言語で記述している場合は、インターフェースがカードとしてレンダリングされるように、適切な形式の JSON を返します。
また、アドオン マニフェストで指定されているトリガー関数も実装する必要があります。アドオンが OAuth を使用してサードパーティの Google 以外のサービスに接続する場合は、そのサービスについても OAuth を構成する必要があります。
カードの作成
アドオンのユーザー インターフェースを定義するには、Card オブジェクトを作成して、ウィジェットを入力します。マニフェストで指定されたトリガー関数は、単一の Card オブジェクト、またはアドオン インターフェースの異なる「ページ」を表す Card オブジェクトの配列を返す必要があります。このアドオンによって、ユーザーの操作に応じて新しいカードを作成して表示することもできます。
Apps Script では、CardBuilder クラスを使用してカードを作成します。各カードには CardHeader と 1 つ以上の CardSections が必要です。各カード セクションに、アドオン インターフェースを構成する個別のウィジェットを入力する必要があります。インタラクション ウィジェットは通常、アクションにリンクされてそのインタラクションの動作が定義されます。
CardBuilder を使用してすべてのセクションとウィジェットをカードに追加したら、CardBuilder.build() を呼び出して、対応する Card オブジェクトを作成する必要があります。
CalendarApp などの組み込みの Apps Script サービスを使用して、ビルドしたアドオン カードに表示する情報を取得できます。Google 以外のサービスから取得したデータを使用できます。
Google Workspace アドオンが、OAuth を必要とする Google 以外の API にアクセスする必要がある場合は、そのサービスを構成して接続する必要があります。詳細については、Google 以外のサービスへの接続ガイドをご覧ください。
建設順序
カードを作成する際は、最初から構築する必要があります。つまり、次の作成順序を使用する必要があります。
- ウィジェットを作成します。
- カード セクションにウィジェットを追加します。
- カード セクションにすべてのウィジェットが表示されるまで、この操作を繰り返します。
- カードにカード セクションを追加します。
これは、ウィジェットをカードまたはカード セクションに追加するときに、そのウィジェットのコピーを追加する必要があるためです。追加後にウィジェット オブジェクトに加えた変更は、最終カードには反映されません。
ユニバーサル アクション
ユニバーサル アクションを使用して、コンテキストに依存しない機能を提供できます。ユニバーサル アクションは、現在表示されているカードに関係なく、アドオン UI で使用できるメニュー項目です。定義したユニバーサル アクションはすべて、アドオンのカードメニューに常に表示されます。
詳細については、ユニバーサル アクションをご覧ください。
アドオンの OAuth スコープを確認する
スコープは、ユーザーに代わってアドオンが実行できるアクションを定義します。アドオンには、その関数に必要なアクションのスコープのみを設定し、それ以外は何も指定しないことをおすすめします。
アドオン プロジェクトで可能な限り制限の厳しいスコープセットを使用するように、アドオンのスコープを明示的に設定します。アドオンのスコープは、アドオンのマニフェストで定義します。
詳細については、スコープをご覧ください。
アドオンをテストする
非公開アドオンは、まず非公開アドオンをインストールすることでテストできます。アドオンをインストールして承認すると、アカウントでアドオンを使用して、その拡張機能が拡張するホスト アプリケーションで外観と動作をテストできます。アドオンがコンテキストとユーザー アクションで想定どおりに動作することを確認する必要があります。
詳しくは、Google Workspace アドオンのテストをご覧ください。
アドオンを公開する
アドオンは、一般公開するか、ドメイン内のユーザーのみに公開できます。公開プロセスを開始する前に、パブリケーションの概要を確認してください。公開は複雑なプロセスであり、準備と完了に時間がかかります。
Google Workspace アドオンは Google Workspace Marketplace で公開されます。一般公開されているアドオンは、公開前にアプリの審査を完了する必要があります。
詳しくは、Google Workspace アドオンを公開するをご覧ください。
Google Workspace アドオンの例
Google Workspace アドオンがどのように構成されているかを理解できるように、Google Workspace の「Cats」アドオン クイックスタートでは、ホームページ、カード ナビゲーション、サードパーティ サービスへの接続などのシンプルな Google Workspace アドオンを作成する方法を示します。クイックスタートが完了したら、アドオンをインストールしてコードをテストできます。