İçerik türü ekler

Bu, Classroom eklentileri açıklamalı kılavuz serisinin dördüncü bölümüdür.

Bu adım adım açıklamalı kılavuzda, ek oluşturmak için Google Classroom API ile etkileşime geçeceksiniz. Kullanıcıların ek içeriğini görüntülemeleri için rotalar sağlarsınız. Görünümler, kullanıcının sınıftaki rolüne göre farklılık gösterir. Bu adım adım açıklamalı kılavuzda, öğrencinin göndermesi gerekmeyen içerik türü ekleri ele alınmaktadır.

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

• Aşağıdaki eklenti sorgu parametrelerini alıp kullanın:
  • addOnToken: Ek Keşfi Görünümü'ne iletilen bir yetkilendirme jetonu.
  • itemId: Eklenti ekini alan Ödev, Ödev Materyali veya Duyuru için benzersiz tanımlayıcı.
  • itemType: "courseWork", "courseWorkMaterials" veya "announcement".
  • courseId: Ödevin oluşturulduğu Google Classroom kursu için benzersiz bir tanımlayıcı.
  • attachmentId: Google Classroom tarafından eklenti eki oluşturulduktan sonra eklentiye atanan benzersiz tanımlayıcı.
• İçerik türü ekleri için kalıcı depolama alanı uygulayın.
• Ekler oluşturmak ve öğretmen görünümü ile öğrenci görünümü iFrame'lerini yayınlamak için rotalar sağlayın.
• Google Classroom eklentileri API'sine aşağıdaki istekleri gönderin:
  • Yeni bir ek oluşturun.
  • Giriş yapan kullanıcının öğrenci mi yoksa öğretmen mi olduğunu tanımlayan eklenti bağlamını alın.

İşiniz bittiğinde, öğretmen olarak giriş yaptığınızda Google Classroom kullanıcı arayüzü üzerinden ödevlerde içerik türünde ekler oluşturabilirsiniz. Sınıftaki öğretmenler ve öğrenciler de içeriği görüntüleyebilir.

Classroom API'yi etkinleştirme

Bu adımdan itibaren Classroom API'ye çağrı yapın. API'ye çağrı gönderebilmeniz için Google Cloud projeniz için etkinleştirilmiş olması gerekir. Google Classroom API kitaplık girişine gidin ve Etkinleştir'i seçin.

Ek Bulma Görünümü sorgu parametrelerini işleme

Daha önce de belirtildiği gibi, Google Classroom iframe'de Ek Keşif Görünümü'nü yüklerken sorgu parametrelerini iletir:

• courseId: Geçerli Classroom kursunun kimliği.
• itemId: Eklenti ekini alan CourseWork, CourseWorkMaterial veya duyuru için benzersiz bir tanımlayıcı.
• itemType: "courseWork", "courseWorkMaterials" veya "duyuru".
• addOnToken: Belirli Classroom eklentisi işlemlerini yetkilendirmek için kullanılan bir jeton.
• login_hint: Geçerli kullanıcının Google kimliği.

Bu adım adım açıklamalı kılavuzda courseId, itemId, itemType ve addOnToken ele alınmaktadır. Classroom API'ye çağrı yayınlarken bunları saklayın ve iletin.

Önceki adımda olduğu gibi, iletilen sorgu parametresi değerlerini oturumumuzda saklayın. Classroom'un bu sorgu parametrelerini iletebilmesi için tek fırsat bu olduğundan, bunu Ek Keşif Görünümü ilk açıldığında gerçekleştirmemiz önemlidir.

# Retrieve the itemId, courseId, and addOnToken query parameters.
if flask.request.args.get("itemId"):
    flask.session["itemId"] = flask.request.args.get("itemId")
if flask.request.args.get("itemType"):
    flask.session["itemType"] = flask.request.args.get("itemType")
if flask.request.args.get("courseId"):
    flask.session["courseId"] = flask.request.args.get("courseId")
if flask.request.args.get("addOnToken"):
    flask.session["addOnToken"] = flask.request.args.get("addOnToken")

İçerik türündeki ekler için kalıcı depolama alanı ekleme

Oluşturulan eklerin yerel kaydına ihtiyacınız vardır. Bu sayede, Classroom tarafından sağlanan tanımlayıcıları kullanarak öğretmenin seçtiği içeriği arayabilirsiniz.

Attachment için veritabanı şeması oluşturun. Sağladığımız örnekte, bir resim ve altyazı gösteren ekler gösterilmektedir. Attachment aşağıdaki özellikleri içerir:

