Google Kitaplar'daki bağlantıları akıllı çiplerle önizleme

Kodlama düzeyi: Orta
Süre: 30 dakika
Proje türü: Google Workspace eklentisi

Hedefler

  • Eklentinin ne işe yaradığını öğrenin.
  • Apps Komut Dosyası'nı kullanarak nasıl eklenti oluşturacağınızı ve Apps Komut Dosyası hizmetlerinin ne işe yaradığını öğrenin.
  • Ortamınızı ayarlayın.
  • Komut dosyasını ayarlayın.
  • Komut dosyasını çalıştırın.

Bu Google Workspace eklentisi hakkında

Bu örnekte, Google Kitaplar'daki bağlantıların önizlemesini bir Google Dokümanlar dokümanında gösteren bir Google Workspace eklentisi oluşturacaksınız. Bir dokümana Google Kitaplar URL'si yazdığınızda veya yapıştırdığınızda eklenti, bağlantıyı tanır ve bağlantı önizlemesini tetikler. Bağlantıyı önizlemek için bağlantıyı akıllı çipe dönüştürebilir ve imleci bağlantının üzerine getirerek kitap hakkında daha fazla bilgi gösteren bir kartı görüntüleyebilirsiniz.

Bu eklenti, Google Kitaplar API'sine bağlanmak ve Google Dokümanlar'da görüntülemek üzere Google Kitaplar hakkında bilgi almak için Apps Komut Dosyası'nın UrlFetch Hizmeti'ni kullanır.

İşleyiş şekli

