Classroom eklentisi oluşturma

Bu, Classroom eklentileriyle ilgili adım adım açıklamalı serinin ilk kılavuzudur.

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

Bu adım adım açıklamalı kılavuz kapsamında aşağıdaki işlemleri tamamlayacaksınız:

• Eklentiniz için yeni bir Google Cloud projesi oluşturun.
• Yer tutucu oturum açma düğmeleriyle iskelet bir web uygulaması oluşturun.
• Eklentiniz için bir Google Workspace Marketplace Mağaza Girişi yayınlayın.

İşiniz bittiğinde eklentinizi yükleyebilir ve Classroom eklentileri iframe'inde yükleyebilirsiniz.

Önemli: Bu adım adım açıklamalı kılavuzlara başvurmadan önce proje yapılandırma kılavuzunu okuyun ve geliştirici yolculuğunun ilk katılım adımlarını tamamlayın. Daha sonra değiştirilemeyeceği için uygulamanın görünürlük ayarına özellikle dikkat edin.

Ön koşullar

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

Python

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

Gerekirse Python 3.7+ 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ı kurup etkinleştirmenizi öneririz.

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

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

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

Node.js

Node.js örneğimiz, Express çerçevesini kullanır. Genel bakış sayfasından tüm adım adım açıklamalı kılavuzlar için eksiksiz kaynak kodu indirebilirsiniz.

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

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

npm install

Java

Java örneğimiz, Spring Boot çerçevesini kullanır. Genel bakış sayfasından tüm adım adım açıklamalı kılavuzların tamamını kaynak kodu indirebilirsiniz.

Makinenize henüz yüklemediyseniz Java 11+'yi yükleyin.

Spring Boot uygulamaları, derlemeleri ve bağımlılıkları yönetmek için Gradle veya Maven'i kullanabilir. Bu örnek, Maven'ı 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

Alternatif olarak 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ımlarda size yol gösterir.

Projeyi oluşturma

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

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

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

Google Workspace Marketplace SDK'sını Google Cloud projesine ekleme

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çip Etkinleştir'i tıklayın.

Google Workspace Marketplace SDK'sını yapılandırma

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

Uygulama Yapılandırması

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

• Uygulama Görünürlüğü'nü Public veya Private olarak ayarlayın.

  • Herkese açık ayar, sonunda son kullanıcılara yayınlanacak uygulamalar için tasarlanmıştır. Herkese açık bir uygulamanın son kullanıcılara yayınlanmadan önce onay sürecinden geçmesi gerekir. Ancak uygulamayı yükleyip Taslak olarak test edebilecek kullanıcıları belirtebilirsiniz. Bu, onaya göndermeden önce eklentinizi test etmenize ve geliştirmenize olanak tanıyan bir yayın öncesi durumudur.
  • Gizli ayar, dahili test ve geliştirme için uygundur. Gizli uygulamalar yalnızca projenin oluşturulduğu alan adındaki kullanıcılar tarafından yüklenebilir. Bu nedenle, yalnızca proje Google Workspace for Education aboneliği bulunan bir alanda oluşturulduysa görünürlüğü "gizli" olarak ayarlamanız gerekir. Aksi takdirde, test kullanıcılarınız Classroom eklentilerini başlatamaz.
  Uyarı: Kaydetmeden önce Uygulama Görünürlüğü ayarınızın doğru olduğundan emin olun. Uygulama Görünürlüğünü ayarladıktan sonra değiştiremezsiniz. Farklı bir Uygulama Görünürlüğü ayarlamak için yeni bir Google Cloud projesi oluşturmanız gerekir.

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

• 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 değer https://<your domain>/addon-discovery olmalıdır.

• İzin Verilen Ek URI Ön Ekleri, courses.*.addOnAttachments.create ve courses.*.addOnAttachments.patch yöntemleri kullanılarak AddOnAttachment içinde ayarlanan URI'leri doğrulamak için kullanılır. Doğrulama, düz bir dize ön eki eşleşmesidir ve şu anda joker karakterlerin kullanılmasına izin vermez. İçerik sunucunuzun en azından kök alanını (ör. https://localhost:5000/ veya https://cdn.myedtech.com/) ekleyin.

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

  Önemli: Uygulama Yapılandırması'nda belirtilen OAuth kapsamları listesi, OAuth izin ekranınızda listelenenlerle eşleşmelidir.

• Geliştirici Bağlantıları bölümündeki alanları kuruluşunuza uygun şekilde doldurun.

Mağaza Girişi

Marketplace 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 halihazırda listelenen dilin yanındaki açılır menüyü genişletin. Bir Uygulama Adı ve açıklamalar girin. Bunlar, eklentinizin Google Workspace Marketplace 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 resim sağlayın. Bunlar daha sonra değiştirilebilir ve şimdilik yer tutucu olarak kullanılabilir.
• Destek Bağlantıları altında, istenen URL'leri sağlayın. Önceki adımda Uygulama Görünürlüğü'nü Gizli olarak ayarlarsanız bunlar yer tutucu olabilir.