• attachment_id: Eklerin benzersiz tanımlayıcısıdır. Classroom tarafından atanır ve ek oluşturulurken yanıtta döndürülür.
• image_filename: Gösterilecek resmin yerel dosya adı.
• image_caption: Resimle birlikte gösterilecek başlıktır.

class Attachment(db.Model):
    # The attachmentId is the unique identifier for the attachment.
    attachment_id = db.Column(db.String(120), primary_key=True)

    # The image filename to store.
    image_filename = db.Column(db.String(120))

    # The image caption to store.
    image_caption = db.Column(db.String(120))

Yeni rotalar oluşturma

Bu adım adım açıklamalı kılavuzun ilk adımında, uygulamamızda yeni sayfalar oluşturalım. Bu izinler, kullanıcıların eklentimiz aracılığıyla içerik oluşturmasına ve görüntülemesine olanak tanır.

Ek oluşturma rotası ekleme

Öğretmenin içerik seçmesi ve ek oluşturma isteği göndermesi için sayfalara ihtiyacınız vardır. Öğretmenin seçebileceği içerik seçeneklerini görüntülemek için /attachment-options rotasını uygulayın. İçerik seçimi ve oluşturma onayı sayfaları için de şablonlara ihtiyacınız vardır. Sağladığımız örneklerde bunlara yönelik şablonlar bulunur ve Classroom API'den gelen istek ve yanıtlar da gösterilebilir.

Alternatif olarak, yeni /attachment-options sayfası oluşturmak yerine mevcut Ek Keşfi Görünümü açılış sayfanızı içerik seçeneklerini gösterecek şekilde değiştirebileceğinizi unutmayın. İkinci adımda uygulanan SSO davranışını (ör. uygulama izinlerinin iptal edilmesi) korumak için bu alıştırma amacıyla yeni bir sayfa oluşturmanızı öneririz. Bu bilgiler, eklentinizi oluşturup test ederken faydalı olacaktır.

Öğretmen, sağladığımız örnekte küçük bir altyazılı resim grubundan seçim yapabilir. Başlıkları dosya adlarından türetilen ünlü önemli noktaların dört resmini sağladık.

@app.route("/attachment-options", methods=["GET", "POST"])
def attachment_options():
    """
    Render the attachment options page from the "attachment-options.html"
    template.

    This page displays a grid of images that the user can select using
    checkboxes.
    """

    # A list of the filenames in the static/images directory.
    image_filenames = os.listdir(os.path.join(app.static_folder, "images"))

    # The image_list_form_builder method creates a form that displays a grid
    # of images, checkboxes, and captions with a Submit button. All images
    # passed in image_filenames will be shown, and the captions will be the
    # title-cased filenames.

    # The form must be built dynamically due to limitations in WTForms. The
    # image_list_form_builder method therefore also returns a list of
    # attribute names in the form, which will be used by the HTML template
    # to properly render the form.
    form, var_names = image_list_form_builder(image_filenames)

    # If the form was submitted, validate the input and create the attachments.
    if form.validate_on_submit():

        # Build a dictionary that maps image filenames to captions.
        # There will be one dictionary entry per selected item in the form.
        filename_caption_pairs = construct_filename_caption_dictionary_list(
            form)

        # Check that the user selected at least one image, then proceed to
        # make requests to the Classroom API.
        if len(filename_caption_pairs) > 0:
            return create_attachments(filename_caption_pairs)
        else:
            return flask.render_template(
                "create-attachment.html",
                message="You didn't select any images.",
                form=form,
                var_names=var_names)

    return flask.render_template(
        "attachment-options.html",
        message=("You've reached the attachment options page. "
                "Select one or more images and click 'Create Attachment'."),
        form=form,
        var_names=var_names,
    )

Sorun eki oluşturma istekleri

Artık öğretmenin hangi içerik parçalarını eklemek istediğini bildiğinize göre, ödevmizde ek oluşturma konusunda Classroom API'ye istek gönderebilirsiniz. Classroom API'den yanıt aldıktan sonra ek ayrıntılarını veritabanınızda saklayın.

Classroom hizmetinin bir örneğini alarak başlayın:

def create_attachments(filename_caption_pairs):
    """
    Create attachments and show an acknowledgement page.

    Args:
        filename_caption_pairs: A dictionary that maps image filenames to
            captions.
    """
    # Get the Google Classroom service.
    classroom_service = googleapiclient.discovery.build(
        serviceName="classroom",
        version="v1",
        credentials=credentials)

