Lampiran eksternal & penyerahan

Ini adalah panduan ketujuh di add-on Classroom seri panduan kami.

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

Anda juga menambahkan perilaku ke add-on untuk mengubah penetapan dengan add-on lampiran secara terprogram. Anda dapat memodifikasi tugas apa pun yang memiliki salah satu lampiran add-on Anda, terlepas dari siapa yang membuat tugas. Ini adalah sangat berguna untuk menyerahkan tugas setelah siswa menyelesaikan kegiatan, yang memberi tahu guru bahwa tugas yang diberikan telah selesai dan tugas siswa siap untuk ditinjau.

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

Penting: Sebelum mengikuti panduan ini, selesaikan panduan sebelumnya dalam seri video ini. Panduan ini memperluas aplikasi web yang dikembangkan dalam panduan kami. 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 belum pernah diperlukan sebelumnya, dan digunakan untuk membuat atau mengubah CourseWork tugas. Tambahkan cakupan ini ke daftar dalam project Cloud Google Workspace Marketplace SDK, Layar izin OAuth, dan kode server tertentu.

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 apa pun dalam panduan ini langkah waktu 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. Di beberapa Anda mungkin melakukannya dengan situs web atau aplikasi yang sudah ada. Untuk contoh ini, Anda perlu membuat laman web tiruan untuk bertindak sebagai situs eksternal. Anda memerlukan tombol atau link yang, saat diklik, membuka rute baru yang melakukan saran Alur CourseWork untuk membuat tugas baru.

Anda juga harus menambahkan tombol atau link agar pengguna dapat login jika Anda belum memilikinya. Anda akan memerlukan kredensial pengguna untuk membuat permintaan API, sehingga mereka harus menyelesaikan handshake OAuth 2.0. Lihat proses login untuk panduan spesifik.

Python

Contoh Python yang disediakan mengubah rute /index yang diperkenalkan pada langkah panduan 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 mewakili tujuan di situs Anda. Halaman ini akan mewakili konten yang akan dilampirkan ke CourseWork Anda penugasan 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>

Membuat file modul Python baru untuk menangani rute terkait CourseWork. Ini adalah coursework_routes.py dalam contoh yang kami berikan. Tambahkan hal berikut tiga rute; 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 client ID OAuth Anda; URI pengalihan yang sah di halaman Credentials project Google Cloud Anda. Untuk contoh yang diberikan, Anda harus menambahkan https://<<your server>>/index dan https://<<your server>>/coursework-assignment-callback.

Memeriksa kelayakan pembuatan add-on pengguna

Poin Penting: Selalu periksa apakah pengguna memenuhi syarat untuk membuat lampiran add-on sebelum mencoba membuat lampiran add-on. Kelayakan dapat berbeda bergantung pada pengguna, kursus, dan project Cloud Anda.

Ada beberapa prasyarat yang harus dipenuhi pengguna sebelum Anda dapat membuat lampiran add-on atas nama mereka. Untuk memudahkan, Google menyediakan Metode courses.checkAddOnCreationEligibility untuk menentukan apakah pengguna memenuhi prasyarat tersebut. Pengguna yang memenuhi prasyarat disebut sebagai pengguna yang memenuhi syarat.

Tambahkan pemeriksaan kelayakan ke penerapan rute pembuatan CourseWork. Kemudian, uji kolom isCreateAttachmentEligible dalam respons. Untuk memenuhi syarat pengguna, ikuti logika untuk membuat tugas dengan add-on lampiran. Jika tidak, buat Link Materi. Anda harus mengetahui ID materi di tempat pengguna ingin membuat tugas. Biasanya, Anda akan meminta pengguna untuk menentukan materi mana yang akan digunakan. Untuk mempermudah, kami menggunakan nilai {i>hard code<i} dalam pada contoh ini.

Poin Penting: Selalu buat lampiran add-on jika pengguna memenuhi syarat. Add-on menawarkan pengalaman pengguna dan developer yang terbaik untuk Menautkan Materi.

Catatan: Kolom isCreateAttachmentEligible hanya akan diisi jika memenuhi syarat. ID ini mungkin tidak ada dalam respons.

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 ...

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

  # Check whether the user can create add-on attachments.
  eligibility_response = (
      classroom_service.courses()
      .checkAddOnCreationEligibility(courseId=course_id)
      .execute()
  )
  is_create_attachment_eligible = eligibility_response.get("isCreateAttachmentEligible")

  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 tindakan berikut:

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

Poin Penting: Anda harus mengajukan dua permintaan secara terpisah. CourseWork tugas harus berhasil dibuat agar lampiran add-on baru dapat yang dikaitkan dengan ID tugas.

Python

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

Buat Materi Link

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

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

Python

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 telah dibuat

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

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

Untuk mendemonstrasikan ini, Anda akan menambahkan rute untuk memodifikasi item aliran data tertentu. Gunakan ini untuk memverifikasi bahwa Anda dapat mengakses dan mengubah item aliran yang Anda buat dengan menggunakan API dan dibuat oleh pengajar melalui UI Google Classroom.

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

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>

Membuat rute baru untuk menangani rute terkait CourseWork. Hal ini dilakukan pada 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 iframe dan kueri kami parameter untuk deskripsi setiap iframe. Semua petunjuk yang diberikan dalam panduan ini menganggap add-on dapat digunakan dalam konteks iframe.

Untuk menyederhanakannya, contoh yang diberikan menggunakan materi {i>hard-code<i} dan pengenal tugas. Anda bisa mendapatkan ID ini dengan membuat permintaan menggunakan kredensial pengajar ke metode get dan list dari courses serta Referensi courseWork. Kolom tersebut juga ditampilkan sebagai respons saat membuat courseWork tugas.

Menguji pembuatan Material Link

Jalankan server Anda, lalu buka halaman indeks dan login sebagai pengguna pengajar tanpa layanan Google Workspace for Education Teaching & Lisensi Learning atau Plus. Anda dapat mengalihkan status lisensi pengguna dari domain uji coba Anda konsol Admin.Klik Buat Tugas Kursus lalu buka UI Google Classroom dan verifikasi bahwa tugas dengan Lampiran Material link telah dibuat. Lampiran harus menampilkan judul laman web yang ditautkan dan URL.

Menguji pembuatan lampiran add-on

Kembali ke halaman indeks dan login sebagai pengguna pengajar dengan Google Workspace for Education Teaching &amp; Lisensi Learning atau Plus. Klik Create a CourseWork Assignment lalu buka UI Google Classroom dan verifikasi bahwa ada tugas dengan lampiran add-on telah dibuat. Lampiran harus menampilkan nama aplikasi add-on dan judul yang ditentukan dalam kode Anda.

Modifikasi tugas pengujian

Kembali ke halaman indeks dan pastikan Anda login sebagai pengguna pengajar dengan Pengajar Lisensi Learning atau Plus. Klik tombol Modify a CourseWork Tugas, lalu kembali ke UI Google Classroom dan pastikan judul tugas telah diubah.

Selamat! Anda telah menyelesaikan rangkaian panduan.