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

Kodlama seviyesi: Orta
Süre: 30 dakika
Proje türü: Google Workspace Eklentisi

Hedefler

• Eklentinin işlevini anlayın.
• Apps Komut Dosyası'nı kullanarak eklenti derlemeyi ve Apps Komut Dosyası hizmetlerinin neler yaptığı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, bir Google Dokümanlar dokümanında Google Kitaplar'daki bağlantıları önizleyen 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 bir bağlantı önizlemesini tetikler. Bağlantıyı önizlemek için bağlantıyı akıllı çipe dönüştürebilir ve fareyle bağlantının üzerine gelerek kitap hakkında daha fazla bilgi gösteren bir kart görüntüleyebilirsiniz.

Bu eklenti, Google Books API'ye bağlanmak ve Google Dokümanlar'da görüntülenmek üzere Google Kitaplar ile ilgili bilgileri 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 (https://books.google.com) belirli kalıplarla eşleşen URL'lerin bağlantı önizlemelerini tetikleyecek şekilde yapılandırır.

Kod dosyasında, komut dosyası Google Books API'ye bağlanır ve kitap hakkında bilgi almak için URL'yi kullanır (bu, Volume kaynağının örneğidir). Komut dosyası, bu bilgileri kullanarak kitabın başlığını görüntüler. Akıllı çiple birlikte özet, sayfa sayısı, kitap kapağının resmi ve puan sayısını gösteren bir önizleme kartı oluşturulur.

Apps Komut Dosyası hizmetleri

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

• UrlFetch hizmeti: Kitaplar hakkında bilgi almak için Google Books API'ye bağlanır (API'nin Volume kaynağının örnekleridir).
• Kart hizmeti: Eklentinin kullanıcı arayüzünü oluşturur.

Ön koşullar

Bu örneği kullanmak için aşağıdaki önkoşullara ihtiyacınız vardır:

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

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

• İlişkilendirilmiş bir faturalandırma hesabı olan bir Google Cloud projesi. Proje için faturalandırmayı etkinleştirme başlıklı makaleyi inceleyin.

Ortamınızı ayarlama

Google Cloud Console'da Cloud projenizi açma

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

1. Google Cloud konsolunda Proje seçin sayfasına gidin.

   Bir Cloud projesi seçin

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

Google Books API'yi açma

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

• Cloud projenizde Books API'yi etkinleştirin.

  API'yi etkinleştirme

OAuth izin ekranını yapılandırın

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

1. Google Cloud konsolunda Menü menu > API'ler ve Hizmetler > OAuth izin ekranı'na gidin.

   OAuth izin ekranına gidin

2. Kullanıcı türü için Dahili'yi seçin ve Oluştur'u tıklayın.
3. Uygulama kayıt formunu doldurun, ardından Kaydet ve Devam Et'i tıklayın.

4. Şimdilik kapsam eklemeyi atlayıp Kaydet ve Devam Et'i tıklayabilirsiniz. Gelecekte Google Workspace kuruluşunuzun dışında kullanmak için bir uygulama oluşturduğunuzda Kullanıcı türü'nü Harici olarak değiştirmeniz ve uygulamanızın gerektirdiği yetkilendirme kapsamlarını eklemeniz gerekir.

5. Uygulama kaydı özetinizi inceleyin. Değişiklik yapmak için Düzenle'yi tıklayın. Uygulama kaydı sorunsuz görünüyorsa Kontrol Paneline Dön'ü tıklayın.

Google Books API için API anahtarı alma

1. Google Cloud Console'a gidin. Faturalandırmanın etkin olduğu projenizin açık olduğundan emin olun.

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

   Kimlik Bilgileri'ne git

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

4. Daha sonraki bir adımda kullanmak üzere API anahtarınızı not edin.

Komut dosyasını kurma

Apps Komut Dosyası projesini oluşturma

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

Cloud proje numarasını kopyalayın

1. Google Cloud konsolunda Menü menu > IAM ve Yönetici > Ayarlar'a gidin.

   IAM ve Yönetici Ayarları'na git

2. Proje numarası alanına değeri kopyalayın.

Apps Komut Dosyası projesinin Cloud projesini ayarlayın

1. Apps Komut Dosyası projenizde, Proje Ayarları'nı tıklayın.
2. Google Cloud Platform (GCP) Project (Google Cloud Platform (GCP) Projesi) bölümünde Change project (Projeyi değiştir) seçeneğini tıklayın.
3. GCP proje numarası alanına Google Cloud proje numarasını yapıştırın.
4. Proje ayarla'yı tıklayın.

Eklentiyi test etme

Test dağıtımı yükleme

1. Apps Komut Dosyası projenizde, code Düzenleyici'yi tıklayın.
2. Code.gs dosyasını açın ve Çalıştır'ı tıklayın. İstendiğinde komut dosyasını yetkilendirin.
3. Dağıt > Dağıtımları test et'i tıklayın.
4. Yükle > Bitti'yi tıklayın.

Google Dokümanlar'da bir bağlantıyı önizleme

1. docs.new adresinde bir Google Dokümanlar dokümanı oluşturun.
2. Aşağıdaki URL'yi dokümana yapıştırın ve sekme tuşuna basarak URL'yi akıllı çipe dönüştürün: https://www.google.com/books/edition/Software_Engineering_at_Google/V3TTDwAAQBAJ
3. İşaretçiyi akıllı çipin üzerinde tutun ve istendiğinde eklentiyi çalıştırmak için erişim yetkisi verin. Önizleme kartında kitapla ilgili bilgiler görüntülenir.

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

Kodu inceleyin

Bu eklentinin Apps Komut Dosyası kodunu incelemek için aşağıdaki Kaynak kodunu görüntüle'yi tıklayın:

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

Sonraki adımlar

• Bağlantıları akıllı çiplerle önizleme
• Google Books API referans dokümanları