Adım adım açıklamalı kılavuzlar

Bu adım adım açıklamalı kılavuzlar, bir çalışma ortamının tüm hareketli parçalarını Classroom eklentisi. Her bir adım adım açıklamalı kılavuz adımında belirli ve bunları tek bir web uygulamasında uygulamaktır. Bu hedef, işlevsel bir eklentinin kurulması, yapılandırılması ve kullanıma sunulmasında rol oynar.

Eklentiniz bir Google Cloud projesiyle etkileşime geçmelidir. Bu projenin Başlangıç kılavuzlarını okumanızı öneririz. Yönettiğiniz ve Google Workspace Marketplace SDK'sı, Google Cloud konsolunu kullanın. Daha fazla bilgi için Marketplace SDK'sı için Google Workspace Marketplace'i ziyaret edin listeleme kılavuzu sayfasına bakın.

Bu kılavuzda aşağıdaki konular ele alınmaktadır:

• Google Cloud'u kullanarak iframe'de gösterilecek bir sayfa oluşturun Classroom.
• Google tek oturum açma (TOA) özelliğini ekleyin ve kullanıcıların oturum açmasına izin verin.
• Eklentinizi ödeve eklemek için API çağrıları yapın.
• Önemli eklenti gönderim şartlarını ve gerekli özellikleri ele alın.

Bu kılavuzda, programlama ve temel web konularında bilgi sahibi olduğunuz varsayılır kavramlar var. Proje konfigürasyonunu okumanızı ve rehberini inceleyin. Bu sayfa önemli bilgiler içeriyor adımlarında tam olarak ele alınmayan yapılandırma ayrıntılarına sahiptir.

Örnek uygulamalar

Python'da eksiksiz bir referans örneği mevcuttur. Kısmi uygulamalar Java ve Node.js'de de mevcuttur. Bu uygulamalar, sonraki sayfalarda bulunan örnek kodun kaynakları.

Nereden indirilir?

Python ve Java örnekleri, GitHub depolarında mevcuttur:

• Python deposu

• Java deposu

Node.js örneği, zip dosyası olarak indirilebilir:

• Node.js arşivi

Ön koşullar

Yeni bir eklenti projesi hazırlamak için aşağıdaki bölümleri inceleyin.

HTTPS sertifikası

Uygulamanızı herhangi bir geliştirme ortamında barındırabilirsiniz. Classroom eklentisi yalnızca https:// üzerinden kullanılabilir. Dolayısıyla, Uygulamanızı dağıtmak veya uygulamanızı içinde test etmek için SSL şifrelemeli bir sunucuya iframe'i seçin.

localhost, SSL sertifikasıyla kullanılabilir; şu durumda mkcert seçeneğini değerlendirin yerel geliştirme için sertifika oluşturmanız gerekir.

Google Cloud projesi

Bu örneklerle kullanılacak bir Google Cloud projesi yapılandırmanız gerekir. Bkz. Google Cloud projesi oluşturma rehberi adımları uygulayın. Google Cloud projesi oluşturma bölümünde de uygulamanız gereken yapılandırma adımlarının yanı sıra eylemde bulunmaktır.

İşiniz bittiğinde OAuth 2.0 Client-ID'nizi JSON dosyası olarak indirin; eklemeniz gereken bu kimlik bilgisi dosyasını sıkıştırılmış örnek dizine taşımanızı sağlar. Daha fazla bilgi için dosyaları kullanabilirsiniz.

OAuth kimlik bilgileri

Önemli Bilgi: Web uygulamanız, Google'da yönetilen OAuth 2.0 kimlik bilgilerini kullanmalıdır Cloud'da görüntüleyebilirsiniz.

Yeni OAuth kimlik bilgileri oluşturmak için şu adımları uygulayın:

• Google Cloud Kimlik Bilgileri sayfasına gidin. Emin olun ekranın üst kısmında doğru projeyi seçmiş olduğunuzdan emin olun.
• KİMLİK BİLGİLERİ OLUŞTUR'u tıklayın ve açılan menüden OAuth istemci kimliği'ni seçin. açılır.
• Sonraki sayfada:
  • Uygulama türü'nü Web uygulaması olarak ayarlayın.
  • Yetkili yönlendirme URI'leri altında URI EKLE'yi tıklayın. yol ekleyin. Örneğin, https://my.domain.com/auth-callback veya https://localhost:5000/callback. Bu rotayı siz oluşturur ve işlersiniz bu kılavuzun devamına bakın. Dilediğiniz zaman bu tür rotaları düzenleyebilir veya daha fazla rota ekleyebilirsiniz.
  • OLUŞTUR'u tıklayın.