Google Workspace eklentisinin manifest dosyasında komut dosyası, eklentiyi Google Dokümanlar'ı genişletecek ve Google Kitaplar web sitesindeki belirli kalıplara uyan URL'ler için bağlantı önizlemelerini tetikleyecek şekilde yapılandırır (https://books.google.com).

Kod dosyasında, komut dosyası Google Kitaplar API'sine bağlanır ve kitapla ilgili bilgileri almak için URL'yi kullanır (bu, Volume<0x0x0A>kaynağının bir örneğidir). Komut dosyası, bu bilgileri kullanarak kitabın başlığını gösteren bir akıllı çip ve özet, sayfa sayısı, kitap kapağının resmi ve derecelendirme sayısını gösteren bir önizleme kartı oluşturur.

Apps Komut Dosyası hizmetleri

Bu eklenti aşağıdaki hizmetleri kullanır:

Ön koşullar

Bu örneği kullanmak için aşağıdaki ön koşulları karşılamanız gerekir:

  • Google Hesabı (Google Workspace hesapları için yönetici onayı gerekebilir).

  • İnternete erişimi olan bir web tarayıcısı.

  • Bir Google Cloud projesi.

Ortamınızı ayarlama

Aşağıdaki bölümlerde, eklentiyi oluşturmak için ortamınız ayarlanır.

Cloud projenizi Google Cloud Console'da açın.

Henüz açık değilse bu örnek için kullanmayı planladığınız Cloud projesini açın:

  1. Google Cloud Console'da Proje seçin sayfasına gidin.

    Bir bulut projesi seçin

  2. Kullanmak istediğiniz Google Cloud projesini seçin. Alternatif olarak, Proje oluştur'u tıklayıp ekrandaki talimatları uygulayın. Google Cloud projesi oluşturursanız proje için faturalandırmayı etkinleştirmeniz gerekebilir.

Google Books API'yi etkinleştirme

Bu eklenti, Google Books API'ye bağlanır. Google API'lerini kullanmadan önce bir Google Cloud projesinde etkinleştirmeniz gerekir. Tek bir Google Cloud projesinde bir veya daha fazla API'yi etkinleştirebilirsiniz.

Bu eklenti, yapılandırılmış izin ekranına sahip bir Cloud projesi gerektirir. OAuth izin ekranını yapılandırmak, Google'ın kullanıcılara ne göstereceğini tanımlar ve uygulamanızı daha sonra yayınlayabilmeniz için kaydeder.

  1. Google Cloud Console'da Menü > Google Auth platform > Markalama'ya gidin.

    Markalama'ya gidin.

  2. Google Auth platformyapılandırdıysanız Markalama, Kitle ve Veri Erişimi'nde aşağıdaki OAuth kullanıcı rızası ekranı ayarlarını yapılandırabilirsiniz. Google Auth platform henüz yapılandırılmadı mesajını görürseniz Başlayın'ı tıklayın:
    1. Uygulama Bilgileri bölümündeki Uygulama adı alanına uygulamanın adını girin.
    2. Kullanıcı destek e-postası bölümünde, kullanıcıların rızalarıyla ilgili soruları olduğunda sizinle iletişime geçebileceği bir destek e-posta adresi seçin.
    3. İleri'yi tıklayın.
    4. Kitle bölümünde Şirket içi'ni seçin.
    5. İleri'yi tıklayın.
    6. İletişim bilgileri bölümünde, projenizde yapılan değişikliklerle ilgili bildirim alabileceğiniz bir e-posta adresi girin.
    7. İleri'yi tıklayın.
    8. Bitir bölümünde Google API Hizmetleri Kullanıcı Verileri Politikası'nı inceleyin ve kabul ediyorsanız Google API Hizmetleri: Kullanıcı Verileri Politikası'nı kabul ediyorum'u seçin.
    9. Devam'ı tıklayın.
    10. Oluştur'u tıklayın.
  3. Şimdilik kapsam eklemeyi atlayabilirsiniz. Gelecekte Google Workspace kuruluşunuzun dışında kullanılacak bir uygulama oluşturduğunuzda Kullanıcı türü'nü Harici olarak değiştirmeniz gerekir. Ardından, uygulamanızın gerektirdiği yetkilendirme kapsamlarını ekleyin. Daha fazla bilgi için OAuth iznini yapılandırma başlıklı kılavuzun tamamını inceleyin.

Google Books API için API anahtarı alma

  1. Google Cloud Console'a gidin. Faturalandırmanın etkinleştirildiği projenizin açık olduğundan emin olun.

  2. Google Cloud Console'da Menü > API'ler ve Hizmetler > Kimlik Bilgileri'ne gidin.

    Kimlik Bilgileri'ne gidin

  3. Kimlik bilgileri oluştur > API anahtarı'nı tıklayın.

  4. Sonraki adımda kullanmak üzere API anahtarınızı not alın.

Komut dosyasını ayarlama

Aşağıdaki bölümlerde, eklentiyi oluşturmak için komut dosyası ayarlanır.

Apps Komut Dosyası projesini oluşturma

  1. Google Kitaplar'daki bağlantıları önizleme Apps Komut Dosyası projesini açmak için aşağıdaki düğmeyi tıklayın.
    Projeyi açın
  2. Genel bakış'ı tıklayın.
  3. Genel bakış sayfasında Kopya oluşturma simgesi Kopya oluştur'u tıklayın.
  4. Apps Komut Dosyası projesinin kopyasında Code.gs dosyasına gidin ve YOUR_API_KEY bölümünü önceki bölümde oluşturduğunuz API anahtarıyla değiştirin.

Gelecekte belirli Google API'lerini kullanmak veya uygulamanızı yayınlamak isterseniz Cloud projenizi Apps Komut Dosyası projenizle ilişkilendirmeniz gerekir. Bu kılavuz için bunu yapmanız gerekmez. Daha fazla bilgi edinmek için Google Cloud projeleri kılavuzuna bakın.

Eklentiyi test etme

Aşağıdaki bölümlerde, oluşturduğunuz eklenti test edilir.

Test dağıtımı yükleme

  1. Apps Komut Dosyası projenizde Düzenleyici'yi tıklayın.
  2. Dağıt > Test dağıtımları'nı tıklayın.
  3. Yükle > Bitti'yi tıklayın.
  1. docs.new adresinde bir Google Dokümanı oluşturun.
  2. Aşağıdaki URL'yi dokümana yapıştırın ve URL'yi akıllı çipe dönüştürmek için sekme tuşuna basın: https://www.google.com/books/edition/Software_Engineering_at_Google/V3TTDwAAQBAJ
  3. İşaretçiyi akıllı çipin üzerine getirin ve istendiğinde eklentiyi çalıştırmak için erişimi yetkilendirin. Önizleme kartında kitapla ilgili bilgiler gösterilir.

Aşağıdaki resimde bağlantı önizlemesi gösterilmektedir:

Google&#39;da Yazılım Mühendisliği adlı kitabın bağlantı önizlemesi.

Kodu inceleme

Bu eklentinin Apps Komut Dosyası kodunu incelemek için Kaynak kodu görüntüle'yi tıklayarak bölümü genişletin:

Kaynak kodu göster

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
/**
 * Copyright 2025 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

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