courses.courseWork.addOnAttachments uç noktasına bir CREATE isteği gönderin. Öğretmen tarafından seçilen her resim için önce bir AddOnAttachment nesnesi oluşturun:

# Create a new attachment for each image that was selected.
attachment_count = 0
for key, value in filename_caption_pairs.items():
    attachment_count += 1

    # Create a dictionary with values for the AddOnAttachment object fields.
    attachment = {
        # Specifies the route for a teacher user.
        "teacherViewUri": {
            "uri":
                flask.url_for(
                    "load_content_attachment", _scheme='https', _external=True),
        },
        # Specifies the route for a student user.
        "studentViewUri": {
            "uri":
                flask.url_for(
                    "load_content_attachment", _scheme='https', _external=True)
        },
        # The title of the attachment.
        "title": f"Attachment {attachment_count}",
    }

Her ek için en az teacherViewUri, studentViewUri ve title alanları sağlanmalıdır. teacherViewUri ve studentViewUri, ek ilgili kullanıcı türü tarafından açıldığında yüklenen URL'leri temsil eder.

İsteğin gövdesinde uygun addOnAttachments uç noktasına AddOnAttachment nesnesini gönderin. Her istekle birlikte courseId, itemId, itemType ve addOnToken tanımlayıcılarını sağlayın.

# Use the itemType to determine which stream item type the teacher created
match flask.session["itemType"]:
    case "announcements":
        parent = classroom_service.courses().announcements()
    case "courseWorkMaterials":
        parent = classroom_service.courses().courseWorkMaterials()
    case _:
        parent = classroom_service.courses().courseWork()

# Issue a request to create the attachment.
resp = parent.addOnAttachments().create(
    courseId=flask.session["courseId"],
    itemId=flask.session["itemId"],
    addOnToken=flask.session["addOnToken"],
    body=attachment).execute()

Daha sonra doğru içeriği yükleyebilmek için yerel veritabanınızda bu ek için bir giriş oluşturun. Classroom, oluşturma isteğinin yanıtında benzersiz bir id değeri döndürür. Bu nedenle, bunu veritabanımızda birincil anahtar olarak kullanın. Ayrıca Classroom'un, Öğretmen ve Öğrenci Görünümlerini açarken attachmentId sorgu parametresini ilettiğini de unutmayın:

# Store the value by id.
new_attachment = Attachment(
    # The new attachment's unique ID, returned in the CREATE response.
    attachment_id=resp.get("id"),
    image_filename=key,
    image_caption=value)
db.session.add(new_attachment)
db.session.commit()

Bu noktada kullanıcıyı, ek oluşturduklarını onaylayan bir onay sayfasına yönlendirebilirsiniz.

Eklentinizden ek göndermeye izin verme

Google Workspace Marketplace SDK'sının Uygulama Yapılandırması sayfasındaki İzin Verilen Ek URI Önekleri alanına uygun adresleri eklemek için bu fırsattan yararlanabilirsiniz. Eklentiniz yalnızca bu sayfada listelenen URI ön eklerinden birinden ek oluşturabilir. Bu, ortadaki adam saldırılarının olasılığını azaltmaya yardımcı olan bir güvenlik önlemidir.

