Melihat pratinjau link dari Google Buku dengan smart chip

Level coding: Menengah
Durasi: 30 menit
Jenis project: Add-on Google Workspace

Tujuan

  • Pahami fungsi add-on.
  • Memahami cara membuat add-on menggunakan Apps Script, dan memahami fungsi layanan Apps Script.
  • Menyiapkan lingkungan Anda.
  • Siapkan skrip.
  • Jalankan skrip.

Tentang Add-on Google Workspace ini

Dalam contoh ini, Anda membuat Add-on Google Workspace yang mempratinjau link dari Google Buku dalam dokumen Google Dokumen. Saat Anda mengetik atau menempelkan URL Google Buku ke dokumen, add-on akan mengenali link dan memicu pratinjau link. Untuk melihat pratinjau link, Anda dapat mengonversi link menjadi smart chip dan mengarahkan kursor ke link untuk melihat kartu yang menampilkan informasi selengkapnya tentang buku tersebut.

Add-on ini menggunakan UrlFetch Service Apps Script untuk terhubung ke Google Books API dan mendapatkan informasi tentang Google Buku untuk ditampilkan di Google Dokumen.

Cara kerjanya

Dalam file manifes Add-on Google Workspace, skrip mengonfigurasi add-on untuk memperluas Google Dokumen dan memicu pratinjau link untuk URL yang cocok dengan pola tertentu dari situs Google Buku (https://books.google.com).

Dalam file kode, skrip terhubung ke Google Books API dan menggunakan URL untuk mendapatkan informasi tentang buku (yang merupakan instance dari resource Volume). Skrip menggunakan informasi ini untuk menghasilkan smart chip yang menampilkan judul buku dan kartu pratinjau yang menampilkan ringkasan, jumlah halaman, gambar sampul buku, dan jumlah rating.

Layanan Apps Script

Add-on ini menggunakan layanan berikut:

Prasyarat

Untuk menggunakan sampel ini, Anda memerlukan prasyarat berikut:

Menyiapkan lingkungan Anda

Buka project Cloud Anda di konsol Google Cloud

Jika belum terbuka, buka project Cloud yang ingin Anda gunakan untuk contoh ini:

  1. Di konsol Google Cloud, buka halaman Select a project.

    Memilih project Cloud

  2. Pilih project Google Cloud yang ingin Anda gunakan. Atau, klik Buat project dan ikuti petunjuk di layar. Jika membuat project Google Cloud, Anda mungkin perlu mengaktifkan penagihan untuk project tersebut.

Mengaktifkan Google Books API

Add-on ini terhubung ke Google Books API. Sebelum menggunakan Google API, Anda harus mengaktifkannya di project Google Cloud. Anda dapat mengaktifkan satu atau beberapa API dalam satu project Google Cloud.

Add-on ini memerlukan project Cloud dengan layar izin yang telah dikonfigurasi. Mengonfigurasi layar izin OAuth akan menentukan apa yang ditampilkan Google kepada pengguna dan mendaftarkan aplikasi Anda agar dapat dipublikasikan nanti.

  1. Di konsol Google Cloud, buka Menu > APIs & Services > OAuth consent screen.

    Buka layar izin OAuth

  2. Untuk Jenis pengguna, pilih Internal, lalu klik Buat.
  3. Lengkapi formulir pendaftaran aplikasi, lalu klik Simpan dan Lanjutkan.

  4. Untuk saat ini, Anda dapat melewati penambahan cakupan dan mengklik Simpan dan Lanjutkan. Pada masa mendatang, saat membuat aplikasi untuk digunakan di luar organisasi Google Workspace, Anda harus mengubah User type menjadi External, lalu tambahkan cakupan otorisasi yang diperlukan aplikasi Anda.

  5. Tinjau ringkasan pendaftaran aplikasi Anda. Untuk melakukan perubahan, klik Edit. Jika pendaftaran aplikasi terlihat baik-baik saja, klik Back to Dashboard.

Mendapatkan kunci API untuk Google Books API

  1. Buka Konsol Google Cloud. Pastikan project Anda yang mendukung penagihan terbuka.

  2. Di konsol Google Cloud, buka Menu > APIs & Services > Credentials.

    Buka Kredensial

  3. Klik Create credentials > API key.

  4. Catat kunci API Anda untuk digunakan di langkah berikutnya.

Menyiapkan skrip

Membuat project Apps Script

  1. Klik tombol berikut untuk membuka project Apps Script Link pratinjau dari Google Buku.
    Buka project
  2. Klik Ringkasan.
  3. Di halaman ringkasan, klik Ikon untuk membuat salinan Buat salinan.
  4. Dalam salinan project Apps Script Anda, buka file Code.gs dan ganti YOUR_API_KEY dengan kunci API yang Anda buat di bagian sebelumnya.

Salin nomor project Cloud

  1. Di konsol Google Cloud, buka Menu > IAM & Admin > Settings.

    Buka IAM & Admin Settings

  2. Di kolom Project number, salin nilainya.

Menetapkan project Cloud project Apps Script

  1. Di project Apps Script, klik Ikon untuk setelan project Setelan Project.
  2. Pada Google Cloud Platform (GCP) Project, klik Change project.
  3. Di GCP project number, tempel nomor project Google Cloud.
  4. Klik Set project.

Menguji add-on

Menginstal deployment pengujian

  1. Di project Apps Script, klik Editor.
  2. Buka file Code.gs, lalu klik Run. Jika diminta, izinkan skrip.
  3. Klik Deploy > Uji deployment.
  4. Klik Instal > Selesai.
  1. Buat dokumen Google Dokumen di docs.new.
  2. Tempel URL berikut ke dokumen, lalu tekan tombol tab untuk mengonversi URL menjadi smart chip: https://www.google.com/books/edition/Software_Engineering_at_Google/V3TTDwAAQBAJ
  3. Tahan kursor ke smart chip, dan jika diminta, izinkan akses untuk menjalankan add-on. Kartu pratinjau menampilkan informasi tentang buku.

Gambar berikut menampilkan pratinjau link:

Pratinjau link buku, Software Engineering di Google.

Meninjau kode

Guna meninjau kode Apps Script untuk add-on ini, klik Lihat kode sumber di bawah:

Melihat kode sumber

appsscript.json

solutions/add-on/book-smartchip/appsscript.json
{
  "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"
          }
        }
      ]
    }
  }
}

Code.gs

solutions/add-on/book-smartchip/Code.js
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();
  }
}

Langkah berikutnya