Внешние вложения и усилитель; сдача

Это седьмое прохождение в серии прохождений надстроек Класса.

В этом пошаговом руководстве вы добавите поведение в веб-приложение для создания дополнительных вложений за пределами Google Classroom . Используйте это поведение, чтобы позволить пользователям создавать дополнительные вложения из вашего существующего продукта или веб-сайта. Это также отличное дополнение к интеграции CourseWork , поскольку вы направляете существующий трафик на улучшенный пользовательский интерфейс, предлагаемый вашим дополнением, не меняя его поток. Предлагаемый процесс представлен на странице руководства «Создание вложений за пределами Класса» .

Вы также добавляете поведение в надстройку, чтобы программно изменить задание с вложениями надстройки . Вы можете изменить любое задание, к которому прикреплено одно из ваших дополнительных вложений, независимо от того, кто создал задание. Это особенно полезно для сдачи заданий после того, как учащийся выполнил задание, сигнализируя учителю, что поставленные задачи выполнены и работа учащегося готова к проверке.

Вы расширяете окончательную версию своего дополнения, которая поддерживает вложения типа контента или типа действия . В этом руководстве используется вложение типа контента.

Важно! Прежде чем следовать этому пошаговому руководству, выполните предыдущие пошаговые руководства этой серии. Это пошаговое руководство расширяет веб-приложение, разработанное в предыдущих пошаговых руководствах. Полный исходный код для всех пошаговых руководств можно скачать на странице «Обзор». Код для этого конкретного пошагового руководства можно найти в каталоге /07-external-attachments/ .

Добавьте область OAuth для управления назначениями.

Убедитесь, что ваше приложение запрашивает следующие области:

• 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 ранее не требовалась и используется для создания или изменения заданий CourseWork . Добавьте эту область в списки областей в SDK Google Workspace Marketplace вашего облачного проекта, на экране согласия OAuth и в коде вашего сервера.

Питон

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

Создание задания в Классе

Важно! Не изменяйте какие-либо элементы интерфейса iframe на этом этапе пошагового руководства. Вместо этого добавьте поведение для создания дополнительных вложений с веб-страницы за пределами Класса.

Добавление кнопок на веб-страницу без iframe

Последовательность действий, описанная в этом пошаговом руководстве, позволяет пользователю создавать задания и вложения Google Classroom из продуктов, не принадлежащих Google. На практике это, скорее всего, ваш существующий веб-сайт или приложение. В этом примере вам нужно создать макет веб-страницы, которая будет выступать в качестве внешнего сайта. Вам нужна кнопка или ссылка, при нажатии которой открывается новый маршрут , выполняющий предложенный процесс CourseWork для создания нового задания.

Вам также потребуется добавить кнопку или ссылку, позволяющую пользователю войти в систему, если у вас ее еще нет. Для выполнения последующих запросов API вам потребуются учетные данные пользователя, поэтому они должны завершить рукопожатие OAuth 2.0. Подробные инструкции см. в пошаговом руководстве по входу.

Питон

Приведенный пример Python изменяет маршрут /index , который был введен на первом шаге пошагового руководства .

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

Добавьте HTML-шаблон для представления пункта назначения на вашем веб-сайте. На этой странице будет представлен контент, который будет прикреплен к вашему заданию 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>

Создайте новый файл модуля Python для обработки маршрутов, связанных с CourseWork. В нашем примере это coursework_routes.py . Добавьте следующие три маршрута; Обратите внимание, что часть содержимого вы заполните позже.

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

Важно! Добавьте все новые маршруты обратного вызова OAuth к своему идентификатору клиента OAuth; URI авторизованного перенаправления на странице учетных данных вашего проекта Google Cloud. В нашем примере вам следует добавить https://<<your server>>/index и https://<<your server>>/coursework-assignment-callback .

Проверка права пользователя на создание вложений

Ключевой момент: всегда проверяйте, имеет ли пользователь право создавать дополнительные вложения, прежде чем пытаться создать дополнительные вложения. Право на участие зависит от пользователя и запрашивающего проекта Google Cloud и может меняться со временем.

Существует несколько предварительных условий, которым должен соответствовать пользователь, прежде чем вы сможете создавать дополнительные вложения от его имени. Для удобства Google предоставляет метод userProfiles.checkUserCapability , позволяющий определить, соответствует ли пользователь этим предварительным требованиям. Пользователь, соответствующий предварительным требованиям, называется подходящим пользователем.

Важно! Проверка соответствия критериям с помощью Classroom API находится в общедоступной предварительной версии и доступна в предварительной версии V1_20240930_PREVIEW и более поздних версиях. Чтобы использовать методы API в общедоступной предварительной версии, вы должны быть участником программы Google Workspace Developer Preview Program и выполнить дополнительную настройку, выходящую за рамки обычного использования Classroom API.