En basit yaklaşım, bu alana üst düzey alan adınızı girmektir (örneğin, https://example.com). https://localhost:<your port number>/, web sunucusu olarak yerel makinenizi kullanıyorsanız işe yarar.

Öğretmen ve Öğrenci Görünümleri için rota ekleme

Google Classroom eklentisinin yüklenmesi için dört iFrame vardır. Şimdiye kadar yalnızca Ek Keşif Görünümü iframe'ine hizmet veren rotalar oluşturdunuz. Ardından, öğretmen ve öğrenci görünümü iFrame'lerini de yayınlamak için rotalar ekleyin.

Öğretmen Görünümü iframe'i, öğrenci deneyiminin bir önizlemesini göstermek için gereklidir ancak isteğe bağlı olarak ek bilgiler veya düzenleme özellikleri de içerebilir.

Öğrenci Görünümü, eklenti eklerini açan her öğrenciye gösterilen sayfadır.

Bu alıştırma için hem öğretmen hem de öğrenci görünümünü sunan tek bir /load-content-attachment rota oluşturun. Sayfa yüklendiğinde kullanıcının öğretmen mi öğrenci mi olduğunu belirlemek için Classroom API yöntemlerini kullanın.

@app.route("/load-content-attachment")
def load_content_attachment():
    """
    Load the attachment for the user's role."""

    # Since this is a landing page for the Teacher and Student View iframes, we
    # need to preserve the incoming query parameters.
    if flask.request.args.get("itemId"):
        flask.session["itemId"] = flask.request.args.get("itemId")
    if flask.request.args.get("itemType"):
        flask.session["itemType"] = flask.request.args.get("itemType")
    if flask.request.args.get("courseId"):
        flask.session["courseId"] = flask.request.args.get("courseId")
    if flask.request.args.get("attachmentId"):
        flask.session["attachmentId"] = flask.request.args.get("attachmentId")

Bu noktada kullanıcının kimliğini doğrulamanız gerektiğini unutmayın. Burada login_hint sorgu parametresini de işlemeniz ve gerekirse kullanıcıyı yetkilendirme akışınıza yönlendirmeniz gerekir. Bu akış hakkında daha fazla bilgi için önceki adım adım açıklamalı kılavuzlarda ele alınan giriş kılavuzu ayrıntılarına bakın.

Ardından, öğe türüyle eşleşen getAddOnContext uç noktasına bir istek gönderin.

# Create an instance of the Classroom service.
classroom_service = googleapiclient.discovery.build(
    serviceName="classroom"
    version="v1",
    credentials=credentials)

# Use the itemType to determine which stream item type the teacher created
match flask.session["itemType"]:
    case "announcements":
        parent = classroom_service.courses().announcements()
    case "courseWorkMaterials":
        parent = classroom_service.courses().courseWorkMaterials()
    case _:
        parent = classroom_service.courses().courseWork()

addon_context_response = parent.getAddOnContext(
    courseId=flask.session["courseId"],
    itemId=flask.session["itemId"]).execute()

Bu yöntem, mevcut kullanıcının sınıftaki rolü hakkında bilgi döndürür. Kullanıcıya sunulan görünümü, rolüne göre değiştirin. Yanıt nesnesi'nde studentContext veya teacherContext alanlarından tam olarak biri doldurulur. Kullanıcıya nasıl hitap edeceğinizi belirlemek için bunları inceleyin.

Her durumda, veritabanımızdan hangi eki alacağınızı öğrenmek için attachmentId sorgu parametresi değerini kullanın. Bu sorgu parametresi, Öğretmen veya Öğrenci Görünümü URI'leri açıldığında sağlanır.

# Determine which view we are in by testing the returned context type.
user_context = "student" if addon_context_response.get(
    "studentContext") else "teacher"

# Look up the attachment in the database.
attachment = Attachment.query.get(flask.session["attachmentId"])

# Set the text for the next page depending on the user's role.
message_str = f"I see that you're a {user_context}! "
message_str += (
    f"I've loaded the attachment with ID {attachment.attachment_id}. "
    if user_context == "teacher" else
    "Please enjoy this image of a famous landmark!")

# Show the content with the customized message text.
return flask.render_template(
    "show-content-attachment.html",
    message=message_str,
    image_filename=attachment.image_filename,
    image_caption=attachment.image_caption,
    responses=response_strings)

Eklentiyi test etme

Ek oluşturmayı test etmek için aşağıdaki adımları uygulayın:

• [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. İçeriden yerleştirilmiş çerçeve açılır ve eklenti, Google Workspace Marketplace SDK'sının Uygulama Yapılandırması sayfasında belirttiğiniz Ekleme Kurulumu URI'sini yükler.
• Ödeve eklenecek bir içerik seçin.
• Ek oluşturma akışı tamamlandıktan sonra iframe'i kapatın.

Google Classroom'daki ödev oluşturma kullanıcı arayüzünde bir ek kartı görürsünüz. Öğretmen Görünümü iframe'ini açmak için kartı tıklayın ve doğru eki gördüğünüzden emin olun. Ata düğmesini tıklayın.

Öğrenci deneyimini test etmek için aşağıdaki adımları tamamlayın:

• Ardından, Classroom'da öğretmen test kullanıcısıyla aynı sınıftaki bir öğrenci test kullanıcısı olarak oturum açın.
• Sınıf çalışmaları sekmesinde sınav ödevini bulun.
• Ödevi genişletin ve öğrenci görünümü iFrame'ini açmak için ek kartını tıklayın.

Öğrenci için doğru eki gördüğünüzden emin olun.

Tebrikler! Bir sonraki adıma (etkinlik türündeki ekleri oluşturma) geçmeye hazırsınız.