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

Bu adım adım açıklamalı kılavuzlar, çalışan bir Classroom eklentisinin tüm hareketli parçalarını göstermektedir. Adım adım açıklamalı her adım, belirli kavramları ele alarak bunları tek bir web uygulamasında uygular. Hedefiniz, işlevsel bir eklentinin kurulumunda, yapılandırmasında ve lansmanında size yardımcı olmaktır.

Eklentiniz bir Google Cloud projesiyle etkileşim kurmalıdır. Google Cloud hakkında bilginiz yoksa Başlangıç kılavuzlarını okumanızı öneririz. Google Cloud Console'da kimlik bilgilerini, API erişimini ve GWM SDK'sını yönetirsiniz. GWM SDK'sı hakkında daha fazla bilgi için Google Workspace Marketplace giriş kılavuz sayfasını ziyaret edin.

Bu kılavuz aşağıdaki konuları kapsar:

• Classroom'daki bir iframe'de gösterilecek bir sayfa oluşturmak için Google Cloud'u kullanın.
• Google tek oturum açma (TOA) özelliğini ekleyin ve kullanıcıların oturum açmasına izin verin.
• Eklentinizi bir ödeve eklemek için API çağrıları yapın.
• Temel eklenti gönderim gereksinimlerini ve gerekli özellikleri karşılayın.

Bu kılavuzda, programlama ve temel web geliştirme kavramlarına aşina olduğunuz varsayılır. Adım adım açıklamalı kılavuzlara başlamadan önce Proje yapılandırma kılavuzunu okumanızı önemle tavsiye ederiz. Bu sayfada, adım adım açıklamalı kılavuzlarda tam olarak ele alınmayan önemli yapılandırma ayrıntıları bulunmaktadır.

Örnek uygulamalar

JavaScript, Python ve Java'da eksiksiz referans örnekleri mevcuttur. Bu uygulamalar sonraki sayfalarda bulunan örnek kodun kaynaklarıdır.

İndirileceği yer

Örneklerimizin tam arşivlerini aşağıdaki bağlantılar kullanılarak indirebilirsiniz.

• Python arşivi
• Node.js arşivi
• Java 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, ancak Classroom eklentiniz yalnızca https:// üzerinden kullanılabilir. Bu nedenle, uygulamanızı dağıtmak veya eklenti iframe'i içinde test etmek için SSL şifrelemesi olan bir sunucuya ihtiyacınız vardır.

localhost, SSL sertifikasıyla kullanılabilir. Yerel geliştirme için sertifika oluşturmanız gerekiyorsa mkcert komutunu değerlendirin.

Google Cloud projesi

Bu örneklerle kullanmak için bir Google Cloud projesi yapılandırmanız gerekir. Başlamak için gerekli adımlara genel bakış için Google Cloud projesi oluşturma kılavuzunu inceleyin. İlk adım adım açıklamalı kılavuzdaki Google Cloud projesi oluşturun bölümünde, gerçekleştirilecek belirli yapılandırma işlemleri de adım adım açıklanmıştır.

İşlem tamamlandığında OAuth 2.0 İstemci Kimliğinizi JSON dosyası olarak indirin. Bu kimlik bilgisi dosyasını sıkıştırılmış örnek dizine eklemeniz gerekir. Belirli konumlar için Dosyaları anlama bölümüne bakın.

OAuth kimlik bilgileri

Önemli Nokta: Web uygulamanız, Google Cloud'da yönetilen OAuth 2.0 kimlik bilgilerini kullanmalıdır.

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