• Bunun üzerine, yeni oluşturulan kimlik bilgilerinizin yer aldığı bir iletişim kutusu görüntülenir. Önce JSON'U İNDİR seçeneğini belirleyin. İndirilen JSON dosyasını sunucunuza kopyalayın dizin.

Dile özgü ön koşullar

Her bir depodaki BENİOKU dosyasını görüntüleyerek en güncel önkoşullarını tanımlamamız gerekir.

Python

Python örneğimiz, Flask çerçevesini kullanır. Chrome web sitesini sağlanan bağlantılardan tam kaynak kodunu girin.

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

python3 -m ensurepip --upgrade

Ayrıca yeni bir Python sanal makinesi kurup etkinleştirmenizi öneririz. bahsedeceğim.

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

Şuradaki her adım adım açıklamalı alt dizinde bir requirements.txt vardır: indirilmiş örnek. Gerekli kitaplıkları hızlı bir şekilde yüklemek için pip Şu komutlar için gerekli kitaplıkları yüklemek amacıyla ilk adım adım açıklamalı kılavuzu.

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

Node.js

Node.js örneğimiz, Express çerçevesini kullanır. Şunları indirebilirsiniz: sağlanan bağlantılardaki kaynak kodunun tamamını girin.

Bu örnek için Node.js v16.13 veya sonraki sürümler gerekir.

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

npm install

Java

Java örneğimiz, Spring Boot çerçevesini kullanır. Şunları indirebilirsiniz: sağlanan bağlantılardaki kaynak kodunun tamamını girin.

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

Spring Boot uygulamaları, derlemeleri işlemek ve yönetmek için Gradle veya Maven'ı kullanabilir ve bildirmeyi konuştuk. Bu örnekte, Google'ın API'lerini kullanarak bir Maven'in kendisini yüklemenize gerek kalmadan başarılı bir derleme çalıştırıyor.

Projeyi indirdiğiniz veya klonladığınız dizinde, projeyi çalıştırmak için gerekli önkoşullara sahip olduğunuzdan emin olmak üzere aşağıdaki komutları uygulayın.

java --version
./mvnw --version

Alternatif olarak Windows'da:

java -version
mvnw.cmd --version

Dosyaları anlama

Aşağıdaki bölümlerde örnek dizinlerin düzeni açıklanmaktadır.

Dizin adları

Her depoda, adları bir sayıyla başlayan çeşitli dizinler bulunur. /01-basic-app/ gibi. Bu sayılar, adım adım açıklamalı belirli adımlara karşılık gelir. Her dizinde, özellikleri uygulayan tam işlevli bir web uygulaması bulunur öğrenebilirsiniz. Örneğin, /01-basic-app/ dizini, Create an add-on (Eklenti oluştur) için son uygulamayı içerir. adım adım açıklamalı kılavuzu inceleyin.

Dizin içerikleri

Dizin içerikleri, uygulama diline bağlı olarak farklılık gösterir:

Python

• Dizin kökü aşağıdaki dosyaları içerir:

  • main.py - Python uygulama giriş noktası. Sunucuyu belirtin bu dosyada kullanmak istediğiniz yapılandırmasını seçin ve ardından bu dosyayı sunucuyu başlatın.
  • requirements.txt - Web uygulamasını çalıştırmak için gerekli Python modülleri. Bunlar, pip install -r requirements.txt ile otomatik olarak yüklenebilir.

  • client_secret.json: Google'dan indirilen istemci gizli anahtarı Cloud'da geliştiricilerin karşılaştığı yaygın sorunları çözmenize ve kullanım alanlarını öğrenmenize yardımcı olacak teknik belgeleri ve videoları keşfedin. Bunun örnek arşive dahil edilmediğini unutmayın; siz indirdiğiniz kimlik bilgileri dosyanızı yeniden adlandırmalı ve dizin kökü.

    Önemli: Google Cloud projesiyle ilgili talimatları uygulayın.

• config.py - Flask sunucusu için yapılandırma seçenekleri.

• webapp dizini, web uygulamasına ait içeriği barındırır. Bunlardan bazıları:

• Çeşitli sayfalar için Jinja şablonlarını içeren /templates/ dizini.

