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

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

目標

• アドオンの機能を確認します。
• Apps Script を使用してアドオンを作成する方法と、Apps Script サービスの機能について説明します。
• 環境をセットアップする。
• スクリプトを設定します。
• スクリプトを実行します。

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

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

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

仕組み

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

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

Apps Script サービス

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

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

前提条件

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

• 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 同意画面を構成すると、ユーザーに表示される内容が定義され、後でアプリを公開できるようにアプリが登録されます。

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

   OAuth 同意画面に移動

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

4. ここではスコープの追加をスキップして、[保存して次へ] をクリックします。今後、Google Workspace 組織の外部で使用するアプリを作成する場合は、[ユーザータイプ] を [外部] に変更し、アプリに必要な認可スコープを追加する必要があります。

5. アプリ登録の概要を確認します。変更するには、[編集] をクリックします。アプリの登録に問題がなければ、[ダッシュボードに戻る] をクリックします。

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

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

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

   [認証情報] に移動

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

4. 後で使用できるように、API キーをメモしておきます。

スクリプトを設定する

以降のセクションでは、アドオンをビルドするためのスクリプトを設定します。

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

1. 次のボタンをクリックして、Google ブックスのリンクをプレビューする Apps Script プロジェクトを開きます。
   プロジェクトを開く
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. YOUR_API_KEY は、前のセクションで作成した Google ブックス API の API キーに置き換えます。
3. [Deploy]（デプロイ）> [Test deployments]（デプロイをテスト）をクリックします。
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 リファレンス ドキュメント