Harici ekler ve teslim etme

Bu, Classroom eklentileriyle ilgili rehberlik serisinin yedinci rehberliğidir.

Bu adım adım açıklamalı kılavuzda, Google Classroom dışından eklenti ekleri oluşturmak için bir web uygulamasına davranış ekleyeceksiniz. Kullanıcılarınızın mevcut ürününüzden veya web sitenizden eklenti ekleri oluşturmasına izin vermek için bu davranışı kullanın. Bu, CourseWork entegrasyonu için de harika bir eklentidir. Çünkü mevcut trafiği, akışlarını değiştirmeden eklentinizin sunduğu gelişmiş kullanıcı deneyimine yönlendirirsiniz. Önerilen süreç, Classroom dışında ek oluşturma rehber sayfamızda açıklanmaktadır.

Ayrıca, ekli ödevleri programatik olarak değiştirmek için eklentinize davranış da ekleyebilirsiniz. Ödevi kimin oluşturduğuna bakılmaksızın, eklenti eklerinizden birinin bulunduğu tüm ödevleri değiştirebilirsiniz. Bu özellik, özellikle bir öğrenci etkinliği tamamladıktan sonra ödevleri göndermek için kullanışlıdır. Öğretmene, atanan görevlerin tamamlandığını ve öğrencinin çalışmasının incelemeye hazır olduğunu bildirir.

Content-type veya activity-type eklerini destekleyen eklentinizin son sürümünü yayınlarsınız. Bu kılavuzda içerik türü eki kullanılır.

Ödev yönetimi OAuth kapsamını ekleme

Uygulamanızın aşağıdaki kapsamları istediğinden emin olun:

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

classroom.coursework.students kapsamı daha önce gerekli değildi ve CourseWork atamaları oluşturmak veya değiştirmek için kullanılır. Bu kapsamı, Cloud projenizin Google Workspace Marketplace SDK, OAuth kullanıcı rızası ekranı ve sunucu kodunuzdaki kapsam listelerine ekleyin.

Python

  SCOPES = [
    "https://www.googleapis.com/auth/classroom.addons.teacher",
    "https://www.googleapis.com/auth/classroom.addons.student",
    "https://www.googleapis.com/auth/classroom.coursework.students",
  ]

Classroom'da ödev oluşturma

Iframe'siz web sayfasına düğme ekleme

Bu kılavuzda açıklanan akış, kullanıcının Google dışı bir üründen Google Classroom ödevleri ve ekleri oluşturmasına olanak tanır. Bu, uygulamada muhtemelen mevcut web siteniz veya uygulamanızdır. Bu örnek için, harici site görevi görecek bir sahte web sayfası oluşturmanız gerekir. Tıklandığında yeni bir ödev oluşturmak için önerilen akışı gerçekleştiren yeni bir rota açan bir düğme veya bağlantı gerekir.CourseWork

Ayrıca, henüz eklemediyseniz kullanıcının oturum açmasına izin verecek bir düğme veya bağlantı eklemeniz gerekir. Sonraki API isteklerini yapmak için kullanıcı kimlik bilgilerine ihtiyacınız olacağından kullanıcıların OAuth 2.0 el sıkışmasını tamamlaması gerekir. Ayrıntılı bilgi için oturum açma rehberine bakın.

Python

Sağlanan Python örneği, ilk adımda tanıtılan /index rotasını değiştirir.

<!-- /webapp/templates/index.html -->
<a href="clear-credentials.html">Logout</a>
<a href="start-auth-flow.html">Login</a>

<br>

<a href="create-coursework-assignment.html">Create a CourseWork Assignment</a>

Web sitenizdeki bir hedefi temsil etmek için HTML şablonu ekleyin. Bu sayfada, CourseWork ödevinize eklenecek içerik gösterilir.

<!-- /webapp/templates/example-coursework-assignment.html -->
<h1>CourseWork assignment loaded!</h1>
<p>You've loaded a CourseWork assignment! It was created from an external web page.</p>

CourseWork ile ilgili rotaları işlemek için yeni bir Python modülü dosyası oluşturun. Bu, sağlanan örneğimizde coursework_routes.py'dır. Aşağıdaki üç rotayı ekleyin. İçeriğin bir kısmını daha sonra dolduracağınızı unutmayın.

# /webapp/coursework_routes.py
@app.route("/create-coursework-assignment")
def create_coursework_assignment():
  """
  Completes the assignment creation flow.
  """

  # Check that the user is signed in. If not, perform the OAuth 2.0
  # authorization flow.
  credentials = get_credentials()

  if not credentials:
    return start_auth_flow("coursework_assignment_callback")

  # Construct the Google Classroom service.
  classroom_service = get_classroom_service()

  pass  # To be completed later.

@app.route("/example-coursework-assignment/<assignment_type>")
def example_coursework_assignment(assignment_type):
  """
  Renders the "example-coursework-assignment.html" template.
  """
  return flask.render_template(
      "example-coursework-assignment.html", assignment_type=assignment_type
  )