• Resimler, CSS ve yardımcı JavaScript'i içeren /static/ dizini dosyası olarak da kaydedebilir.

• routes.py - web uygulaması rotaları için işleyici yöntemleri.

• __init__.py - webapp modülü için başlatıcı. Bu başlatıcı, Flask sunucusunu başlatır ve yapılandırma seçeneklerini yükler config.py hücresinde ayarlandı.

• Belirli bir adım adım açıklamalı kılavuz adımının gerektirdiği ek dosyalar.

Node.js

Yürüyüşteki her adım kendi <step> içinde bulunabilir alt klasöre koyabilirsiniz. Her adımda şunlar bulunur:

• JavaScript, CSS ve görseller gibi statik dosyalar ./<step>/public klasör.
• Ekspres yönlendiriciler ./<step>/routes klasörlerinde bulunuyor.
• HTML şablonları ./<step>/views klasörde bulundu.
• Sunucu uygulaması: ./<step>/app.js.

Java

Proje dizini şunları içerir:

• src.main dizini, çalıştırılacak kaynak kodunu ve yapılandırmayı içerir geri dönelim. Bu dizin şunları içerir: + java.com.addons.spring dizini şunu içerir: Application.java ve Controller.java dosyaları. İlgili içeriği oluşturmak için kullanılan Application.java dosyası, Controller.java dosyası uç nokta mantığı. + resources dizini, şununla birlikte templates dizinini içerir: HTML ve JavaScript dosyaları. Ayrıca application.properties dosyası, sunucuyu, anahtar deposu dosyasının yolunu ve templates dizini. Bu örnek, resources dizininde bulabilirsiniz. Bu verileri istediğiniz yerde saklayabilirsiniz ancak application.properties ayarlarını güncellediğinizden emin olun. yolu buna göre değiştirebilirsiniz.
  • pom.xml, projeyi oluşturmak için gereken bilgileri içerir ve ve gerekli bağımlılıkları belirlemenize yardımcı olur.
  • .gitignore, git'e yüklenmemesi gereken dosya adları içeriyor. Bu .gitignore içinde anahtar deponuzun yolunu eklediğinizden emin olun. Sağlanan örnekte bu, secrets/*.p12 ( anahtar deposu aşağıdaki bölümde ele alınmaktadır). Adım adım açıklamalı 2 ve hedefinize giden yolu da Lütfen client_secret.json dosyanızı dahil etmediğinizden emin olun saklayan sırları saklıyor. Adım adım açıklamalı 3 ve daha fazlası için H2 veritabanı dosyasının ve dosya veri deposunun yolunu eklemelidir fabrika ayarlarına dönelim. Bu veri depolarının kurulumu hakkında daha fazla bilgi tekrarlanan ziyaretleri yönetme ile ilgili üçüncü adım adım açıklamalı kılavuzda bulabilirsiniz.
  • mvnw ve mvnw.cmd, Unix ve Windows. Örneğin, ./mvnw --version şurada çalıştırılıyor: Unix, diğer bilgilerin yanı sıra Apache Maven sürümünü oluşturur.
  • .mvn dizini, Maven sarmalayıcı için yapılandırmayı içerir.

Örnek sunucuyu çalıştırma

Önemli Nokta: Web uygulamanız yalnızca Google Classroom'da şunun üzerinden açılabilir: HTTPS'ye dokunun. Diğer ayrıntılar için HTTPS sertifikası bölümüne bakın.

Test etmek için sunucunuzu başlatmanız gerekir. Bu talimatları uygulayarak örnek sunucuyu seçtiğiniz dilde çalıştırın:

Python

OAuth kimlik bilgileri

OAuth kimlik bilgilerinizi daha önce açıklandığı şekilde oluşturup indirin. Yer uygulamanızın sunucusuyla birlikte kök dizinde bulunan JSON dosyası başlatma dosyasıdır.

Sunucuyu yapılandırma

Web sunucusunu çalıştırmak için birkaç seçeneğiniz vardır. Bu Python dosyasına aşağıdakilerden birini ekleyin:

1. localhost güvenli değil. Bunun doğrudan test için uygun olduğunu unutmayın Yalnızca bir tarayıcı penceresinde; Güvenli olmayan alanlar, Classroom eklenti iframe'i.

   if __name__ == "__main__":
     # Disable OAuthlib's HTTPs verification.
     os.environ["OAUTHLIB_INSECURE_TRANSPORT"] = "1"
   
     # Run the web app at http://localhost:5000.
     app.run(debug=True)
   

