Załączniki zewnętrzne i oddanie

To siódmy samouczek z serii samouczków dotyczących dodatków do Classroom.

W tym samouczku dodasz do aplikacji internetowej funkcję tworzenia załączników dodatków poza Google Classroom. Dzięki tej funkcji użytkownicy będą mogli tworzyć załączniki dodatków z poziomu Twojej dotychczasowej usługi lub witryny. Jest to też świetne uzupełnienie integracji z CourseWork, ponieważ możesz kierować dotychczasowy ruch do ulepszonej wersji dodatku bez zmiany sposobu korzystania z niego. Sugerowany proces opisujemy na stronie Tworzenie załączników poza Classroom.

Dodasz też do dodatku funkcję programowego modyfikowania projektu za pomocą załączników dodatków. Możesz modyfikować dowolny projekt, który ma załącznik dodatku, niezależnie od tego, kto go utworzył. Jest to szczególnie przydatne w przypadku oddawania projektów po ukończeniu przez ucznia zadania. Dzięki temu nauczyciel wie, że zadane zadania zostały wykonane, a praca ucznia jest gotowa do sprawdzenia.

Rozszerzysz ostateczną wersję dodatku, która obsługuje content-type lub activity-type attachments. W tym przewodniku używamy załącznika typu content-type.

Dodawanie zakresu OAuth do zarządzania projektami

Upewnij się, że Twoja aplikacja wysyła żądania dotyczące tych zakresów:

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

Zakres classroom.coursework.students nie był wcześniej potrzebny. Służy do tworzenia i modyfikowania projektów CourseWork. Dodaj ten zakres do list zakresów w pakiecie SDK Google Workspace Marketplace, na ekranie zgody OAuth i w kodzie serwera w projekcie Cloud.

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

Tworzenie projektu w Classroom

Dodawanie przycisków do strony internetowej bez elementu iframe

Proces opisany w tym samouczku umożliwia użytkownikowi tworzenie projektów i załączników Google Classroom z poziomu usługi innej niż Google. W praktyce jest to prawdopodobnie Twoja dotychczasowa witryna lub aplikacja. W tym przykładzie musisz utworzyć fikcyjną stronę internetową, która będzie pełnić rolę witryny zewnętrznej. Potrzebujesz przycisku lub linku, który po kliknięciu otwiera nową ścieżkę wykonującą sugerowany CourseWork proces w celu utworzenia nowego projektu.

Musisz też dodać przycisk lub link, który umożliwi użytkownikowi zalogowanie się, jeśli jeszcze go nie masz. Do wysyłania kolejnych żądań do interfejsu API potrzebne są dane logowania użytkownika, dlatego musi on przejść proces uzgadniania OAuth 2.0. Szczegółowe wskazówki znajdziesz w samouczku dotyczącym logowania.

Python

Podany przykład w Pythonie modyfikuje ścieżkę /index, która została wprowadzona w pierwszym kroku samouczka.

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

Dodaj szablon HTML, który będzie reprezentować miejsce docelowe w Twojej witrynie. Ta strona będzie reprezentować treści, które zostaną dołączone do projektu CourseWork.

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

Utwórz nowy plik modułu Python, który będzie obsługiwać ścieżki związane z CourseWork. W podanym przykładzie jest to plik coursework_routes.py. Dodaj te 3 ścieżki. Pamiętaj, że niektóre treści uzupełnisz później.

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

Sprawdzanie, czy użytkownik może tworzyć załączniki

Zanim będzie można utworzyć załączniki dodatków w imieniu użytkownika, musi on spełnić kilka wymagań wstępnych. Aby ułatwić Ci pracę, Google udostępnia metodę userProfiles.checkUserCapability, która pozwala sprawdzić, czy użytkownik spełnia te wymagania. Użytkownik, który spełnia wymagania wstępne, jest określany jako uprawniony.

