Załączniki zewnętrzne i oddanie

To siódmy z kolei przewodnik z serii o dodatkach do Classroom.

Z tego przewodnika dowiesz się, jak dodać do aplikacji internetowej zachowanie umożliwiające tworzenie dodatków spoza Google Classroom. Użyj tego sposobu, aby umożliwić użytkownikom tworzenie załączników dodatków z istniejącej usługi lub witryny. Jest to też świetne uzupełnienie integracji CourseWork, ponieważ kieruje ona obecny ruch do ulepszonej wersji aplikacji, która zapewnia większą wygodę użytkowników, bez konieczności zmiany ich działań. Sugerowany proces jest opisany na stronie przewodnika Tworzenie załączników poza Classroom.

Możesz też dodać do dodatku zachowanie, aby programowo modyfikować projekt za pomocą załączników dodatku. Możesz modyfikować dowolny projekt, który zawiera jeden z załączników Twojego dodatku, niezależnie od tego, kto go utworzył. Jest to szczególnie przydatne w przypadku oddawania projektów po ukończeniu zadań przez ucznia, dzięki czemu nauczyciel może sygnalizować nauczycielowi, że zadania zostały ukończone, a praca jest gotowa do sprawdzenia.

rozszerzysz ostateczną wersję dodatku, aby obsługiwał treści lub załączniki typu aktywność; W tym przewodniku używany jest załącznik typu „content”.

Ważne: zanim skorzystasz z tej instrukcji, zapoznaj się z poprzednimi instrukcjami z tej serii. Ten przewodnik rozszerza aplikację internetową opracowaną w poprzednich przewodnikach. Na stronie Przegląd możesz pobrać pełny kod źródłowy wszystkich samouczków. Kod tego konkretnego samouczka znajdziesz w katalogu /07-external-attachments/.

Dodaj zakres protokołu OAuth dotyczący zarządzania przypisaniami

Upewnij się, że Twoja aplikacja żąda 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 i służy do tworzenia lub modyfikowania przypisań CourseWork. Dodaj ten zakres do list zakresów w pakiecie SDK Google Workspace Marketplace w projekcie Cloud, ekranie zgody OAuth i kodzie serwera.

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

Ważne: na tym etapie nie modyfikuj żadnych treści w ramkach iframe. Zamiast tego dodaj zachowanie, które umożliwi tworzenie załączników dodatków na stronie internetowej poza Classroom.

Dodawanie przycisków do strony internetowej bez ramki iFrame

Proces opisany w tym przewodniku umożliwia użytkownikowi tworzenie zadań i załączników 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ć stronę internetową, która będzie udawać stronę zewnętrzną. Potrzebujesz przycisku lub linku, który po kliknięciu otwiera nową ścieżkę, która wykonuje sugerowanąCourseWork ścieżkę, aby utworzyć nowe zadanie.

Musisz też dodać przycisk lub link umożliwiający użytkownikowi zalogowanie się, jeśli jeszcze go nie masz. Aby wysyłać kolejne żądania interfejsu API, musisz mieć dane uwierzytelniające użytkownika, dlatego musi on ukończyć proces uwierzytelniania OAuth 2.0. Szczegółowe wskazówki znajdziesz w przewodniku po logowaniu.

Python

Podany przykład w języku Python modyfikuje trasę /index, która została przedstawiona 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 zawierać 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 Pythona, aby obsługiwać ścieżki związane z CourseWork. Jest to coursework_routes.py w podanym przykładzie. Dodaj te 3 trasy. Pamiętaj, że niektóre informacje 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")

Ważne: dodaj nowe trasy wywołań zwrotnych OAuth do identyfikatora klienta OAuth Autoryzowane identyfikatory URI przekierowania na stronie Dane logowania w projekcie Google Cloud. W przypadku naszego przykładu należy dodać https://<<your server>>/index i https://<<your server>>/coursework-assignment-callback.

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

Ważne: zanim spróbujesz utworzyć załączniki dodatków, zawsze sprawdź, czy użytkownik może je tworzyć. Kwalifikacje różnią się w zależności od użytkownika i projektu Google Cloud, który wysyła żądanie, i mogą się zmieniać w czasie.

Aby móc tworzyć załączniki dodatków w imieniu użytkownika, musisz spełnić kilka warunków wstępnych. Dla wygody użytkowników Google udostępnia metodę userProfiles.checkUserCapability, która pozwala określić, czy użytkownik spełnia te wymagania wstępne. Użytkownik, który spełnia wymagania wstępne, jest nazywany kwalifikującym się użytkownikiem.

Ważne: sprawdzanie uprawnień za pomocą interfejsu Classroom API jest dostępne w wersji przedpremierowej V1_20240930_PREVIEW lub nowszej. Aby korzystać z metod interfejsu API w wersji publicznej, musisz wziąć udział w programie Google Workspace Developer Preview i przeprowadzić dodatkową konfigurację poza typowym korzystaniem z interfejsu Classroom API.