Önceki adımda Uygulama Görünürlüğü'nü Gizli olarak ayarladıysanız YAYINLA'yı tıklayın. Uygulamanız hemen yüklenebilir. Uygulama Görünürlüğü'nü Herkese Açık olarak ayarlarsanız Taslak Test Kullanıcıları alanına tüm test kullanıcıları için e-posta adresleri ekleyin ve Taslağı Kaydet'i tıklayın.

Önemli Bilgi: Görünürlüğü Herkese Açık olan bir uygulama için YAYINLA seçildiğinde uygulama hemen Marketplace ekibi tarafından incelenmek üzere gönderilir. Uygulamanın Marketplace'e eklenebilmesi için inceleme ekibinin uygulamayı test edip onaylaması gerekir. Test kullanıcılarınız tarafından incelenmeden yüklenebilir hale getirmek için proje taslaklarını kaydedin. Marketplace ekibinin onaylaması için hazır olduğunuzda TASLAĞI YAYINLA'yı seçebilirsiniz.

OAuth İzin Ekranı

OAuth İzin Ekranı, kullanıcılar uygulamanızı ilk kez yetkilendirdiğinde görünür. Kullanıcılardan, uygulamanızın etkinleştirdiğiniz kapsamlar tarafından belirtildiği şekilde 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ü) seçeneğini External (Harici) olarak ayarlayın. Create'i (Oluştur) tıklayın.
• Sonraki sayfada, gerekli uygulama ayrıntılarını ve iletişim bilgilerini girin. Yetkili Alanlar altında, uygulamanızı barındıran tüm 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ıyla ilgili ayrıntılı bir tartışma için OAuth yapılandırma kılavuzuna bakın.

  Google'ın login_hint sorgu parametresini göndermesi için aşağıdaki kapsamlardan en az birini istemeniz gerekir. Bu davranışın daha ayrıntılı açıklamasını 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

  Uygulamanızın son kullanıcılardan gerektirdiği diğer tüm Google API kapsamlarını da dahil edin.

  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 onaylayın ve ardından kontrol paneline dönün.

Eklentiyi yükle

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

Not: Şu an için yalnızca belirli kullanıcılar eklentiyi yükleyebilir. Eklentinizin görünürlüğü herkese açık ise yalnızca Taslak Test Kullanıcıları olarak listelenen kullanıcılardır. Eklentinizin gizli görünürlüğü varsa bunlar, Cloud projesiyle aynı alanda bulunan tüm kullanıcılardır.

Temel bir web uygulaması geliştirme

İki rota ile iskelet web uygulaması kurma. İlerideki adım adım açıklamalı kılavuz adımları bu uygulamayı genişletir. Bu nedenle, şimdilik /addon-discovery eklentisi için bir açılış sayfası ve "şirket sitemiz" için bir örnek dizin sayfası (/) oluşturmanız yeterlidir.

Bu 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ı ve iki düğme görüntüler: biri eklenti iframe'ini kapatmak, diğeri web sitesini yeni sekmede açmak için kullanılır.

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

Yardımcı program komut dosyası oluşturma

Bir static/scripts dizini oluşturun. addon-utils.js adlı yeni bir dosya oluşturun. Aşağıdaki iki işlevi 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, 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 kurma

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

Sunucu modülü için bir dizin oluşturun (ör. webapp). static dizinini modül dizinine taşıyın. Modül dizininde de 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 aktarma 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. Sağladığımız örnekte webapp/routes.py değeri kullanılmıştır. Bu dosyadaki iki yolu da 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.")

Her iki rotamızın da ilgili Jinja şablonlarına message değişkeni ilettiğini unutmayın. Bu, kullanıcının hangi sayfaya ulaştığını belirlemek için 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ıza, 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('/addon-discovery', addonRouter);

/01-basic-app/routes/index.js uygulamasını açın ve kodu inceleyin. Bu rota, son kullanıcı ziyaretinde şirketin web sitesini ziyaret ettiğinde ulaşılır. Rota, index Tutamaçları ş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ığına dikkat edin.

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ılır. Bu ilk adım adım açıklamalı kılavuz olduğu için kod, step_01_basic_app modülünün kapsamındadır. Projenizi modülleri kullanarak uygulamanız beklenmez. Bunun yerine, adım adım açıklamalı kılavuzdaki her bir adımı tek bir proje üzerine geliştirmenizi öneririz.

Uç noktaları tanımlamak için bu örnek projede bir denetleyici sınıfı (Controller.java) 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 üzerine Spring çerçevesi denetleyicisi ek açıklamasını ekleyin.

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

Ardından bu iki yolu ve hata işlemeye yönelik ek bir yolu 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 eklentileri iframe'lerinde test etmeniz gerekir. Web uygulamanızın iframe'e yüklenmesi bazı alışılmadık 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 talimatlarda, eklentinin bir iframe bağlamında kullanılabileceği varsayılmıştır.

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

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