@app.route("/coursework-assignment-callback")
def coursework_assignment_callback():
  """
  Completes the OAuth 2.0 handshake and stores credentials in the session.
  This is identical to the callback introduced in the sign-in walkthrough,
  but redirects the user to the index page instead of the attachment
  discovery page.
  """
  flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
      CLIENT_SECRETS_FILE,
      scopes=SCOPES,
      state=flask.session["state"],
      redirect_uri=flask.url_for("coursework_assignment_callback", _external=True),
  )

  flow.fetch_token(authorization_response=flask.request.url)

  credentials = flow.credentials
  flask.session["credentials"] = session_credentials_to_dict(
      credentials
  )

  # Close the current window and redirect the user to the index page.
  return flask.render_template("close-me.html", redirect_destination="index")

Kullanıcının ek oluşturma uygunluğunu kontrol etme

Kullanıcı adına eklenti ekleri oluşturabilmeniz için kullanıcının karşılaması gereken çeşitli ön koşullar vardır. Google, kullanıcıların bu ön koşulları karşılayıp karşılamadığını belirlemek için kolaylık sağlamak amacıyla userProfiles.checkUserCapability yöntemini sunar. Ön koşulları karşılayan kullanıcıya uygun kullanıcı denir.

Uygunluk kontrolünü CourseWork oluşturma rotası uygulamasına ekleyin. Ardından, yanıttaki allowed alanını test edin. Uygun kullanıcılar için eklenti eki içeren bir ödev oluşturmak üzere mantığı izleyin. Aksi takdirde LinkMaterial oluşturun. Kullanıcının ödev oluşturmak istediği kursun kimliğini bilmeniz gerekir. Normalde, kullanıcıdan hangi kursun kullanılacağını belirtmesini istersiniz. Kolay anlaşılması için bu örnekte sabit kodlanmış bir değer kullanıyoruz.

Python

# /webapp/coursework_routes.py
@app.route("/create-coursework-assignment")
def create_coursework_assignment():
  """
  Completes the assignment creation flow.
  """
  # ... Check that the user is signed in and get the Classroom service ...

  # Check whether the user can create add-on attachments.
  eligibility_response = (
      classroom_service.userProfiles()
      .checkUserCapability(
        userId="me",
        capability="CREATE_ADD_ON_ATTACHMENT",
        # The previewVersion is necessary while the method is available in the
        # Workspace Developer Preview Program.
        previewVersion="V1_20240930_PREVIEW",
      ).execute()
  )
  is_create_attachment_eligible = eligibility_response.get("allowed")

  if is_create_attachment_eligible:
    # See the "Create an assignment with add-on attachment for eligible users" section for implementation.
  if not is_create_attachment_eligible:
    # See the "Create a Link Material" section for implementation.

Uygun kullanıcılar için eklenti eki içeren bir ödev oluşturma

Kullanıcı, eklenti eki oluşturmaya uygunsa aşağıdakileri yapın:

  1. Google Classroom'da ek içermeyen bir courseWork ödevi oluşturmak için API isteği gönderin.
  2. Yeni oluşturulan ödevin id değerini çıkarın.
  3. Yeni bir CourseWork AddOnAttachment oluşturun.
  4. Google Classroom'da yeni oluşturulan ödevde eklenti eki oluşturma isteği gönderin.

Python

# The ID of the course to which the assignment will be added.
course_id = 1234567890  # TODO(developer) Replace with an actual course ID.

# /webapp/coursework_routes.py
if is_create_attachment_eligible:
  # Create an assignment.
  coursework = {
      "title": "My CourseWork Assignment with Add-on Attachment",
      "description": "Created using the Classroom CourseWork API.",
      "workType": "ASSIGNMENT",
      "state": "DRAFT",  # Set to 'PUBLISHED' to assign to students.
  }

  # Issue a request to create the assignment.
  create_assignment_response = (
      classroom_service.courses()
      .courseWork()
      .create(courseId=course_id, body=coursework)
      .execute()
  )

  # Create an add-on attachment that links to the selected content and
  # associate it with the new assignment.
  content_url = flask.url_for(
      "example_coursework_assignment",
      assignment_type="add-on-attachment",
      _scheme="https",
      _external=True,
  )

  # Construct an AddOnAttachment instance.
  attachment = {
      "teacherViewUri": {"uri": content_url},
      "studentViewUri": {"uri": content_url},
      "title": f'Test Attachment for Assignment {create_assignment_response.get("id")}',
  }

  # Issue a request to create the attachment.
  add_on_attachment_response = (
      classroom_service.courses()
      .courseWork()
      .addOnAttachments()
      .create(
          courseId=course_id,
          itemId=create_assignment_response.get("id"),  # ID of the new assignment.
          body=attachment,
      )
      .execute()
  )

Kullanıcı, eklenti ekleri oluşturmaya uygun değilse bunun yerine aşağıdaki adımları uygulayarak bir Materyal Bağlantısı oluşturun:

Python

# The ID of the course to which the assignment will be added.
course_id = 1234567890  # TODO(developer) Replace with an actual course ID.