• Google Cloud Kimlik Bilgileri sayfasına gidin. Ekranın üst kısmında doğru projeyi seçtiğinizden emin olun.
• KİMLİK BİLGİLERİ OLUŞTUR'u tıklayın ve açılır menüden OAuth istemci kimliği'ni seçin.
• Sonraki sayfada:
  • Uygulama türü'nü Web uygulaması olarak ayarlayın.
  • Yetkilendirilmiş yönlendirme URI'leri altında URI EKLE'yi tıklayın. Uygulamanızın geri çağırma rotası için tam yolu ekleyin. Örneğin, https://my.domain.com/auth-callback veya https://localhost:5000/callback. Rotayı, bu adım adım açıklamalı kılavuzda daha sonra oluşturup işleyeceğiz. Dilediğiniz zaman rotalarınızı düzenleyebilir veya yeni rotalar ekleyebilirsiniz.
  • CREATE'ı (OLUŞTUR) tıklayın.
• Yeni oluşturulan kimlik bilgilerinizin yer aldığı bir iletişim kutusu gösterilir. JSON'u İNDİR seçeneğini belirleyin. İndirilen .json dosyasını sunucu dizininize kopyalayın.

Dile özgü ön koşullar

En güncel ön koşul listesini görmek için her arşivdeki BENİOKU dosyasını görüntüleyin.

Python

Python örneğimizde Flask çerçevesi kullanılmıştır. Kaynak kodun tamamını yukarıdaki bağlantıdan indirebilirsiniz.

Gerekirse Python 3.7 ve sonraki sürümleri 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 ortamı oluşturup etkinleştirmenizi de öneririz.

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

İndirilen örneklerdeki adım adım açıklamalı kılavuz alt dizinlerinin her birinde bir requirements.txt yer alır. Gerekli kitaplıkları pip kullanarak hızlıca yükleyebilirsiniz. İlk adım adım açıklamalı kılavuz için gerekli kitaplıkları yüklemek üzere aşağıdaki komutları kullanın.

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

Node.js

Node.js örneğimizde Express çerçeve kullanılır. Kaynak kodun tamamını yukarıdaki bağlantıdan indirebilirsiniz.

Bu örnek için Node.js v16.13 veya sonraki bir sürüm gereklidir.

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

npm install

Java

Java örneğimizde Spring Boot çerçevesi kullanılmıştır. Kaynak kodun tamamını yukarıdaki bağlantıdan 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.

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

java --version
./mvnw --version

Veya 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 arşiv, /01-basic-app/ gibi bir sayı ile başlayan birkaç dizin içerir. Sayılar, adım adım açıklamalı belirli adımlara karşılık gelir. Her dizin, belirli bir adım adım açıklamalı kılavuzda açıklanan özellikleri uygulayan, tamamen işlevsel bir web uygulaması içerir. Örneğin, /01-basic-app/ dizini, Eklenti oluşturun adım adım açıklamalı kılavuzunun son uygulamasını içerir.

Dizin içeriği

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

Python

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

  • main.py: Python uygulaması giriş noktası. Bu dosyada kullanmak istediğiniz sunucu yapılandırmasını belirtin, ardından sunucuyu başlatmak için çalıştırın.
  • requirements.txt: Web uygulamasını çalıştırmak için gereken Python modülleri. Bu modüller, pip install -r requirements.txt kullanılarak otomatik olarak yüklenebilir.

  • client_secret.json - Google Cloud'dan indirilen istemci gizli anahtarı dosyası. Bunun örnek arşivine dahil edilmediğini unutmayın. İndirdiğiniz kimlik bilgileri dosyasını yeniden adlandırmanız ve her dizin köküne kopyalamanız gerekir.

    Önemli: Örnekleri çalıştırabilmek için önce Google Cloud projenizden istemci gizli anahtarı dosyasını sağlamanız gerekir.

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

• webapp dizini, web uygulamasının içeriğini barındırır. Şunları içerir:

• Jinja şablonları içeren /templates/ dizini, çeşitli sayfalar için kullanılır.

• Resimler, CSS ve yardımcı JavaScript dosyaları içeren /static/ dizini.

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

• __init__.py - webapp modülü için başlatıcı. Bu ilkleştirici, Flask sunucusunu başlatır ve config.py bölgesinde ayarlanan yapılandırma seçeneklerini yükler.

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

