Google ドライブ インターフェースの構築

Google Workspace アドオンを使用すると、ユーザーが Google ドライブを使用しているときにカスタマイズされたインターフェースを提供できます。これにより、ユーザーに関連する追加情報を提供したり、タスクを自動化したり、サードパーティ システムを Google ドライブに接続したりできます。

アドオン UI へのアクセス

Google Workspace アドオンのアイコンがドライブのユーザー インターフェースの右側にあるアイコン列に表示されている場合は、Google ドライブでそのアドオンを開くことができます。Google Workspace アドオンでは、ホームページ インターフェース、アイテム選択インターフェース、またはその両方を定義できます。

  • ユーザーが Google ドライブでアドオン アイコンをクリックすると、アドオンは対応する drive.homepageTrigger 関数を実行します（存在する場合）。この関数は、ホームページ カードを作成して Google ドライブに返します。drive.homepageTrigger 関数が定義されていない場合、代わりに一般的なホームページ カードが表示されます。
  • ユーザーが Google ドライブで 1 つ以上のアイテムを選択し、アドオン アイコンをクリックするか、アドオンが開いているときにアイテムを選択すると、アドオンは対応する drive.onItemsSelectedTrigger コンテキスト関数（存在する場合）を実行します。この関数は、アドオンの Google ドライブのコンテキストに応じた「選択したアイテム」インターフェースをビルドし、Google ドライブに返して表示します。

アドオンの Google ドライブ インターフェースを構築する

Google ドライブを拡張するインターフェースを構築する一般的な手順は次のとおりです。

  1. アドオンにドライブ固有のホームページを設定するかを決定します。また、ユーザーがドライブのアイテムを選択したときにコンテキスト インターフェースを提供するかどうかも決定します。
  2. 必要な ドライブ スコープなど、適切な addOns.common フィールドと addOns.drive フィールドをアドオン スクリプト プロジェクトのマニフェストに追加します。
  3. ドライブ固有のホームページを提供する場合は、drive.homepageTrigger 関数を実装してこのインターフェースを構築します。複数の Google Workspace ホストに common.homepageTrigger インターフェースを使用することもできます。
  4. Drive のコンテキスト アイテム選択インターフェースを提供する場合は、このインターフェースを構築するためにコンテキスト トリガー関数 drive.onItemsSelectedTrigger を実装する必要があります。詳しくは、選択したアイテムのドライビング コンテキスト インターフェースをご覧ください。
  5. ボタンのクリックなどのユーザーの UI 操作に応答するために必要な関連するコールバック関数を実装します。

ドライブのホームページ

Google ドライブは、Google Workspace アドオンのホームページの表示をサポートしています。Google ドライブにアドオンの共通ホームページを表示するには、アドオンのマニフェストに addOns.drive フィールドがあることを確認します。

または、アドオン マニフェストに drive.homepageTrigger を追加して、ドライブ固有のホームページを指定します。

いずれの場合も、アドオンのスクリプト プロジェクトでホームページ トリガー関数の名前を指定する必要があります。この関数は、必要に応じて自動的に呼び出され、ドライブのホームページをビルドします。この関数を実装して、ホームページを構成する単一の Card オブジェクトまたは Card オブジェクトの配列を構築して返す必要があります。ホームページ トリガー関数には、クライアントのプラットフォームなどの一般的な情報を含むイベント オブジェクトがパラメータとして渡されます。イベント オブジェクトのデータを使用して、ホームページの作成をカスタマイズできます。

選択したアイテムの Google ドライブのコンテキスト インターフェース

Google ドライブは、コンテキスト トリガーを使用して、ユーザーが 1 つ以上の Google ドライブ アイテムを選択したときに表示するインターフェース（存在する場合）を決定します。トリガーがトリガーされると、アドオンのマニフェストの drive.onItemsSelectedTrigger.runFunction フィールドで指定されたコンテキスト トリガー関数が実行されます。

Drive のコンテキスト アイテム選択インターフェースを作成するには、次の操作を行う必要があります。

  1. アドオンのマニフェストに https://www.googleapis.com/auth/drive.addons.metadata.readonly スコープが含まれていることを確認します。

  2. マニフェストに drive.onItemsSelectedTrigger セクションが含まれていることを確認します。

  3. drive.onItemsSelectedTrigger フィールドに指定した名前の関数を実装します。この関数は、イベント オブジェクトを引数として受け取り、単一の Card オブジェクトまたは Card オブジェクトの配列を返す必要があります。

  4. 他のカードと同様に、インターフェースのウィジェット インタラクティビティに使用するコールバック関数を実装する必要があります。たとえば、インターフェースにボタンを追加する場合は、ボタンに関連付けられたアクションと、ボタンがクリックされたときに実行されるコールバック関数を実装する必要があります。

イベント オブジェクト

イベント オブジェクトが作成され、これらの関数が呼び出されると、drive.homepageTrigger または drive.onItemsSelectedTrigger トリガー関数に渡されます。トリガー関数は、このイベント オブジェクトの情報を使用して、アドオンカードの作成方法を決定したり、アドオンの動作を制御したりできます。

イベント オブジェクトの完全な構造については、イベント オブジェクトをご覧ください。アドオンのホストアプリとしてドライブが機能している場合、コンテキスト イベント オブジェクトには、ドライブ固有のクライアント情報を格納する ドライブ イベント オブジェクト フィールドが含まれます。

アイテム選択トリガーのコンテキスト ドライブ イベント オブジェクトには、トリガーが起動されたときにユーザーが選択したアイテムに関する情報が含まれます。ユーザーがドライブで複数のアイテムを選択すると、そのうちの 1 つが主な関心の対象と見なされます。このアイテムはアクティブなカーソル アイテムと呼ばれます。

次の例は、drive.onItemsSelectedTrigger 関数に渡される ドライブ イベント オブジェクトを示しています。

    {
      "commonEventObject": { ... },
      "drive": {
        "activeCursorItem":{
          "addonHasFileScopePermission": true,
          "id":"0B_sX1fXRRU6Ac3RhcnRlcl9maWxl",
          "iconUrl": "https://drive-thirdparty.googleusercontent.com...",
          "mimeType":"application/pdf",
          "title":"How to get started with Drive"
        },
        "selectedItems": [
          {
            "addonHasFileScopePermission": true,
            "id":"0B_sX1fXRRU6Ac3RhcnRlcl9maWxl",
            "iconUrl":"https://drive-thirdparty.googleusercontent.com...",
            "mimeType":"application/pdf",
            "title":"How to get started with Drive"
          },
          ...
        ]
      },
      ...
    }