Classroom eklentisi oluşturma

Bu, Classroom eklentileri serisinin ilk adım adım açıklamalı kılavuzudur.

Bu adım adım açıklamalı kılavuzda, bir web uygulaması geliştirmek ve bunu bir Classroom eklentisi olarak yayınlamak için gereken temeli hazırlıyorsunuz. Gelecekteki adım adım açıklamalı adımlarda bu uygulama genişletilecektir.

Bu adım adım açıklamalı kılavuzda aşağıdakileri tamamlarsınız:

• Web uygulamanız için yeni bir Google Cloud projesi oluşturun.
• Yer tutucu oturum açma düğmeleri içeren bir iskelet web uygulaması oluşturun.
• Web uygulamanız için gizli bir Google Workspace Marketplace (GWM) Mağaza Girişi yayınlayın.

Bu işlem tamamlandıktan sonra eklentinizi, Classroom eklentileri iframe'ine yükleyebilirsiniz.

Önemli: Bu adım adım açıklamalı kılavuzları uygulamadan önce proje yapılandırma kılavuzunu okuyun ve geliştirici yolculuğunun 1-6. adımlarını tamamlayın.

Ön koşullar

Uygun ön koşulları görmek için aşağıdan bir dil seçin:

Python

Python örneğimizde Flask çerçevesi kullanılmaktadır. Tüm adım adım açıklamalı kılavuzlar için kaynak kodun tamamını Genel Bakış sayfasından indirebilirsiniz. Bu adım adım açıklamalı kılavuzun kodunu /flask/01-basic-app/ dizininde bulabilirsiniz.

Gerekirse Python 3.7 ve sonraki sürümleri yükleyin ve pip sürümünün kullanılabilir olduğundan emin olun.

python -m ensurepip --upgrade

Ayrıca yeni bir Python sanal ortamı oluşturup etkinleştirmenizi de öneririz.

python3 -m venv .classroom-addon-env
source .classroom-addon-env/bin/activate

İndirilen örneklerdeki her adım adım açıklamalı kılavuz alt dizini bir requirements.txt içerir. Gerekli kitaplıkları pip kullanarak hızlıca yükleyebilirsiniz. Bu adım adım açıklamalı kılavuzda gerekli kitaplıkları yüklemek için aşağıdaki yöntemi kullanın.

cd flask/01-basic-app
pip install -r requirements.txt

Node.js

Node.js örneğimizde Express çerçevesi kullanılmıştır. Tüm adım adım açıklamalı kılavuzlar için kaynak kodun tamamını Genel Bakış sayfasından indirebilirsiniz.

Gerekirse NodeJS v16.13+ sürümünü yükleyin.

Gerekli düğüm modüllerini npm kullanarak yükleyin.

npm install

Java

Java örneğimizde Spring Boot çerçevesi kullanılmıştır. Tüm adım adım açıklamalı kılavuzlar için kaynak kodun tamamını Genel Bakış sayfasından indirebilirsiniz.

Makinenizde yüklü değilse Java 11 ve sonraki sürümleri yükleyin.

Spring Boot uygulamaları, derlemeleri işlemek ve bağımlılıkları yönetmek için Gradle veya Maven'i kullanabilir. Bu örnek, Maven'in kendisini yüklemenize gerek kalmadan başarılı bir derleme sağlayan Maven sarmalayıcısını içerir.

Verdiğimiz örneği çalıştırabilmek için projeyi indirdiğiniz dizinde aşağıdaki komutları çalıştırarak projeyi çalıştırmak için gerekli ön koşullara sahip olduğunuzdan emin olun.

java --version
./mvnw --version

Veya Windows'da:

java -version
mvnw.cmd --version

Google Cloud projesi oluşturun

Classroom API'ye erişim ve gerekli kimlik doğrulama yöntemleri, Google Cloud projeleri tarafından kontrol edilir. Aşağıdaki talimatlar, eklentinizle kullanmak üzere yeni bir proje oluşturmak ve yapılandırmak için gereken minimum adımları açıklar.

Projeyi oluşturma

Proje oluşturma sayfasını ziyaret ederek yeni bir Google Cloud projesi oluşturun. Yeni proje için herhangi bir ad girebilirsiniz. Oluştur'u tıklayın.