Node.js

Bu adımın her adımı kendi <step> alt klasöründe bulunabilir. Her adım şunları içerir:

• ./<step>/public klasöründe JavaScript, CSS ve resimler gibi statik dosyalar bulunur.
• Ekspres yönlendiriciler ./<step>/routes klasörlerinde bulunuyor.
• HTML şablonları ./<step>/views klasörlerinde bulunuyor.
• Sunucu uygulaması ./<step>/app.js.

Java

Proje dizini şunları içerir:

• src.main dizini, uygulamayı başarıyla çalıştırmak için gerekli kaynak kodunu ve yapılandırmayı içerir. Bu dizin aşağıdakileri içerir: + java.com.addons.spring dizini, Application.java ve Controller.java dosyalarını içerir. Application.java dosyası uygulama sunucusunu çalıştırmaktan sorumludur, Controller.java dosyası ise uç nokta mantığını işler. + resources dizini, HTML ve JavaScript dosyalarının bulunduğu templates dizinini içerir. Dosya ayrıca, sunucuyu çalıştıracak bağlantı noktasını, anahtar deposu dosyasının yolunu ve templates dizininin yolunu belirten application.properties dosyasını içerir. Bu örnek, resources dizinindeki anahtar deposu dosyasını içerir. Dosyayı istediğiniz yerde depolayabilirsiniz ancak application.properties dosyasını yol ile uygun şekilde güncellediğinizden emin olun.
  • pom.xml, projeyi oluşturmak ve gerekli bağımlılıkları tanımlamak için gereken bilgileri içerir.
  • .gitignore, git'e yüklenmemesi gereken dosya adları içeriyor. Anahtar deponuzun yolunu bu .gitignore içinde eklediğinizden emin olun. Sağlanan örnekte bu, secrets/*.p12 değeridir (anahtar deposunun amacı aşağıdaki bölümde açıklanmıştır). Adım adım açıklamalı kılavuz 2 ve sonrasında, gizli anahtarlarınızı uzak bir depoya eklemediğinizden emin olmak için client_secret.json dosyanızın yolunu da eklemeniz gerekir. Adım adım açıklamalı kılavuz 3 ve sonrası için H2 veritabanı dosyasının ve dosya veri deposu fabrikasının yolunu eklemeniz gerekir. Bu veri depolarının kurulumuyla ilgili daha fazla bilgiyi, tekrarlanan ziyaretlerin ele alınması ile ilgili üçüncü adım adım açıklamalı kılavuzda bulabilirsiniz.
  • mvnw ve mvnw.cmd, sırasıyla Unix ve Windows için Maven sarmalayıcı yürütülebilir dosyalarıdır. Örneğin, Unix'de ./mvnw --version komutunu çalıştırmak diğer bilgilerin yanı sıra Apache Maven sürümünü verir.
  • .mvn dizini Maven sarmalayıcısı için yapılandırma içeriyor.

Örnek sunucuyu çalıştırma

Önemli Bilgi: Web uygulamanız Google Classroom'da yalnızca HTTPS üzerinden açılabilir. Ek ayrıntılar için yukarıdaki HTTPS sertifikası bölümüne bakın.

Test etmek için sunucunuzu başlatmanız gerekir. Örnek sunucuyu seçtiğiniz dilde çalıştırmak için aşağıdaki talimatları uygulayın:

Python

OAuth kimlik bilgileri

OAuth kimlik bilgilerinizi yukarıda açıklandığı şekilde oluşturup indirin. .json dosyasını kök dizine, uygulamanızın sunucu başlatma dosyasının yanına yerleştirin.

Sunucuyu yapılandırma

Web sunucusunu çalıştırmak için birkaç seçeneğiniz vardır. Python dosyanızın sonuna aşağıdakilerden birini ekleyin:

1. localhost güvenli değil. Bunun yalnızca bir tarayıcı penceresinde doğrudan test yapmak için uygun olduğunu, güvenli olmayan alanlar Classroom eklentisi iframe'de yüklenemez.

   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. ssl_context bağımsız değişkeni için SSL anahtar dosyalarından oluşan bir unsur belirtmelisiniz.

   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 sunucusu. Bu, üretime hazır bir sunucu veya bulut dağıtımı için uygundur. Bu başlatma seçeneğiyle birlikte kullanılacak bir PORT ortam değişkeni ayarlamanızı öneririz.

   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, Classroom API'ye ve gerekli kimlik bilgilerine erişmek için bir Google Cloud projesi oluşturmanız gerekir.

Sunucuyu önceki adımda yapılandırıldığı şekilde başlatmak için Python uygulamanızı çalıştırın.

python main.py

Web uygulamanızı bir tarayıcıda görüntülemek için görünen URL'yi tıklayarak uygulamanın doğru çalıştığını onaylayın.

Node.js

Sunucuyu yapılandırma

Sunucuyu HTTPS üzerinden çalıştırmak için, uygulamayı HTTPS üzerinden çalıştırmak üzere kullanılan bir kendinden sertifika oluşturmanız gerekir. Bu kimlik bilgileri, kod deposu kök klasöründe sslcert/cert.pem ve sslcert/key.pem olarak kaydedilmelidir. Tarayıcınızın bu anahtarları kabul etmesi için bu anahtarları OS anahtar zincirinize eklemeniz gerekebilir.

Dosyayı git'e kaydetmek istemediğiniz için *.pem dosyasının .gitignore dosyanızda bulunduğundan emin olun.

Sunucuyu başlatma

Uyarı: Sunucuyu başlatmadan önce, Classroom API'ye ve gerekli kimlik bilgilerine erişmek için Google Cloud projesi oluşturmanız gerekir.

Uygulamayı, sunucu olarak çalıştırmak istediğiniz doğru adımla değiştirerek step01 komutunu kullanarak uygulamayı çalıştırabilirsiniz (örneğin, 01-basic-app için step01, 02-sign-in için step02).

npm run step01

veya

npm run step02

https://localhost:3000 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, uygulamayı HTTPS üzerinden çalıştırmak üzere kullanılan bir kendinden sertifika oluşturmanız gerekir.

Yerel geliştirme için mkcert kullanmayı düşünün. mkcert eklentisini yüklediğinizde aşağıdaki komutlar, HTTPS üzerinden çalışacak şekilde yerel olarak depolanan bir sertifika oluşturur.

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

Bu örnek, kaynaklar dizinindeki anahtar deposu dosyasını içerir. Dosyayı istediğiniz yerde depolayabilirsiniz ancak application.properties dosyasını yol ile uygun şekilde güncellediğinizden emin olun. Alan adı, projeyi çalıştırdığınız alandır (örneğin, localhost).

Dosyayı git'e kaydetmek istemediğiniz için *.p12 dosyasının .gitignore dosyanızda bulunduğundan emin olun.

Sunucuyu başlatma

Uyarı: Sunucuyu başlatmadan önce, Classroom API'ye ve gerekli kimlik bilgilerine erişmek için Google Cloud projesi oluşturmanız gerekir.

Application.java dosyasında main yöntemini çalıştırarak sunucuyu başlatın. Örneğin, IntelliJ'de src/main/java/com/addons/spring dizininde Application.java > Run 'Application' öğesini sağ tıklayabilir veya Application.java dosyasını açarak main(String[] args) yöntem imzasının solundaki yeşil oku tıklayabilirsiniz. Alternatif olarak, projeyi bir terminal penceresinde çalıştırabilirsiniz:

./mvnw spring-boot:run

veya Windows'da:

mvnw.cmd spring-boot:run

Bu işlem, sunucuyu https://localhost:5000 konumunda veya application.properties öğesinde belirttiğiniz bağlantı noktasında başlatır.