Melihat pratinjau link dari Google Buku dengan smart chip

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

Tujuan

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

Tentang add-on Google Workspace ini

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

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

Cara kerjanya

Dalam file manifest 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 Volume resource). Skrip menggunakan informasi ini untuk membuat chip smart 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:

• Layanan UrlFetch–Terhubung ke Google Books API untuk mendapatkan informasi tentang buku (yang merupakan instance dari resource Volume API).
• Layanan Kartu–Membuat antarmuka pengguna add-on.

Prasyarat

Untuk menggunakan sampel ini, Anda memerlukan prasyarat berikut:

• Akun Google (akun Google Workspace mungkin memerlukan persetujuan administrator).

• Browser web dengan akses ke internet.

• Project Google Cloud dengan akun penagihan terkait. Lihat Mengaktifkan penagihan untuk project.

Menyiapkan lingkungan Anda

Bagian berikut menyiapkan lingkungan Anda untuk membangun add-on.

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.

   Pilih 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.

• Di project Cloud Anda, aktifkan Books API.

  Aktifkan API

Mengonfigurasi layar izin OAuth

Add-on ini memerlukan project Cloud dengan layar izin yang dikonfigurasi. Mengonfigurasi layar izin OAuth menentukan konten yang ditampilkan Google kepada pengguna dan mendaftarkan aplikasi Anda sehingga Anda dapat memublikasikannya nanti.

1. Di Konsol Google Cloud, buka Menu menu > Google Auth platform > Branding.

   Buka Branding

2. Jika sudah mengonfigurasi Google Auth platform, Anda dapat mengonfigurasi setelan Layar Izin OAuth berikut di Branding, Audiens, dan Akses Data. Jika Anda melihat pesan yang bertuliskan Google Auth platform belum dikonfigurasi, klik Mulai:
1. Di bagian Informasi Aplikasi, di Nama aplikasi, masukkan nama untuk aplikasi.
2. Di Email dukungan pengguna, pilih alamat email dukungan yang dapat dihubungi pengguna jika mereka memiliki pertanyaan tentang izin mereka.
3. Klik Berikutnya.
4. Di bagian Audiens, pilih Internal.
5. Klik Berikutnya.
6. Di bagian Informasi Kontak, masukkan Alamat email tempat Anda dapat menerima notifikasi tentang perubahan apa pun pada project Anda.
7. Klik Berikutnya.
8. Di bagian Selesai, tinjau Kebijakan Data Pengguna Layanan Google API dan jika Anda setuju, pilih Saya setuju dengan Kebijakan Data Pengguna Layanan Google API.
9. Klik Lanjutkan.
10. Klik Buat.
3. Untuk saat ini, Anda dapat melewati penambahan cakupan. Pada masa mendatang, saat membuat aplikasi untuk digunakan di luar organisasi Google Workspace Anda, Anda harus mengubah Jenis pengguna menjadi Eksternal. Kemudian tambahkan cakupan otorisasi yang diperlukan aplikasi Anda. Untuk mempelajari lebih lanjut, lihat panduan Mengonfigurasi izin OAuth selengkapnya.

Mendapatkan kunci API untuk Google Books API

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

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

   Buka Kredensial

3. Klik Create credentials > API key.

4. Catat kunci API Anda untuk digunakan pada langkah selanjutnya.

Menyiapkan skrip

Bagian berikut menyiapkan skrip untuk membuat add-on.

Buat project Apps Script

1. Klik tombol berikut untuk membuka project Apps Script Preview links from Google Books.
   Membuka project
2. Klik info_outline Ringkasan.
3. Di halaman ringkasan, klik Buat salinan.
4. Di salinan project Apps Script Anda, buka file Code.gs dan ganti YOUR_API_KEY dengan kunci API yang Anda buat di bagian sebelumnya.

Menyalin nomor project Cloud

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

   Buka Setelan IAM & Admin

2. Di kolom Project number, salin nilai.

Menetapkan project Cloud untuk project Apps Script

1. Di project Apps Script Anda, klik Project Settings.
2. Pada Google Cloud Platform (GCP) Project, klik Change project.
3. Di GCP project number, tempelkan nomor project Google Cloud.
4. Klik Set project.

Menguji add-on

Bagian berikut akan menguji add-on yang Anda buat.

Menginstal deployment pengujian

1. Di project Apps Script Anda, klik code Editor.
2. Ganti YOUR_API_KEY dengan kunci API untuk Google Books API, yang dibuat di bagian sebelumnya.
3. Klik Deploy > Test deployments.
4. Klik Instal > Selesai.

Melihat pratinjau link di Google Dokumen

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. Arahkan kursor ke smart chip, dan saat diminta, izinkan akses untuk menjalankan add-on. Kartu pratinjau menampilkan informasi tentang buku.

Gambar berikut menampilkan pratinjau link:

Meninjau kode

Untuk meninjau kode Apps Script untuk add-on ini, klik Lihat kode sumber untuk meluaskan bagian:

{
  "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();
  }
}

Topik terkait

• Melihat pratinjau link dengan smart chip
• Dokumentasi referensi Google Books API