Yeni projenin tamamen oluşturulması birkaç dakika sürer. İşiniz bittiğinde projeyi seçtiğinizden emin olun. Projeyi ekranın üst kısmındaki proje seçici açılır menüsünden seçebilir veya sağ üstteki bildirim menüsünden PROJE SEÇ'i tıklayabilirsiniz.

Önemli: Devam etmeden önce doğru projeyi seçtiğinizden emin olun.

GWM SDK'sını Google Cloud projesine ekleyin

API Kitaplığı tarayıcısına gidin. Google Workspace Marketplace SDK araması yapın. Sonuç listesinde SDK'yı görürsünüz.

Google Workspace Marketplace SDK kartını seçin, ardından Etkinleştir'i tıklayın.

GWM SDK'sını yapılandırma

GWM, kullanıcıların ve yöneticilerin eklentinizi yüklemek için kullanacağı girişi sağlar. Devam etmek için OAuth İzin Ekranı'nı ve GWM SDK'sının Uygulama Yapılandırması ve Mağaza Girişi'ni yapılandırın.

OAuth İzin Ekranı

OAuth İzin Ekranı, kullanıcılar uygulamanızı ilk kez yetkilendirdiğinde görünür. Kullanıcılardan, etkinleştirdiğiniz kapsamların belirlediği şekilde uygulamanızın kişisel ve hesap bilgilerine erişmesine izin vermeleri istenir.

OAuth izin ekranı oluşturma sayfasına gidin. Aşağıdaki bilgileri sağlayın:

• User Type (Kullanıcı Türü) için External (Harici) seçeneğini belirleyin. Create'i (Oluştur) tıklayın.
• Bir sonraki sayfada gerekli uygulama ayrıntılarını ve iletişim bilgilerini doldurun. Yetkilendirilen Alanlar altında uygulamanızı barındıran alanları belirtin. KAYDET VE DEVAM ET'i tıklayın.

• Web uygulamanızın gerektirdiği tüm OAuth Kapsamlarını ekleyin. Kapsamlar ve amaçları hakkında ayrıntılı bir açıklama için OAuth yapılandırma kılavuzuna göz atın.

  Google'ın login_hint sorgu parametresini göndermesi için aşağıdaki kapsamlardan en az birini istemeniz gerekir. Bu davranışla ilgili daha ayrıntılı bir açıklamayı OAuth yapılandırma kılavuzumuzda bulabilirsiniz:

  • https://www.googleapis.com/auth/userinfo.email (zaten dahil)
  • https://www.googleapis.com/auth/userinfo.profile (zaten dahil)

  Aşağıdaki kapsamlar Classroom eklentilerine özeldir:

  • https://www.googleapis.com/auth/classroom.addons.teacher
  • https://www.googleapis.com/auth/classroom.addons.student

  Ayrıca, uygulamanızın son kullanıcılardan gerektirdiği diğer tüm Google API kapsamlarını da ekleyin.

  KAYDET VE DEVAM ET'i tıklayın

• Test kullanıcıları sayfasında test hesaplarının e-posta adreslerini listeleyin. KAYDET VE DEVAM ET'i tıklayın.

Ayarlarınızın doğru olduğunu onayladıktan sonra kontrol paneline dönün.

Uygulama Yapılandırması

GWM SDK'sının Uygulama Yapılandırması sayfasına gidin. Aşağıdaki bilgileri sağlayın:

• Uygulama Görünürlüğü'nü Private olarak ayarlayın. Bu ayar, test ve geliştirme amaçlarına uygundur ve bu adım adım açıklamalı kılavuzlar için uygun seçimdir. Public seçeneğini yalnızca eklentinizin herkes tarafından kullanılmasına hazırsanız seçin.

  Uyarı: Kaydetmeden önce Uygulama Görünürlüğü ayarınızın doğru olup olmadığını kontrol edin. Uygulama Görünürlüğü ayarlandıktan sonra değiştirilemez. Farklı bir Uygulama Görünürlüğü ayarlamak için yeni bir Google Cloud projesi oluşturmalısınız.

• Yüklemeyi alan yöneticileriyle kısıtlamak istiyorsanız Yükleme Ayarları'nı Admin Only install olarak belirleyin.

