Anhänge außerhalb von Google Classroom erstellen

In dieser Anleitung wird beschrieben, wie Sie Add-on-Anhänge auf Ihrer Website oder in Ihrer Anwendung erstellen. Die Interaktionen ähneln dem Erstellen von Aufgaben mithilfe der CourseWork API Endpunkte. Implementieren Sie diesen Ablauf, damit Nutzer Add-on-Anhänge von Ihrer Website oder aus Ihrer Anwendung erstellen können.

Wichtig: Wir empfehlen 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 viel mehr Nutzer für Ihr Add-on gewinnen und das mit wenig zusätzlichem Aufwand.

Workflow

Auf übergeordneter Ebene folgt der Ablauf zum Erstellen von Anhängen dieser Reihenfolge:

1. Eine Lehrkraft öffnet Ihre Website oder App und wählt einen Inhalt aus, den sie ihren Schülern 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 zum ausgewählten Inhalt als Link-Material.
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 auf den ausgewählten Inhalt verweist, und verknüpfen Sie ihn mit der neuen Aufgabe.
5. Informieren Sie die Lehrkraft, dass die Aufgabe erfolgreich erstellt wurde.

Jede Aktion wird 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 Kursaufgaben erstellen möchten, und hat die Lizenz für die Google Workspace for Education-Version Teaching &Learning oder Education Plus.

Wichtig:Die Berechtigung zum Erstellen von Add-on-Anhängen kann sich für jeden Nutzer unterscheiden und sich im Laufe der Zeit ändern. Prüfen Sie immer, ob der Nutzer berechtigt ist, bevor Sie versuchen, Add-on-Anhänge zu erstellen.

Wichtig: Berechtigungsprüfungen mit der Classroom API befinden sich in der öffentlichen Vorschau und sind in der Vorschauversion V1_20240930_PREVIEW und höher verfügbar. Wenn Sie API-Methoden in der öffentlichen Vorschau verwenden möchten, müssen Sie am Entwicklervorschauprogramm für Google Workspace 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 userProfiles.checkUserCapability Endpunkt mit dem CREATE_ADD_ON_ATTACHMENT Capability-Parameter. Prüfen Sie das boolesche Feld allowed in der Antwort. Ein Wert von true bedeutet, dass der Nutzer berechtigt ist, Add-on-Anhänge zu erstellen.

Warnung: Anfragen zum Erstellen von Add-on-Anhängen für Nutzer mit der CREATE_ADD_ON_ATTACHMENT Capability sind nicht garantiert erfolgreich. Ein Nutzer mit der Capability erhält beispielsweise einen 403-Antwortfehler, wenn Sie versuchen, in seinem Namen Add-on-Anhänge in einem Kurs zu erstellen, in dem er kein Lehrer 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('User eligibility for add-on attachment creation: '
      f'{is_create_attachment_eligible}.')

Nutzer basierend auf ihrer Berechtigung weiterleiten

Die Berechtigung bestimmt, 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 Content-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 dem angehängten Inhalt. Nutzer können auf den Link klicken, um den Inhalt auf Ihrer Website in einem neuen Tab zu öffnen.

Abbildung 1 : Lehreransicht einer Entwurfs-CourseWork-Aufgabe mit Link-Material.

Berechtigter 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 fürAddOnAttachment's itemId die id der neu erstellten Aufgabe fest.
   • Geben Sie für jede Ansicht , die Sie unterstützen, URLs zu den vom Nutzer ausgewählten Inhalten 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 für eine von Ihnen erstellte Aufgabe erstellen.

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