if not is_create_attachment_eligible:
    coursework = {
        "title": "My CourseWork Assignment with Link Material",
        "description": "Created using the Classroom CourseWork API.",
        "workType": "ASSIGNMENT",
        "state": "DRAFT",  # Set to 'PUBLISHED' to assign to students.
        # Specify the URL for your content as a Link Material.
        "materials": [
            {
                "link": {
                    "url": flask.url_for(
                        "example_coursework_assignment",
                        assignment_type="link-material",
                        _scheme="https",
                        _external=True,
                    )
                }
            }
        ],
    }

    # Issue a request to create the assignment.
    assignment_response = (
        classroom_service.courses()
        .courseWork()
        .create(courseId=course_id, body=coursework)
        .execute()
    )

Daha önce oluşturulmuş bir ödevi değiştirme

Akış öğesini kimin oluşturduğuna bakılmaksızın, eklenti eklerinizden en az birini içeren tüm Google Classroom akış öğelerine erişebilir, bunları değiştirebilir, gönderebilir, geri alabilir veya iade edebilirsiniz. Akış öğeleri; Announcement, CourseWork ödev veya CourseWorkMaterial olabilir.

Bunu göstermek için belirli bir akış öğesini değiştirecek bir rota ekleyeceksiniz. Bu yöntemi kullanarak, API ve Google Classroom kullanıcı arayüzü aracılığıyla öğretmenler tarafından oluşturulan akış öğelerine erişip bunları değiştirebildiğinizi doğrulayın.

Bu adım adım açıklama bölümünde ilk olarak düzenlediğiniz web sayfasına bir bağlantı veya düğme daha ekleyin. CourseWork ödevi değiştirmek için yeni bir rota açılır.

Python

Sağlanan Python örneği, /index rotasını değiştirir. Bu rota, bu kılavuzun önceki bölümlerinde değiştirilmişti.

<!-- /webapp/templates/index.html -->
<a href="modify-coursework-assignment.html">Create a CourseWork Assignment</a>

CourseWork ile ilgili rotaları işlemek için yeni bir rota oluşturun. Bu, sağladığımız örnekteki coursework_routes.py dosyasında yer alır.

# Check that the user is signed in.
credentials = get_credentials()

if not credentials:
  return start_auth_flow("coursework_assignment_callback")

# Get the Google Classroom service.
classroom_service = get_classroom_service()

# The ID of the course to which the assignment will be added.
# Ordinarily, you'll prompt the user to specify which course to use. For
# simplicity, we use a hard-coded value in this example.
course_id = 1234567890  # TODO(developer) Replace with an actual course ID.
assignment_id = 1234567890  # TODO(developer) Replace with an actual assignment ID.

# Retrieve details about the CourseWork assignment.
get_coursework_response = (
    classroom_service.courses()
    .courseWork()
    .get(courseId=course_id, id=assignment_id)
    .execute()
)

# Alter the current title.
assignment_title = f"{get_coursework_response.get('title')} (Modified by API request)"

# Issue a request to modify the assignment.
modify_coursework_response = (
    classroom_service.courses()
    .courseWork()
    .patch(
        courseId=course_id,
        id=assignment_id,
        updateMask="title",
        body={"title": assignment_title},
    )
    .execute()
)

Eklentiyi test etme

İşleri basitleştirmek için sağlanan örneklerde sabit kodlu kurs ve ödev tanımlayıcıları kullanılır. Bu tanımlayıcıları, courses ve courseWork kaynaklarının get ve list yöntemlerine öğretmen kimlik bilgileriyle istekte bulunarak alabilirsiniz. Ayrıca, courseWork ödev oluştururken yanıtta da döndürülürler.

Sunucunuzu çalıştırın, ardından dizin sayfanıza gidin ve Google Workspace for Education Teaching & Learning veya Plus lisansı olmayan bir öğretmen kullanıcısı olarak oturum açın. Test alanınızın yönetici konsolundan bir kullanıcının lisans durumunu açıp kapatabilirsiniz.Ödev Oluştur düğmesini tıklayın, ardından Google Classroom kullanıcı arayüzünü açıp Materyal Bağlantısı eklenmiş bir ödevin oluşturulduğunu doğrulayın. Ekte, bağlantısı verilen web sayfasının başlığı ve bir URL gösterilmelidir.

Eklenti eki oluşturmayı test etme

Dizin sayfasına dönün ve Google Workspace for Education Teaching & Learning veya Plus lisansı olan bir öğretmen kullanıcısı olarak oturum açın. Ödev Oluştur düğmesini tıklayın, ardından Google Classroom kullanıcı arayüzünü açıp eklenti eki içeren bir ödevin oluşturulduğunu doğrulayın. Ekte, eklenti uygulamanızın adı ve kodunuzda belirtilen başlık gösterilmelidir.

Ödev değişikliğini test etme

Dizin sayfasına dönün ve Teaching & Learning veya Plus lisansıyla öğretmen kullanıcısı olarak oturum açtığınızdan emin olun. Modify a CourseWork Assignment (Bir CourseWork Ödevini Değiştir) düğmesini tıklayın, ardından Google Classroom kullanıcı arayüzüne dönün ve ödev başlığının değiştirildiğini doğrulayın.

Tebrikler! Adım adım açıklama serisini tamamladınız.