• Uygulama Entegrasyonu bölümünde Classroom eklentisi'ni seçin. Güvenli Ek Kurulumu URI'si istenir. Bu, bir kullanıcı eklentinizi açtığında yüklenmesini beklediğiniz URL'dir. Bu adım adım açıklamalı kılavuz için bu öğe https://<your domain>/addon-discovery olmalıdır.

• İzin Verilen Ek URI Önekleri, courses.*.addOnAttachments.create ve courses.*.addOnAttachments.patch yöntemlerini kullanarak AddOnAttachment içinde ayarlanan URI'leri doğrulamak için kullanılır. Doğrulama, dizenin ön ek eşleşmesidir ve şu anda joker karakterlerin kullanılmasına izin vermez. Bunları şimdilik boş bırakabilirsiniz.

• Önceki adımda OAuth izin ekranınızda sağlanan OAuth Kapsamlarını ekleyin.

  Uyarı: Uygulama Yapılandırması OAuth izin ekranınızda listelenen kapsamlardan farklı kapsamlar belirtiyorsa eklentiniz yayınlanamaz.

• Geliştirici Bağlantıları'nın altındaki alanları kuruluşunuza uygun şekilde doldurun.

Mağaza Girişi

GWM SDK'sının Mağaza Girişi sayfasına gidin. Aşağıdaki bilgileri sağlayın:

• Uygulama Ayrıntıları altında, bir dil ekleyin veya hâlihazırda listelenen dilin yanındaki açılır menüyü genişletin. Uygulama Adı ve açıklamaları girin. Bunlar, eklentinizin GWM mağaza girişi sayfasında görünür. Kaydetmek için Bitti'yi tıklayın.
• Eklentiniz için bir Kategori seçin.
• Grafik Öğeleri altında, zorunlu alanlar için resimler sağlayın. Bunlar daha sonra değiştirilebilir ve önceki adımda Uygulama Görünürlüğü'nü Gizli olarak ayarlarsanız yer tutucu olabilir.
• Destek Bağlantıları altında, istenen URL'leri sağlayın. Önceki adımda Uygulama Görünürlüğü'nü Gizli olarak ayarladıysanız bunlar yer tutucu olabilir.

Ayarlarınızı kaydetmek için YAYINLA'yı tıklayın. Önceki adımda Uygulama Görünürlüğü'nü Gizli olarak ayarlarsanız uygulamanız hemen yüklenebilir. Uygulama Görünürlüğü'nü Herkese Açık olarak ayarlarsanız uygulamanız, yüklenmek üzere kullanıma sunulmadan önce GWM ekibi tarafından incelenmek üzere gönderilir.

Eklentiyi yükleme

Artık GWM SDK'sının Mağaza Girişi sayfasının üst kısmındaki bağlantıyı kullanarak eklentinizi yükleyebilirsiniz. Listeyi görmek için sayfanın üst kısmındaki Uygulama URL'si seçeneğini tıklayın, ardından Yükle'yi seçin.

Not: Eklentiyi yalnızca OAuth izin ekranınızı yapılandırırken test kullanıcısı olarak belirttiğiniz bir hesapla giriş yaptıysanız yükleyebilirsiniz.

Temel web uygulaması oluşturma

İki rotalı iskelet web uygulaması oluşturun. Gelecekteki adım adım açıklamalı kılavuz adımları bu uygulamanın kapsamını genişleteceğinden, şimdilik /addon-discovery eklentisi için bir açılış sayfası ve "şirket sitemiz" için bir örnek dizin sayfası / oluşturun.

Şu iki uç noktayı uygulayın:

• /: Bir karşılama mesajı ve hem geçerli sekmeyi hem de eklenti iframe'ini kapatmak için bir düğme görüntüler.
• /addon-discovery: Bir karşılama mesajı ile iki düğme görüntüler. Bunlardan biri eklenti iframe'ini kapatmak, diğeri web sitesini yeni sekmede açmak içindir.

Pencereleri veya iframe'i oluşturup kapatmak için düğmeler eklediğimizi unutmayın. Bunlar, bir sonraki adım adım açıklamalı kılavuzda yetkilendirme için kullanıcıyı güvenli bir şekilde yeni bir sekmeye açma yöntemini gösterir.

