Anhänge außerhalb von Google Classroom erstellen

In diesem Leitfaden erfahren Sie, wie Sie Add-on-Anhänge auf Ihrer Website oder in Ihrer App erstellen. Die Interaktionen ähneln dem Erstellen von Aufgaben mit den Endpunkten der CourseWork API. Implementieren Sie diesen Ablauf, damit Nutzer Add-on-Anhänge über Ihre Website oder Anwendung erstellen können.

Wichtig :Wir empfehlen Ihnen dringend, diesen Ablauf zum Erstellen von Anhängen zu implementieren, wenn Sie bereits CourseWork-Aufgaben erstellen. Wenn Sie eine CourseWork-Implementierung erweitern, können Sie viele weitere Nutzer auf Ihr Add-on umstellen. Das erfordert nur wenig zusätzliche Arbeit.

Workflow

Im Groben sieht der Ablauf zum Erstellen von Anhängen so aus:

1. Ein Lehrkraftnutzer öffnet Ihre Website oder App. Er wählt einen Inhalt aus, den er seinen Schülern oder Studenten zuweisen möchte.
2. Prüfen Sie, ob der Nutzer Add-on-Anhänge erstellen kann.
3. Wenn der Nutzer keine Add-on-Anhänge erstellen kann, erstellen Sie eine CourseWork-Aufgabe mit der URL zu den ausgewählten Inhalten als Linkmaterial.
4. Wenn der Nutzer Add-on-Anhänge erstellen kann, gehen Sie so vor:
   1. Erstellen Sie eine Aufgabe.
   2. Erstellen Sie einen Add-on-Anhang, der mit den ausgewählten Inhalten verknüpft ist, und verknüpfen Sie ihn mit der neuen Aufgabe.
5. Informieren Sie die Lehrkraft darüber, dass die Aufgabe erfolgreich erstellt wurde.

Die einzelnen Aktionen werden in den folgenden Abschnitten beschrieben.

Prüfen, ob ein Nutzer Add-on-Anhänge erstellen kann

Sie können Add-on-Anhänge im Namen eines berechtigten Nutzers erstellen. Ein berechtigter Nutzer ist eine Lehrkraft im Kurs, in dem Sie CourseWork-Aufgaben erstellen möchten, und der die Lizenz für die Google Workspace for Education-Version „Teaching and Learning“ oder „Education Plus“ zugewiesen hat.

Wichtig: Ob Nutzer Add-on-Anhänge erstellen können, kann sich von Nutzer zu Nutzer unterscheiden und sich im Laufe der Zeit ändern. Prüfen Sie immer die Berechtigung des Nutzers, bevor Sie Add-on-Anhänge erstellen.

Wichtig :Die Berechtigungsprüfung mit der Classroom API befindet sich in der öffentlichen Vorabversion und ist in der Vorabversion V1_20240930_PREVIEW und höher verfügbar. Wenn Sie API-Methoden in der öffentlichen Vorschau verwenden möchten, müssen Sie am Google Workspace-Vorschauprogramm für Entwickler teilnehmen und zusätzliche Einrichtungsschritte vornehmen, die über die typische Nutzung der Classroom API hinausgehen.

Prüfen Sie zuerst, ob der Nutzer Add-on-Anhänge erstellen kann. Dazu senden Sie eine Anfrage an den Endpunkt userProfiles.checkUserCapability mit dem Parameter CREATE_ADD_ON_ATTACHMENT. Prüfe das boolesche Feld allowed in der Antwort. Ein Wert von true gibt an, dass der Nutzer Add-on-Anhänge erstellen kann.

Warnung :Anfragen zum Erstellen von Add-on-Anhängen für Nutzer mit der Funktion CREATE_ADD_ON_ATTACHMENT sind nicht garantiert erfolgreich. Ein Nutzer mit der Funktion erhält beispielsweise einen 403-Antwortfehler, wenn Sie in seinem Namen Add-on-Anhänge in einem Kurs erstellen, in dem er kein Lehrkraft ist.

Python

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')
)
print(f'User eligibility for course {course_id}'
      f': {is_create_attachment_eligible}.')

Nutzer je nach Berechtigung weiterleiten

Anhand der Berechtigung wird festgelegt, ob Sie Add-on-Anhänge für einen Nutzer erstellen können.

Wichtig :Add-ons bieten erhebliche Vorteile für die Nutzerfreundlichkeit. Erstellen Sie immer Add-on-Anhänge für berechtigte Nutzer.

Nicht berechtigter Nutzer

Wenn der Nutzer keine Add-on-Anhänge erstellen kann, erstellen Sie eine neue CourseWork-Aufgabe mit der vom Nutzer ausgewählten Inhalts-URL als Link.

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.
    'maxPoints': 100,
    'materials': [
      {'link': {'url': my_content_url}}
    ]
  }

  assignment = (
    service.courses()
    .courseWork()
    .create(courseId=course_id, body=coursework)
    .execute()
  )

  print(
    f'Link Material assignment created with ID: {assignment.get("id")}'
  )

Die Antwort enthält eine Aufgabe im angeforderten Kurs mit den angehängten Inhalten. Nutzer können auf Link klicken, um die Inhalte Ihrer Website in einem neuen Tab zu öffnen.

Abbildung 1. Ansicht für Lehrkräfte eines Kursaufgaben-Entwurfs mit Linkmaterial

Berechtigte Nutzer

Gehen Sie so vor, wenn der Nutzer Add-on-Anhänge erstellen kann.

1. Erstellen Sie eine neue CourseWork-Aufgabe ohne Anhänge.
2. Erstellen Sie einen Add-on-Anhang.
   • Legen Sie den itemId der AddOnAttachment auf den id der neu erstellten Aufgabe fest.
   • Geben Sie URLs zu den vom Nutzer ausgewählten Inhalten für jede von Ihnen unterstützte Ansicht an.

Python

if is_create_attachment_eligible:
  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.
    'maxPoints': 100,
  }

  assignment = (
    classroom_service.courses()
    .courseWork()
    .create(courseId=course_id, body=coursework)
    .execute()
  )

  print(
    f'Empty assignment created with ID: {assignment.get("id")}'
  )

  attachment = {
    'teacherViewUri': {'uri': teacher_view_url},
    'studentViewUri': {'uri': student_view_url},
    'studentWorkReviewUri': {'uri': grade_student_work_url},
    'title': f'Test Attachment {test_label}',
  }

  add_on_attachment = (
    service.courses()
    .courseWork()
    .addOnAttachments()
    .create(
      courseId=course_id,
      itemId=assignment.get("id"),  # ID of the new assignment.
      body=attachment,
    )
    .execute()
  )

  print(
    f'Add-on attachment created with ID: {add_on_attachment.get("id")}'
  )

Hinweis: Ein Add-on-Token ist nicht erforderlich, wenn Sie einen Anhang zu einer von Ihnen erstellten Aufgabe hinzufügen.

Das Add-on wird in Classroom als Anhängekarte angezeigt. Die in der Anfrage angegebenen URLs werden im entsprechenden Iframe für jede Ansicht geöffnet.