Добавьте проверку приемлемости в реализацию маршрута создания CourseWork . Затем проверьте allowed поле в ответе. Для соответствующих критериям пользователей следуйте логике, чтобы создать задание с дополнительным прикрепленным файлом . В противном случае создайте Link Material . Вам потребуется знать идентификатор курса, в котором пользователь хочет создать задание. Обычно вы предлагаете пользователю указать, какой курс использовать. Для простоты в этом примере мы используем жестко запрограммированное значение.

Ключевой момент: всегда создавайте дополнительные вложения, если пользователь имеет на это право. Дополнения обеспечивают превосходное удобство использования Link Materials для пользователей и разработчиков.

Питон

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

Создайте задание с дополнительным прикрепленным файлом для подходящих пользователей.

Если пользователь имеет право создавать дополнительные вложения, выполните следующие действия:

1. Отправьте запрос API, чтобы создать задание courseWork в Google Classroom без вложений .
2. Извлеките id вновь созданного задания.
3. Создайте новый AddOnAttachment CourseWork .
4. Отправьте запрос на создание дополнительного вложения к только что созданному заданию в Google Classroom.

Ключевой момент: вы должны подать два запроса отдельно. Задание CourseWork должно быть успешно создано, чтобы новое вложение надстройки можно было связать с идентификатором задания.

Питон

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

Создайте материал для ссылки

Ключевой момент: если ваш продукт уже создает задания CourseWork , скорее всего, он уже соответствует представленному здесь алгоритму.

Если пользователь не имеет права создавать дополнительные вложения, вместо этого создайте Материал ссылки, выполнив следующие действия:

Питон

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

Изменение уже созданного задания

Ключевой момент: основным преимуществом дополнительных вложений является то, что они предоставляют вам возможность выполнять запросы API к элементу родительского потока.

Вы можете получить доступ, изменить, сдать, вернуть или вернуть любой элемент потока Google Classroom, к которому имеется хотя бы одно из ваших дополнительных вложений, независимо от того, кто создал этот элемент потока. Элементами потока являются любые Announcement , задания CourseWork или CourseWorkMaterial .

Чтобы продемонстрировать это, вы добавите маршрут для изменения данного элемента потока. Используйте этот метод, чтобы убедиться, что вы можете получать доступ и изменять элементы потока, созданные вами с помощью API и созданные учителем через пользовательский интерфейс Google Classroom.

Добавьте еще одну ссылку или кнопку на веб-страницу, которую вы впервые редактировали в этом пошаговом руководстве. Должен открыться новый маршрут для изменения задания CourseWork .

Питон

Приведенный пример Python изменяет маршрут /index , который был изменен ранее в этом пошаговом руководстве .

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

Создайте новый маршрут для обработки маршрутов, связанных с CourseWork. Это находится в файле 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()
)

Протестируйте дополнение

Важно! На данном этапе разработки вы можете тестировать свое приложение только в iframe надстроек Класса. Прочтите нашу страницу руководства по iframe и параметрам запроса, чтобы получить описание каждого iframe. Все инструкции, представленные в этом пошаговом руководстве, предполагают, что надстройку можно использовать в контексте iframe.

Для простоты в приведенных примерах используются жестко закодированные идентификаторы курсов и заданий. Вы можете получить эти идентификаторы, отправив запросы с учетными данными преподавателя к методам get и list courses и ресурсов courseWork . Они также возвращаются в ответе при создании заданий courseWork .

Создание материала тестовой ссылки

Запустите свой сервер, затем перейдите на свою индексную страницу и войдите в систему как преподаватель без лицензии Google Workspace for Education Teaching & Learning или Plus . Вы можете переключить статус лицензии пользователя в консоли администратора вашего тестового домена. Нажмите кнопку «Создать задание курсовой работы» , затем откройте пользовательский интерфейс Google Classroom и убедитесь, что задание с прикрепленным к нему материалом ссылки было создано. Во вложении должно быть указано название связанной веб-страницы и URL-адрес.

Тестирование создания дополнительных вложений

Вернитесь на главную страницу и войдите в систему как преподаватель с лицензией Google Workspace for Education Teaching & Learning или Plus . Нажмите кнопку «Создать задание курсовой работы» , затем откройте пользовательский интерфейс Google Classroom и убедитесь, что задание с дополнительным вложением было создано. Во вложении должно быть указано имя вашего дополнительного приложения и заголовок, указанный в вашем коде.

Модификация тестового задания

Вернитесь на главную страницу и убедитесь, что вы вошли в систему как преподаватель с лицензией Teaching & Learning или Plus. Нажмите кнопку «Изменить задание курсовой работы» , затем вернитесь в пользовательский интерфейс Google Classroom и убедитесь, что название задания было изменено.

Поздравляем! Вы завершили серию прохождений.