Yardımcı program komut dosyası oluşturun

Bir static/scripts dizini oluşturun. Yeni bir dosya oluşturun: addon-utils.js. Aşağıdaki iki fonksiyonu ekleyin.

/**
 *   Opens a given destination route in a new window. This function uses
 *   window.open() so as to force window.opener to retain a reference to the
 *   iframe from which it was called.
 *   @param {string} destinationURL The endpoint to open, or "/" if none is
 *   provided.
 */
function openWebsiteInNewTab(destinationURL = '/') {
  window.open(destinationURL, '_blank');
}

/**
 *   Close the iframe by calling postMessage() in the host Classroom page. This
 *   function can be called directly when in a Classroom add-on iframe.
 *
 *   Alternatively, it can be used to close an add-on iframe in another window.
 *   For example, if an add-on iframe in Window 1 opens a link in a new Window 2
 *   using the openWebsiteInNewTab function above, you can call
 *   window.opener.closeAddonIframe() from Window 2 to close the iframe in Window
 *   1.
 */
function closeAddonIframe() {
  window.parent.postMessage({
    type: 'Classroom',
    action: 'closeIframe',
  }, '*');
};

Rota oluşturma

/addon-discovery ve / uç noktalarını uygulayın.

Python

Uygulama dizinini ayarlama

Bu örneğin amaçları doğrultusunda, uygulama mantığını bir Python modülü olarak yapılandırın. Bu, sağladığımız örnekte webapp dizinidir.

Sunucu modülü için bir dizin (webapp) oluşturun. static dizinini modül dizinine taşıyın. Modül dizininde bir template dizini oluşturun. HTML dosyalarınız burada yer alır.

Sunucu modülünü oluşturma*

Modül dizininizde __init__.py dosyasını oluşturun ve aşağıdaki içe aktarmaları ve bildirimleri ekleyin.

from flask import Flask
import config

app = Flask(__name__)
app.config.from_object(config.Config)

# Load other module script files. This import statement refers to the
# 'routes.py' file described below.
from webapp import routes

Ardından, web uygulamasının rotalarını işlemek için bir dosya oluşturun. Bu, sağladığımız örnekte webapp/routes.py. Bu dosyadaki iki rotayı uygulayın.

from webapp import app
import flask

@app.route("/")
def index():
    return flask.render_template("index.html",
                                message="You've reached the index page.")

@app.route("/classroom-addon")
def classroom_addon():
    return flask.render_template(
        "addon-discovery.html",
        message="You've reached the addon discovery page.")

Rotalarımızın her ikisinin de ilgili Jinja şablonlarına bir message değişkeni ilettiğini unutmayın. Bu, kullanıcının hangi sayfaya ulaştığını belirlemek açısından yararlıdır.

Yapılandırma oluşturma ve dosyaları başlatma

Uygulamanızın kök dizininde main.py ve config.py dosyalarını oluşturun. config.py ürününde gizli anahtarınızı yapılandırın.

import os

class Config(object):
    # Note: A secret key is included in the sample so that it works.
    # If you use this code in your application, replace this with a truly secret
    # key. See https://flask.palletsprojects.com/quickstart/#sessions.
    SECRET_KEY = os.environ.get(
        'SECRET_KEY') or "REPLACE ME - this value is here as a placeholder."

main.py dosyanızda, modülünüzü içe aktarın ve Flask sunucusunu başlatın.

from webapp import app

if __name__ == "__main__":
    # Run the application over HTTPs with a locally stored certificate and key.
    # Defaults to https://localhost:5000.
    app.run(
        host="localhost",
        ssl_context=("localhost.pem", "localhost-key.pem"),
        debug=True)

Node.js

Rotalar, app.js dosyasına aşağıdaki satırlarla kaydedilir.

const websiteRouter = require('./routes/index');
const addonRouter = require('./routes/classroom-addon');

app.use('/', websiteRouter);
app.use('/classroom-addon', addonRouter);

/01-basic-app/routes/index.js uygulamasını açıp kodu inceleyin. Bu rotaya son kullanıcı, şirket web sitesini ziyaret ettiğinde ulaşılır. Rota, index Gidon Çubuğu şablonunu kullanarak bir yanıt oluşturur ve şablona, title ve message değişkenlerini içeren bir veri nesnesi iletir.