2. Güvenli localhost. Şu öğe için bir SSL anahtar dosyası türü belirtmelisiniz: ssl_context bağımsız değişken.

   if __name__ == "__main__":
     # Run the web app at https://localhost:5000.
     app.run(host="localhost",
             ssl_context=("localhost.pem", "localhost-key.pem"),
             debug=True)
   

3. Gunicorn sunucusuyla iletişim kurmalıdır. Üretime hazır bir sunucu veya daha fazla bilgi edineceksiniz. Şunun için bir PORT ortam değişkeni ayarlamanızı öneririz: bu seçeneği kullanabilirsiniz.

   if __name__ == "__main__":
     # Run the web app at https://<your domain>:<server_port>.
     # Defaults to https://<your domain>:8080.
     server_port = os.environ.get("PORT", "8080")
     app.run(debug=True, port=server_port, host="0.0.0.0")
   

Sunucuyu başlatma

Uyarı: Sunucuyu başlatmadan önce bir Google Cloud projesinden Classroom API ve gerekli kimlik bilgileri.

Sunucuyu önceki adım.

python main.py

Web uygulamanızı tarayıcıda görüntülemek için gösterilen URL'yi tıklayarak aşağıdaki işlemi onaylayın: çalışıp çalışmadığını kontrol edin.

Node.js

Sunucuyu yapılandırma

Sunucuyu HTTPS üzerinden çalıştırmak için kendi sertifikası oluşturmanız gerekir için kullanılan bir uygulamadır. Bu kimlik bilgileri, kod deposu köküne sslcert/cert.pem ve sslcert/key.pem olarak kaydedildi emin olmanız gerekir. İşlemi tamamlamak için bu anahtarları OS anahtar zincirinize eklemeniz tarayıcınıza ekleyin.

Kopyalama işlemini önlemek için *.pem öğesinin .gitignore dosyanızda bulunduğundan emin olun kaydetmesini isteyin.

Sunucuyu başlatma

Uyarı: Sunucuyu başlatmadan önce bir Google Cloud projesinden Classroom API ve gerekli kimlik bilgileri.

Uygulamayı, step01 yerine aşağıdaki komutu kullanarak çalıştırabilirsiniz çalıştırmak istediğiniz doğru adımla (örneğin, step01 01-basic-app için, 02-oturum açmak için step02).

npm run step01

veya

npm run step02

Bu işlemle, https://localhost:5000 adresindeki web sunucusu başlatılır.

Terminalinizde Control + C ile sunucuyu sonlandırabilirsiniz.

Java

Sunucuyu yapılandırma

Sunucuyu HTTPS üzerinden çalıştırmak için kendi sertifikası oluşturmanız gerekir için kullanılan bir uygulamadır.

Yerel geliştirme için mkcert'i kullanabilirsiniz. mkcert uygulamasını yükledikten sonra, aşağıdaki komutlar çalıştırılacak, yerel olarak depolanan bir sertifika oluşturur HTTPS'ye dokunun.

mkcert -install
mkcert -pkcs12 -p12-file <path_to_keystore> <domain_name>

Bu örnek, kaynaklar dizinindeki anahtar deposu dosyasını içerir. istediğiniz yerde depolayabilirsiniz, ancak yine de yolu uygun şekilde application.properties dosyası olarak kaydedin. Alan adı projeyi çalıştırdığınız alan adı (örneğin, localhost).

Kopyalama işlemini önlemek için *.p12 öğesinin .gitignore dosyanızda bulunduğundan emin olun kaydetmesini isteyin.

Sunucuyu başlatma

Uyarı: Sunucuyu başlatmadan önce bir Google Cloud projesinden Classroom API ve gerekli kimlik bilgileri.

Application.java içinde main yöntemini çalıştırarak sunucuyu başlatın dosyası olarak kaydedebilirsiniz. Örneğin IntelliJ'de Application.java Run 'Application' src/main/java/com/addons/spring dizinini açın veya Application.java dosyasını açın dosyasını tıklayarak main(String[] args) öğesinin solundaki yeşil oku tıklayın yöntem imzası da dahildir. Alternatif olarak, projeyi bir terminalde çalıştırabilirsiniz pencere:

./mvnw spring-boot:run

veya Windows'da:

mvnw.cmd spring-boot:run

Bu işlem, sunucuyu https://localhost:5000 adresinde veya istediğiniz bağlantı noktasında başlatır application.properties içinde belirtilir.