Dodaj sprawdzanie uprawnień do implementacji ścieżki tworzenia CourseWork. Następnie przetestuj pole allowed w odpowiedzi. W przypadku uprawnionych użytkowników postępuj zgodnie z logiką, aby utworzyć projekt z załącznikiem dodatku załącznik. W przeciwnym razie utwórz materiał z linkiem. Musisz znać identyfikator kursu, w którym użytkownik chce utworzyć projekt. Zazwyczaj wyświetlasz użytkownikowi prośbę o wybranie kursu. W tym przykładzie dla uproszczenia używamy zakodowanej na stałe wartości.

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.

Tworzenie projektu z załącznikiem dodatku dla uprawnionych użytkowników

Jeśli użytkownik może tworzyć załączniki dodatków, wykonaj te czynności:

  1. Wyślij żądanie do interfejsu API, aby utworzyć projekt courseWork w Google Classroom bez załączników.
  2. Wyodrębnij id nowo utworzonego projektu.
  3. Utwórz nowy projekt AddOnAttachment.
  4. Wyślij żądanie utworzenia załącznika dodatku w nowo utworzonym projekcie w Google Classroom.

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

Jeśli użytkownik nie może tworzyć załączników dodatków, utwórz zamiast tego materiał z linkiem, wykonując te czynności:

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

Modyfikowanie utworzonego projektu

Możesz uzyskiwać dostęp do dowolnego elementu strumienia Google Classroom, który ma co najmniej 1 załącznik dodatku, oraz go modyfikować, oddawać, odzyskiwać lub zwracać, niezależnie od tego, kto go utworzył. Elementy strumienia to dowolne Announcement, CourseWork projekt lub CourseWorkMaterial.

Aby to zademonstrować, dodasz ścieżkę do modyfikowania danego elementu strumienia. Za pomocą tej metody możesz sprawdzić, czy masz dostęp do elementów strumienia utworzonych przez Ciebie za pomocą interfejsu API oraz przez nauczyciela w interfejsie Google Classroom i czy możesz je modyfikować.

Dodaj jeszcze 1 link lub przycisk do strony internetowej, którą edytowałeś(-aś) w tym samouczku. Powinien on otwierać nową ścieżkę do modyfikowania projektu CourseWork.

Python

Podany przykład w Pythonie modyfikuje ścieżkę /index, która została zmodyfikowana wcześniej w tym samouczku.

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

Utwórz nową ścieżkę do obsługi ścieżek związanych z CourseWork. W podanym przykładzie znajduje się ona w pliku coursework_routes.py.

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

Testowanie dodatku

Aby uprościć, w podanych przykładach używamy zakodowanych na stałe identyfikatorów kursów i projektów. Możesz je uzyskać, wysyłając żądania z danymi logowania nauczyciela do metod get i list zasobów courses i courseWork. Są one też zwracane w odpowiedzi podczas tworzenia projektów courseWork.

Uruchom serwer, a następnie otwórz stronę indeksu i zaloguj się jako nauczyciel bez licencji Google Workspace for Education Teaching &Learning lub Plus. Stan licencji użytkownika możesz zmienić w konsoli administracyjnej domeny testowej.Kliknij przycisk Utwórz projekt CourseWork , a następnie otwórz interfejs Google Classroom i sprawdź, czy utworzono projekt z załącznikiem materiału z linkiem. Załącznik powinien zawierać tytuł połączonej strony internetowej i adres URL.

Testowanie tworzenia załącznika dodatku

Wróć na stronę indeksu i zaloguj się jako nauczyciel z licencją Google Workspace for Education Teaching & Learning lub Plus. Kliknij przycisk Utwórz projekt CourseWork , a następnie otwórz interfejs Google Classroom i sprawdź, czy utworzono projekt z załącznikiem dodatku. Załącznik powinien zawierać nazwę aplikacji dodatku i tytuł określony w kodzie.

Testowanie modyfikowania projektu

Wróć na stronę indeksu i upewnij się, że jesteś zalogowany(-a) jako nauczyciel z licencją Teaching &Learning lub Plus. Kliknij przycisk Modyfikuj projekt CourseWork , a następnie wróć do interfejsu Google Classroom i sprawdź, czy tytuł projektu został zmieniony.

Gratulacje! Ukończono serię samouczków.