スマートチップを使用して Google ブックスからのリンクをプレビューする

コーディング レベル: 中級
所要時間: 30 分
プロジェクトの種類: Google Workspace アドオン

目標

• アドオンの機能を理解します。
• Apps Script を使用してアドオンを作成する方法を理解し、Apps Script サービスの仕組みを理解します。
• 環境を設定する。
• スクリプトを設定します。
• スクリプトを実行します。

この Google Workspace アドオンについて

このサンプルでは、Google ドキュメント ドキュメント内の Google ブックスのリンクをプレビューする Google Workspace アドオンを作成します。Google ブックスの URL をドキュメントに入力または貼り付けると、アドオンがリンクを認識し、リンク プレビューをトリガーします。リンクをプレビューするには、リンクをスマートチップに変換し、リンクにカーソルを合わせると、書籍の詳細情報がカードに表示されます。

このアドオンは、Apps Script の UrlFetch Service を使用して Google Books API に接続し、Google ブックスに関する情報を取得して、Google ドキュメントに表示します。

仕組み

Google Workspace アドオンのマニフェスト ファイルでは、このスクリプトがアドオンを構成して、Google ドキュメントを拡張し、Google ブックスのウェブサイト（https://books.google.com）の特定のパターンに一致する URL に対してリンクのプレビューをトリガーします。

コードファイルで、スクリプトは Google Books API に接続し、URL を使用して書籍に関する情報（Volume リソースのインスタンス）を取得します。このスクリプトは、この情報を使用して、書籍のタイトルを表示するスマートチップと、概要、ページ数、書籍の表紙の画像、評価数を表示するプレビュー カードを生成します。

Apps Script サービス

このアドオンでは、次のサービスを使用します。

• UrlFetch サービス - Google Books API に接続して、書籍に関する情報（API の Volume リソースのインスタンス）を取得します。
• カードサービス - アドオンのユーザー インターフェースを作成します。

前提条件

このサンプルを使用するには、次の前提条件を満たす必要があります。

• Google アカウント（Google Workspace アカウントの場合、管理者の承認が必要になる場合があります）。

• インターネットにアクセスできるウェブブラウザ。

• 請求先アカウントが関連付けられた Google Cloud プロジェクト。プロジェクトの課金を有効にするをご覧ください。

環境を設定する

Google Cloud コンソールで Cloud プロジェクトを開く

まだ開いていない場合は、このサンプルで使用する Cloud プロジェクトを開きます。

1. Google Cloud コンソールで [プロジェクトの選択] ページに移動します。

   Cloud プロジェクトを選択

2. 使用する Google Cloud プロジェクトを選択します。または、[プロジェクトを作成] をクリックし、画面の指示に従います。Google Cloud プロジェクトを作成する場合は、プロジェクトの課金を有効にすることが必要な場合があります。

Google Books API を有効にする

このアドオンは Google Books API に接続します。 Google API を使用する前に、Google Cloud プロジェクトで API を有効にする必要があります。1 つの Google Cloud プロジェクトで 1 つ以上の API を有効にできます。

• Cloud プロジェクトで Books API を有効にします。

  API を有効にする

OAuth 同意画面を構成する

このアドオンには、同意画面が構成された Cloud プロジェクトが必要です。OAuth 同意画面を構成すると、Google がユーザーに表示する内容を定義し、後で公開できるようにアプリを登録します。

1. Google Cloud コンソールで、メニュー menu > [API とサービス] > [OAuth 同意画面] に移動します。

   OAuth 同意画面に移動

2. [ユーザーの種類] で [内部] を選択し、[作成] をクリックします。
3. アプリ登録フォームに入力し、[保存して次へ] をクリックします。

4. 現時点では、スコープの追加をスキップして、[Save and Continue] をクリックします。今後、Google Workspace 組織外で使用するアプリを作成する場合は、[ユーザータイプ] を [外部] に変更してから、アプリに必要な認証スコープを追加する必要があります。

5. アプリ登録の概要を確認します。変更するには、[編集] をクリックします。アプリ登録に問題がない場合は、[Back to Dashboard] をクリックします。

Google Books API の API キーを取得する

1. Google Cloud コンソールに移動します。 課金が有効になっているプロジェクトが開いていることを確認します。

2. Google Cloud コンソールで、メニュー menu > [API とサービス] > [認証情報] に移動します。

   [認証情報] に移動

3. [認証情報を作成] > [API キー] をクリックします。

4. 後のステップで使用するために、API キーをメモしておきます。

スクリプトを設定する

Apps Script プロジェクトを作成する

1. 次のボタンをクリックして、Apps Script プロジェクト「Google ブックスからのプレビュー リンク」を開きます。
   プロジェクトを開く
2. [info_outline 概要] をクリックします。
3. 概要ページで [ コピーを作成] をクリックします。
4. Apps Script プロジェクトのコピーで、Code.gs ファイルに移動し、YOUR_API_KEY を前のセクションで生成した API キーに置き換えます。

