Lampiran eksternal & penyerahan

Ini adalah panduan ketujuh dalam seri panduan add-on Classroom.

Dalam panduan ini, Anda akan menambahkan perilaku ke aplikasi web untuk membuat lampiran add-on dari luar Google Classroom. Gunakan perilaku ini untuk memungkinkan pengguna membuat lampiran add-on dari produk atau situs yang ada. Hal ini juga merupakan tambahan yang bagus untuk integrasi CourseWork karena Anda mengarahkan traffic yang ada ke pengalaman pengguna yang lebih baik yang ditawarkan oleh add-on Anda tanpa mengubah alurnya. Proses yang disarankan dijelaskan di halaman panduan Membuat lampiran di luar Classroom.

Anda juga menambahkan perilaku ke add-on untuk mengubah tugas dengan lampiran add-on secara terprogram. Anda dapat mengubah tugas apa pun yang memiliki salah satu lampiran add-on Anda, terlepas dari siapa yang membuat tugas tersebut. Fitur ini sangat berguna untuk menyerahkan tugas setelah siswa menyelesaikan aktivitas, yang menandakan kepada pengajar bahwa tugas yang diberikan telah selesai dan tugas siswa siap untuk ditinjau.

Anda memperluas versi akhir add-on yang mendukung content-type atau lampiran activity-type. Lampiran content-type digunakan dalam panduan ini.

Penting: Sebelum mengikuti panduan ini, selesaikan panduan sebelumnya dalam seri ini. Panduan ini memperluas aplikasi web yang dikembangkan dalam panduan sebelumnya. Anda dapat mendownload kode sumber lengkap untuk semua panduan dari halaman Ringkasan. Kode untuk panduan khusus ini dapat ditemukan di direktori /07-external-attachments/.

Menambahkan cakupan OAuth pengelolaan tugas

Pastikan aplikasi Anda meminta cakupan berikut:

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

Cakupan classroom.coursework.students sebelumnya tidak diperlukan, dan digunakan untuk membuat atau mengubah penetapan CourseWork. Tambahkan cakupan ini ke daftar cakupan di Google Workspace Marketplace SDK, layar izin OAuth, dan kode server project Cloud Anda.

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",
  ]

Membuat tugas di Classroom

Penting: Jangan ubah pengalaman iframe Anda dalam langkah-langkah ini. Sebagai gantinya, tambahkan perilaku untuk membuat lampiran add-on dari halaman web di luar Classroom.

Menambahkan tombol ke halaman web non-iframe

Alur yang dijelaskan dalam panduan ini memungkinkan pengguna membuat tugas dan lampiran Google Classroom dari produk non-Google. Pada praktiknya, ini kemungkinan adalah situs atau aplikasi yang sudah ada. Untuk contoh ini, Anda perlu membuat halaman web tiruan yang berfungsi sebagai situs eksternal. Anda memerlukan tombol atau link yang, jika diklik, membuka rute baru yang menjalankan alur saran CourseWork untuk membuat tugas baru.

Anda juga harus menambahkan tombol atau link untuk mengizinkan pengguna login jika Anda belum memilikinya. Anda akan memerlukan kredensial pengguna untuk membuat permintaan API berikutnya, sehingga pengguna harus menyelesaikan handshake OAuth 2.0. Lihat penjelasan proses login untuk mendapatkan panduan khusus.

Python

Contoh Python yang diberikan mengubah rute /index yang diperkenalkan di langkah penelusuran pertama.

<!-- /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>

Tambahkan template HTML untuk merepresentasikan tujuan di situs Anda. Halaman ini akan menampilkan konten yang akan dilampirkan ke tugas CourseWork Anda.

<!-- /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>

Buat file modul Python baru untuk menangani rute terkait CourseWork. Ini adalah coursework_routes.py dalam contoh yang kami berikan. Tambahkan tiga rute berikut; perhatikan bahwa Anda akan mengisi beberapa konten nanti.

# /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")

Penting: Tambahkan rute callback OAuth baru ke URI pengalihan yang diotorisasi client ID OAuth di halaman Kredensial project Google Cloud Anda. Untuk contoh yang kami berikan, Anda harus menambahkan https://<<your server>>/index dan https://<<your server>>/coursework-assignment-callback.

Memeriksa kelayakan pembuatan lampiran pengguna

Poin Utama: Selalu periksa apakah pengguna memenuhi syarat untuk membuat lampiran add-on sebelum mencoba membuat lampiran add-on. Kelayakan berbeda-beda menurut pengguna dan project Google Cloud yang meminta dan dapat berubah dari waktu ke waktu.

Ada beberapa prasyarat yang harus dipenuhi pengguna sebelum Anda dapat membuat lampiran add-on atas nama mereka. Untuk mempermudah, Google menyediakan metode userProfiles.checkUserCapability untuk menentukan apakah pengguna memenuhi prasyarat ini. Pengguna yang memenuhi prasyarat disebut sebagai pengguna yang memenuhi syarat.

Penting: Pemeriksaan kelayakan menggunakan Classroom API dalam pratinjau publik dan tersedia di versi pratinjau V1_20240930_PREVIEW dan yang lebih baru. Untuk menggunakan metode API dalam pratinjau publik, Anda harus menjadi bagian dari Program Pratinjau Developer Google Workspace dan melakukan penyiapan tambahan di luar penggunaan Classroom API yang umum.