Dodaj weryfikację kwalifikowalności do implementacji CourseWork. Następnie przetestuj pole allowed w odpowiedzi. W przypadku kwalifikujących się użytkowników postępuj zgodnie z logiką tworzenia projektu z załącznikiem dodatku. W przeciwnym razie utwórz materiał typu Link. Musisz znać identyfikator kursu, w którym użytkownik chce utworzyć zadanie. Zazwyczaj użytkownik musi podać, którego kursu ma użyć. W tym przykładzie dla uproszczenia używamy zakodowanej wartości.

Ważna informacja: zawsze twórz załączniki dodatków, jeśli użytkownik spełnia wymagania. Dodatki zapewniają lepsze wrażenia użytkowników i programistów w przypadku materiałów z linkami.

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łączonym dodatkiem dla kwalifikujących się użytkowników

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

1. Wyślij żądanie interfejsu API, aby utworzyć w Google Classroom projekt courseWork bez załączników.
2. Wyodrębnij id nowo utworzonego projektu.
3. Utwórz nową pracę domową AddOnAttachment.
4. Wyślij prośbę o utworzenie załącznika dodatku do nowo utworzonego projektu w Google Classroom.

Ważne: te 2 prośby musisz przesłać oddzielnie. Aby można było powiązać nowy załącznik dodatku z identyfikatorem projektu, musi zostać utworzone przypisanie CourseWork.

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

Utwórz materiał linku

Ważne: jeśli Twój produkt już tworzy zadania CourseWork, prawdopodobnie już stosuje omówioną tutaj procedurę.

Jeśli użytkownik nie spełnia wymagań dotyczących tworzenia załączników dodatków, utwórz zamiast tego materiał z linkiem:

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 istniejącego projektu

Ważne: główną zaletą załączników dodatków jest to, że umożliwiają one wysyłanie żądań interfejsu API do elementu strumienia nadrzędnego.

Możesz uzyskać dostęp do dowolnego elementu strumienia Google Classroom, który zawiera co najmniej 1 załącznik z Twojego dodatku, zmodyfikować go, przesłać, odzyskać lub zwrócić, niezależnie od tego, kto go utworzył. Elementy strumienia to Announcement, CourseWork, projekt lub CourseWorkMaterial.

Aby to zilustrować, dodasz trasę, która zmodyfikuje dany element strumienia. Użyj tej metody, aby sprawdzić, czy możesz uzyskać dostęp do elementów strumienia utworzonych przez Ciebie za pomocą interfejsu API i utworzonych przez nauczyciela w interfejsie Google Classroom.

Dodaj jeszcze jeden link lub przycisk do strony internetowej, którą po raz pierwszy edytowałeś/aś w ramach tej instrukcji. Powinna otworzyć się nowa trasa do modyfikowania przypisania CourseWork.

Python

Podany przykład kodu Pythona modyfikuje trasę /index, która została zmodyfikowana wcześniej w tym przewodniku.

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

Utwórz nową trasę do obsługi tras związanych z CourseWork. Znajdziesz go w pliku coursework_routes.py w naszym przykładzie.

# 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

Ważne: na tym etapie programowania możesz testować aplikację tylko w elementach iframe dodatków do Classroom. Opis każdego elementu iframe znajdziesz w naszym przewodniku [w języku angielskim] iframe and query parameters. Wszystkie instrukcje podane w tym przewodniku zakładają, że wtyczka jest dostępna w kontekście ramki iframe.

Dla uproszczenia w przykładach użyto zakodowanych identyfikatorów zajęć i zadań. Możesz je uzyskać, wysyłając żądania z uprawnieniami nauczyciela do metod get i list zasobów courses i courseWork. Są one również zwracane w odpowiedzi podczas tworzenia courseWork przypisów.

Tworzenie testu połączenia

Uruchom serwer, a następnie przejdź do strony indeksu i zaloguj się jako nauczyciel bez licencji Google Workspace for Education Teaching & Learning lub Plus. Możesz zmienić stan licencji użytkownika w konsoli administracyjnej domeny testowej.Kliknij przycisk Utwórz projekt CourseWork, a następnie otwórz interfejs Google Classroom i sprawdź, czy projekt z załącznikiem z linkiem do materiału został utworzony. Załącznik powinien zawierać tytuł linkowanej 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, otwórz interfejs Google Classroom i sprawdź, czy został utworzony projekt z załączonym dodatkiem. Załącznik powinien zawierać nazwę aplikacji dodatku i tytuł określony w kodzie.

Modyfikowanie przypisania testu

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

Gratulacje! To już wszystkie instrukcje.