Cloud プロジェクト番号をコピーする

1. Google Cloud コンソールで、メニュー menu > [IAM と管理] > [設定] に移動します。

   [IAM と管理] の設定に移動

2. [プロジェクト番号] フィールドで、値をコピーします。

Apps Script プロジェクトの Cloud プロジェクトを設定する

1. Apps Script プロジェクトで、 [プロジェクトの設定] をクリックします。
2. [Google Cloud Platform（GCP）プロジェクト] で、[プロジェクトを変更] をクリックします。
3. [GCP のプロジェクト番号] に、Google Cloud のプロジェクト番号を貼り付けます。
4. [プロジェクトを設定] をクリックします。

アドオンをテストする

テストデプロイをインストールする

1. Apps Script プロジェクトで、code [エディタ] をクリックします。
2. Code.gs ファイルを開き、[Run] をクリックします。プロンプトが表示されたら、スクリプトを承認します。
3. [デプロイ] > [デプロイをテスト] をクリックします。
4. [インストール] > [完了] をクリックします。

Google ドキュメントでリンクをプレビューする

1. docs.new で Google ドキュメント ドキュメントを作成します。
2. 次の URL をドキュメントに貼り付け、Tab キーを押して URL をスマートチップに変換します。 https://www.google.com/books/edition/Software_Engineering_at_Google/V3TTDwAAQBAJ
3. スマートチップの上にポインタを置き、プロンプトが表示されたら、アドオンを実行するためのアクセスを承認します。プレビュー カードには、書籍に関する情報が表示されます。

次の画像は、リンクのプレビューです。

コードを確認する

このアドオンの Apps Script コードを確認するには、下の [ソースコードを表示] をクリックします。

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://www.googleapis.com/auth/workspace.linkpreview",
    "https://www.googleapis.com/auth/script.external_request"
  ],
  "urlFetchWhitelist": [
    "https://www.googleapis.com/books/v1/volumes/"
  ],
  "addOns": {
    "common": {
      "name": "Preview Books Add-on",
      "logoUrl": "https://developers.google.com/workspace/add-ons/images/library-icon.png",
      "layoutProperties": {
        "primaryColor": "#dd4b39"
      }
    },
    "docs": {
      "linkPreviewTriggers": [
        {
          "runFunction": "bookLinkPreview",
          "patterns": [
            {
              "hostPattern": "*.google.*",
              "pathPrefix": "books"
            },
            {
              "hostPattern": "*.google.*",
              "pathPrefix": "books/edition"
            }
          ],
          "labelText": "Book",
          "logoUrl": "https://developers.google.com/workspace/add-ons/images/book-icon.png",
          "localizedLabelText": {
            "es": "Libros"
          }
        }
      ]
    }
  }
}

function getBook(id) {
  const apiKey = 'YOUR_API_KEY'; // Replace with your API key
  const apiEndpoint = `https://www.googleapis.com/books/v1/volumes/${id}?key=${apiKey}&country=US`;
  const response = UrlFetchApp.fetch(apiEndpoint);
  return JSON.parse(response);
}

function bookLinkPreview(event) {
 if (event.docs.matchedUrl.url) {
    const segments = event.docs.matchedUrl.url.split('/');
    const volumeID = segments[segments.length - 1];

    const bookData = getBook(volumeID);
    const bookTitle = bookData.volumeInfo.title;
    const bookDescription = bookData.volumeInfo.description;
    const bookImage = bookData.volumeInfo.imageLinks.small;
    const bookAuthors = bookData.volumeInfo.authors;
    const bookPageCount = bookData.volumeInfo.pageCount;

    const previewHeader = CardService.newCardHeader()
      .setSubtitle('By ' + bookAuthors)
      .setTitle(bookTitle);

    const previewPages = CardService.newDecoratedText()
      .setTopLabel('Page count')
      .setText(bookPageCount);

    const previewDescription = CardService.newDecoratedText()
      .setTopLabel('About this book')
      .setText(bookDescription).setWrapText(true);

    const previewImage = CardService.newImage()
      .setAltText('Image of book cover')
      .setImageUrl(bookImage);

    const buttonBook = CardService.newTextButton()
      .setText('View book')
      .setOpenLink(CardService.newOpenLink()
        .setUrl(event.docs.matchedUrl.url));

    const cardSectionBook = CardService.newCardSection()
      .addWidget(previewImage)
      .addWidget(previewPages)
      .addWidget(CardService.newDivider())
      .addWidget(previewDescription)
      .addWidget(buttonBook);

    return CardService.newCardBuilder()
    .setHeader(previewHeader)
    .addSection(cardSectionBook)
    .build();
  }
}

次のステップ

• スマートチップを使用してリンクをプレビューする
• Google Books API リファレンス ドキュメント