Tambahkan pemeriksaan kelayakan ke penerapan rute pembuatan CourseWork. Kemudian, uji kolom allowed dalam respons. Untuk pengguna yang memenuhi syarat, ikuti logika untuk membuat tugas dengan lampiran add-on. Jika tidak, buat Link Material. Anda harus mengetahui ID kursus tempat pengguna ingin membuat tugas. Biasanya, Anda akan meminta pengguna untuk menentukan kursus mana yang akan digunakan. Agar lebih sederhana, kita menggunakan nilai hardcode dalam contoh ini.

Poin Penting: Selalu buat lampiran add-on jika pengguna memenuhi syarat. Add-on menawarkan pengalaman pengguna dan developer yang lebih baik daripada Link Materi.

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.

Membuat tugas dengan lampiran add-on untuk pengguna yang memenuhi syarat

Jika pengguna memenuhi syarat untuk membuat lampiran add-on, lakukan hal berikut:

1. Kirim permintaan API untuk membuat tugas courseWork di Google Classroom tanpa lampiran.
2. Ekstrak id tugas yang baru dibuat.
3. Buat CourseWork AddOnAttachment baru.
4. Mengirim permintaan untuk membuat lampiran add-on pada tugas yang baru dibuat di Google Classroom.

Poin Penting: Anda harus mengirimkan kedua permintaan secara terpisah. Penetapan CourseWork harus berhasil dibuat agar lampiran add-on baru dapat dikaitkan dengan ID tugas.

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()
  )

Membuat Materi Link

Poin Penting: Jika produk Anda sudah membuat penetapan CourseWork, kemungkinan produk tersebut sudah mengikuti alur yang ditampilkan di sini.

Jika pengguna tidak memenuhi syarat untuk membuat lampiran add-on, buat Materi Link sebagai gantinya dengan melakukan hal berikut:

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()
    )

Mengubah tugas yang sudah dibuat

Poin Penting: Manfaat utama lampiran add-on adalah bahwa lampiran tersebut memberi Anda kemampuan untuk melakukan permintaan API pada item streaming induk.

Anda dapat mengakses, mengubah, menyerahkan, mengklaim kembali, atau mengembalikan item feed Google Classroom yang memiliki setidaknya satu lampiran add-on Anda, terlepas dari siapa yang membuat item feed tersebut. Item forum adalah Announcement, CourseWork tugas, atau CourseWorkMaterial.

Untuk mendemonstrasikannya, Anda akan menambahkan rute untuk mengubah item streaming tertentu. Gunakan metode ini untuk memverifikasi bahwa Anda dapat mengakses dan mengubah item streaming yang dibuat oleh Anda menggunakan API dan yang dibuat oleh pengajar melalui UI Google Classroom.

Tambahkan satu link atau tombol lagi ke halaman web yang pertama kali Anda edit dalam panduan ini. Tindakan ini akan membuka rute baru untuk mengubah tugas.CourseWork

Python

Contoh Python yang diberikan mengubah rute /index yang telah diubah sebelumnya dalam panduan ini.

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

Buat rute baru untuk menangani rute terkait CourseWork. Hal ini ada di file coursework_routes.py dalam contoh yang kami berikan.

# 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()
)

Menguji add-on

Penting: Pada tahap pengembangan ini, Anda hanya dapat menguji aplikasi di iframe add-on Classroom. Baca halaman panduan parameter iframe dan kueri kami untuk mengetahui deskripsi setiap iframe. Semua petunjuk yang diberikan dalam panduan ini mengasumsikan add-on dapat digunakan dalam konteks iframe.

Agar tetap sederhana, contoh yang diberikan menggunakan ID kursus dan tugas yang di-hardcode. Anda bisa mendapatkan ID ini dengan membuat permintaan menggunakan kredensial pengajar ke metode get dan list dari resource courses dan courseWork. ID ini juga ditampilkan dalam respons saat membuat penetapan courseWork.

Pembuatan Materi Link Uji

Jalankan server Anda, lalu buka halaman indeks dan login sebagai pengguna pengajar tanpa lisensi Google Workspace for Education Teaching & Learning atau Plus. Anda dapat mengubah status lisensi pengguna dari Konsol Admin domain pengujian Anda.Klik tombol Buat Tugas CourseWork, lalu buka UI Google Classroom dan verifikasi bahwa tugas dengan lampiran Materi Link telah dibuat. Lampiran harus menampilkan judul halaman web yang ditautkan dan URL.

Menguji pembuatan lampiran add-on

Kembali ke halaman indeks dan login sebagai pengguna pengajar dengan lisensi Teaching and Learning atau Plus Google Workspace for Education. Klik tombol Buat Tugas CourseWork, lalu buka UI Google Classroom dan verifikasi bahwa tugas dengan lampiran add-on telah dibuat. Lampiran harus menampilkan nama aplikasi add-on dan judul yang ditentukan dalam kode Anda.

Pengujian modifikasi tugas

Kembali ke halaman indeks dan pastikan Anda login sebagai pengguna pengajar dengan lisensi Teaching & Learning atau Plus. Klik tombol Modify a CourseWork Assignment, lalu kembali ke UI Google Classroom dan verifikasi bahwa judul tugas telah diubah.

Selamat! Anda telah menyelesaikan rangkaian panduan.