router.get('/', function (req, res, next) {
  res.render('index', {
    title: 'Education Technology',
    message: 'Welcome to our website!'
  });
});

İkinci rotayı (/01-basic-app/routes/classroom-addon.js) açın ve kodu inceleyin. Bu rota, son kullanıcı ziyareti eklenti olduğunda ulaşılır. Bu rotanın, sayfayı şirket web sitesinden farklı bir şekilde oluşturmak için discovery Gidon Çubuğu şablonunu ve ayrıca addon.hbs düzenini kullandığını unutmayın.

router.get('/', function (req, res, next) {
  res.render('discovery', {
    layout: 'addon.hbs',
    title: 'Education Technology Classroom add-on',
    message: `Welcome.`
});
});

Java

Java kodu örneğinde, sıralı adım adım açıklamalı adımları paketlemek için modüller kullanılmaktadır. Bu ilk adım adım açıklamalı kılavuz olduğundan kod step_01_basic_app modülünün altındadır. Projenizi modül kullanarak uygulamanız beklenmemektedir. Bunun yerine, adım adım açıklamalı kılavuzdaki her adımı izlerken tek bir proje üzerinde derleme yapmanızı öneririz.

Uç noktaları tanımlamak için bu örnek projede Controller.java adlı denetleyici sınıfı oluşturun. Bu dosyada spring-boot-starter-web bağımlılığından @GetMapping ek açıklamasını içe aktarın.

import org.springframework.web.bind.annotation.GetMapping;

Sınıfın amacını belirtmek için sınıf tanımının üstüne Spring çerçevesi denetleyici ek açıklamasını ekleyin.

@org.springframework.stereotype.Controller
public class Controller {

Ardından, bu iki yolu ve hata işleme için ek bir yol uygulayın.

/** Returns the index page that will be displayed when the add-on opens in a
*   new tab.
*   @param model the Model interface to pass error information that's
*   displayed on the error page.
*   @return the index page template if successful, or the onError method to
*   handle and display the error message.
*/
@GetMapping(value = {"/"})
public String index(Model model) {
  try {
    return "index";
  } catch (Exception e) {
    return onError(e.getMessage(), model);
  }
}

/** Returns the add-on discovery page that will be displayed when the iframe
*   is first opened in Classroom.
*   @param model the Model interface to pass error information that's
*   displayed on the error page.
*   @return the addon-discovery page.
*/
@GetMapping(value = {"/addon-discovery"})
public String addon_discovery(Model model) {
  try {
    return "addon-discovery";
  } catch (Exception e) {
    return onError(e.getMessage(), model);
  }
}

/** Handles application errors.
*   @param errorMessage message to be displayed on the error page.
*   @param model the Model interface to pass error information to display on
*   the error page.
*   @return the error page.
*/
@GetMapping(value = {"/error"})
public String onError(String errorMessage, Model model) {
  model.addAttribute("error", errorMessage);
  return "error";
}

Eklentiyi test etme

Önemli: Uygulamanızı doğrudan bir web tarayıcısı kullanarak test edebilirsiniz, ancak öncelikle Classroom eklentilerinin iframe'lerinde test etmeniz gerekir. Web uygulamanızın iframe'de yüklenmesi, bazı olağan dışı davranışlara neden olabilir. Her bir iframe'in açıklaması için iframe ve sorgu parametreleri kılavuz sayfamızı okuyun. Bu adım adım açıklamalı kılavuzda sağlanan tüm talimatlar, eklentinin bir iframe bağlamında kullanılabilir olduğunu varsayar.

Sunucunuzu başlatın. Ardından, Google Classroom'da Öğretmen test kullanıcılarınızdan biri olarak oturum açın. Sınıf Çalışmaları sekmesine gidin ve yeni bir Ödev oluşturun. Metin alanının altındaki Eklentiler düğmesini tıklayın ve ardından eklentinizi seçin. iframe açılır ve eklenti, GWM SDK'sının Uygulama Yapılandırması sayfasında belirttiğiniz Ek Kurulum URI'sı'nı yükler.

Tebrikler! Sonraki adıma geçmeye hazırsınız: Google TOA ile kullanıcıların oturumunu açma.