Konfiguracja projektu Google Cloud

Na tej stronie znajdziesz informacje o tworzeniu i konfigurowaniu projektów Google Cloud na potrzeby dodatków do Classroom. Projekty Google Cloud służą do wdrażania logowania jednokrotnego Google za pomocą OAuth 2.0 (logowanie jednokrotne Google), autoryzowania żądań wysyłanych przez dodatek oraz zarządzania informacjami o dodatku w sklepie Google Workspace Marketplace.

Ogólne informacje o publikowaniu dodatku w Marketplace znajdziesz w artykule Publikowanie aplikacji.

Tworzenie projektu Google Cloud

Możesz utworzyć 2 rodzaje projektów: prywatny, który służy do tworzenia aplikacji, oraz publiczny, który jest dostępny dla użytkowników. Etykiety „publiczna” i „prywatna” odnoszą się do widoczności aplikacji w Google Workspace Marketplace. Prywatną aplikację w Marketplace mogą instalować tylko użytkownicy w domenie, w której została utworzona, a publiczna aplikacja w Marketplace jest dostępna w każdej domenie Google Workspace. Muszą to być 2 osobne aplikacje, ponieważ projekt nie może być jednocześnie publiczny i prywatny. Aplikacje publiczne muszą zostać sprawdzone i zatwierdzone, zanim staną się dostępne na platformie.

Ogólne informacje o tworzeniu projektów Google Cloud znajdziesz w artykule Tworzenie projektu Google Cloud.

Tworzenie publicznego projektu Google Cloud

Ten projekt reprezentuje aplikację dodatkową, do której mają dostęp administratorzy, nauczyciele i uczniowie. Projekt publiczny musi zostać sprawdzony i zatwierdzony przez zespół Google Workspace Marketplace, zanim będzie można go uruchomić lub zainstalować.

  1. Utwórz nowy projekt Google Cloud w domenie produkcyjnej.

    Tworzenie projektu Google Cloud

  2. włączyć interfejs Classroom API w projekcie Cloud;

    Włączanie interfejsu Classroom API

  3. Włącz pakiet Google Workspace Marketplace SDK w projekcie Cloud.

    Włączanie pakietu SDK Google Workspace Marketplace

  4. W pakiecie SDK Marketplace ustaw Konfiguracja aplikacji Widoczność aplikacji na Publiczna i zaznacz pole Niepubliczna.

  5. Wypełnij wymagane pola na stronie pakietu SDK Marketplace Informacje o aplikacji i kliknij OPUBLIKUJ.

  6. Aplikacja zostanie sprawdzona przez zespół Google Workspace Marketplace. Będą się z Tobą kontaktować za pomocą adresu e-mail dewelopera podanego w pakiecie SDK Marketplace. Gdy aplikacja zostanie zatwierdzona, odznacz pole Niepubliczna, aby nauczyciele i administratorzy mogli ją znaleźć w Marketplace.

Tworzenie prywatnego projektu Google Cloud

Ten prywatny projekt reprezentuje aplikację dodatku używaną do programowania. Nie jest dostępna dla użytkowników spoza domeny, w której została utworzona, ale nie wymaga zatwierdzenia przed instalacją. Dlatego zalecamy używanie tego projektu do tworzenia i testowania dodatku w kontrolowanym środowisku.

Aby utworzyć projekt prywatny, musisz mieć dostęp do domeny Google Workspace for Education z licencją Teaching & Learning lub Plus. Jeśli nie masz jeszcze dostępu do takiej domeny, wykonaj te czynności, aby skonfigurować domenę demonstracyjną Google Workspace for Education, przejść na licencję Plus i umożliwić jej dostęp do interfejsu Classroom Add-ons API:

  1. Wykonaj czynności, aby uzyskać domenę testową dla deweloperów.

  2. Zaloguj się jako administrator w domenie demonstracyjnej i utwórz nowy projekt Google Cloud.

    Tworzenie projektu Google Cloud

    Jeśli nie możesz uzyskać dostępu do konsoli Google Cloud ani tworzyć projektów Cloud, sprawdź w konsoli administracyjnej:

    • Otwórz stronę Ustawienia konta > Ustawienia dostępu na podstawie wieku i wybierz opcję Wszyscy użytkownicy w tej grupie lub jednostce organizacyjnej mają co najmniej 18 lat.
    • W sekcji Aplikacje > Usługi dodatkowe Google:
    • Google Cloud Platform jest włączona dla wszystkich.
    • Ustawienia tworzenia projektów to Zezwalaj użytkownikom na tworzenie projektów.
    • Ustawienia dostępu do Cloud Shell to Zezwalaj na dostęp do Cloud Shell.

  3. Wypełnij i prześlij formularz prośby o przejście na wyższą wersję domeny demonstracyjnej. Przesłanie tego formularza oznacza prośbę o przejście na Google Workspace for Education Plus z 10 licencjami w domenie demonstracyjnej oraz o umożliwienie korzystania z interfejsu Classroom Add-ons API w projekcie Cloud.

    Po zakończeniu procesu uaktualniania i dodawania do listy dozwolonych otrzymasz e-maila. Przypisz licencje Plus do kont nauczycieli testowych w konsoli administracyjnej. W sekcji Katalog > Użytkownicy utwórz lub wybierz konta nauczycieli testowych. W sekcji Licencje każdego nauczyciela sprawdź, czy Google Workspace for Education Plus jest przypisana.

  4. włączyć interfejs Classroom API w projekcie Cloud;

    Włączanie interfejsu Classroom API

  5. Włącz pakiet Google Workspace Marketplace SDK w projekcie Cloud.

    Włączanie pakietu SDK Google Workspace Marketplace

  6. Ustaw opcję pakietu SDK Marketplace Konfiguracja aplikacji Widoczność aplikacji na prywatna.

  7. Wypełnij wymagane pola na stronie pakietu SDK Marketplace Informacje o aplikacji i kliknij OPUBLIKUJ. Po opublikowaniu informacji o aplikacji użytkownicy w domenie mogą znaleźć i zainstalować aplikację w Google Workspace Marketplace lub odwiedzając adres URL aplikacji widoczny na stronie informacji o aplikacji.

OAuth 2.0

Dostęp do interfejsu Classroom API wymaga zgody użytkownika na dostęp do danych. Są one uzyskiwane przez wysłanie do Google prośby o dostęp do zakresów OAuth dla zalogowanego użytkownika i otrzymanie tokena, którego można później użyć do wywoływania interfejsu API Google Classroom. Zakresy muszą być skonfigurowane w informacjach o aplikacji w Google Workspace Marketplace, aby administrator domeny mógł wyrazić zgodę w imieniu użytkowników domeny, jeśli zainstalują oni dodatek.

Zakresy Classroom są wrażliwe, więc przed uruchomieniem dodatku musisz poprosić o weryfikację OAuth. W przeciwnym razie użytkownicy zobaczą ostrzeżenie, że aplikacja nie jest zweryfikowana, a tylko niewielka liczba użytkowników będzie mogła uzyskać dostęp do Twojej usługi. Więcej informacji o weryfikacji znajdziesz w omówieniu sekwencji weryfikacji.

Szczegółową listę wszystkich dostępnych zakresów i ich zastosowań znajdziesz na stronie Zakresy OAuth interfejsów API Google. Ogólne informacje o konfiguracji OAuth znajdziesz na stronie Konfigurowanie OAuth w dokumentacji Workspace.

Uprawnienia użytkownika

Aplikacja internetowa powinna prosić o co najmniej jeden z tych zakresów:

  • https://www.googleapis.com/auth/userinfo.email, która umożliwia aplikacji wyświetlanie adresu e-mail użytkownika.
  • https://www.googleapis.com/auth/userinfo.profile, która umożliwia aplikacji wyświetlanie danych osobowych, takich jak zdjęcie profilowe, imię i nazwisko oraz inne informacje, które użytkownik udostępnił publicznie.

Gdy użytkownik autoryzuje jeden z tych zakresów w dodatku, jest identyfikowany za pomocą parametru zapytania login_hint. Ten parametr jest przekazywany do wszystkich adresów URL aplikacji internetowej po otwarciu elementu iframe. Jeśli użytkownik nie autoryzował jednego z tych zakresów, parametr login_hint nie zostanie wysłany.

login_hint to standardowe parametry OpenID Connect, które możesz opcjonalnie przekazywać do Google podczas korzystania z logowania przez Google lub wysyłania prośby o token OAuth. Ma to na celu ułatwienie użytkownikom procesu autoryzacji.

Zakresy dodatków do Classroom

Te zakresy są specyficzne dla dodatków do Classroom:

  • https://www.googleapis.com/auth/classroom.addons.teacher, który umożliwia dostęp do wszystkich metod API.
  • https://www.googleapis.com/auth/classroom.addons.student, która umożliwia dostęp do operacji weryfikacji uruchamiania i odczytu załączników.

Nawet w przypadku prawidłowego tokena dostępu OAuth, który zawiera dane logowania użytkownika, wywołania interfejsu API podlegają dodatkowym wymaganiom:

  • Wszystkie metody wymagają, aby użytkownik był nauczycielem lub uczniem na zajęciach określonych przez courseId w żądaniu.
  • Tworzenie, aktualizowanie i usuwanie załączników oraz przesyłanie ocen wymaga, aby użytkownik był nauczycielem.
  • Wywołania konkretnego posta w Google Classroom są ograniczone przez te sprawdzenia:
    • Jeśli dodatek ma już co najmniej 1 załącznik w poście, może wysyłać żądania:
      • Weryfikacja uruchomienia elementu iframe
      • Operacje odczytywania, aktualizowania i usuwania załączników
      • aktualizacje ocen w tym poście,
    • Gdy ramka iframe wykrywania załączników zostanie otwarta po raz pierwszy, dodatek może nie mieć jeszcze załącznika w poście. Dostępny jest parametr zapytania addOnToken, którego można używać do przesyłania żądań dotyczących tych elementów:
      • Tworzenie załącznika pod postem (addOnToken jest wymagane)
      • Weryfikacja uruchomienia (addOnToken jest weryfikowana, jeśli jest podana, i jest wymagana, gdy dodatek nie ma istniejącego załącznika w poście)

Weryfikacja OAuth

Dodatek do Classroom korzysta z interfejsów API Google, aby uzyskiwać dostęp do danych użytkowników Google.

Więcej informacji o procesie weryfikacji znajdziesz w najczęstszych pytaniach dotyczących weryfikacji interfejsu OAuth API.

Informacje w Google Workspace Marketplace

Ogólne informacje o konfiguracji pakietu SDK Google Workspace Marketplace znajdziesz w artykułach Włączanie i konfigurowanie pakietu SDK Google Workspace Marketplace oraz Tworzenie strony aplikacji w Google Workspace Marketplace.

Informacje o ofercie

W informacjach o aplikacji w Marketplace SDK Store w Twoim publicznym projekcie Google Cloud podana jest nazwa aplikacji i opisy przeznaczone dla użytkowników. Te informacje możesz podać w kilku językach w sekcji Szczegóły aplikacji.

stosując się do tych wskazówek:

  • W sekcji Szczegóły aplikacji:
    • Unikaj znaków interpunkcyjnych w nazwie aplikacji. Na przykład użyj nazwy „Mój dodatek od Mojej Firmy” zamiast „Moja Firma: Mój dodatek” lub „Mój dodatek od Mojej Firmy”.
    • Krótki opis i Szczegółowy opis nie powinny zawierać dokładnie tego samego tekstu.
    • Sprawdź, czy w polu Ceny wybrano wartość. To pole zawiera opcje cenowe Bezpłatna, Płatna z bezpłatnym okresem próbnym, Płatna z bezpłatnymi funkcjami i Płatna. Nie musisz podawać kwoty kosztu w informacjach o zasobach na platformie Marketplace.
    • Sprawdź, czy w polu Kategoria wybrano wartość. Zasoby edukacyjne lub Narzędzia dla nauczycieli i administratorów mogą być dobrym wyborem w przypadku dodatku do Classroom.
    • Więcej informacji znajdziesz w opisie szczegółów aplikacji na platformie Marketplace.

Integracja z usługami licencjonowania i rozliczeń Google

Jeśli chcesz, aby Twoje aplikacje z Google Workspace Marketplace były zintegrowane z usługami licencjonowania i rozliczeń Google, odwiedź stronę Marketplace API.

Ustawienia instalacji

Dodatki mogą umożliwiać instalację indywidualną oprócz instalacji administracyjnej. Na tej stronie opisujemy niektóre różnice między tymi 2 rodzajami instalacji. Nie ma ona na celu promowania żadnego z nich. Możesz określić, czy zezwalać na instalację indywidualną, na stronie konfiguracji aplikacji w pakiecie SDK Google Workspace Marketplace.

Instalacja przez administratora

Instalacje administracyjne umożliwiają administratorowi dodanie dodatku do wszystkich kont w domenie lub do określonych grup dostępu lub jednostek organizacyjnych. Tylko administrator domeny może przeprowadzić instalację administracyjną. Administrator może opcjonalnie wyrazić zgodę na wszystkie zakresy dostępu w imieniu wszystkich użytkowników w domenie. Jeśli administrator zdecyduje się to zrobić, użytkownicy nie będą proszeni o wyrażenie zgody na żadne zakresy dostępu.

Poniżej przedstawiamy kilka kwestii dotyczących instalacji przez administratora.

  • Większa kontrola. Administratorzy mogą ograniczyć dostęp do dodatku dla wybranych użytkowników.
  • Zgodność z licencjonowaniem Jeśli aplikacja wymaga licencji, przekierowywanie instalacji przez administratora może pomóc w zapewnieniu, że licencje są rozpowszechniane i używane w odpowiedni sposób w danej instytucji.
  • Mniejsze obciążenie użytkowników. Instalacja przez administratora zmniejsza obciążenie związane z konfiguracją dla nauczycieli i uczniów. Może to zapewnić użytkownikom większą wygodę, ponieważ będą musieli wykonać mniej kliknięć i nie będą mieli powodów do dezorientacji.

Więcej informacji o tym, jak przeprowadzać instalacje przez administratora, znajdziesz w artykule Instalowanie aplikacji z Marketplace w domenie. Aby dowiedzieć się więcej o jednostkach organizacyjnych i grupach dostępu, przeczytaj artykuł Jak działa struktura organizacyjna.

Instalacja indywidualna

Instalacje indywidualne dodają dodatek do konta użytkownika. Podczas instalacji użytkownik jest proszony o wyrażenie zgody na zakresy dostępu dodatku.

Poniżej znajdziesz kilka kwestii dotyczących instalacji indywidualnej.

  • Ułatwianie wdrażania. Więcej użytkowników może zobaczyć i zainstalować Twój dodatek z Google Workspace Marketplace. Umożliwienie indywidualnej instalacji może zachęcić większą liczbę nauczycieli do korzystania z Twojej usługi lub promowania jej.
  • Testowanie przez administratora. Administrator może zainstalować dodatek indywidualnie, aby go przetestować lub ocenić przed zatwierdzeniem lub zainstalowaniem go dla większej grupy.

Oprócz instalowania dodatków w imieniu użytkowników administratorzy mogą też prowadzić listę dozwolonych, aby zezwalać użytkownikom na instalowanie dodatków, które umożliwiają instalację indywidualną. Jeśli dodatku nie ma na liście dozwolonych, użytkownicy nadal mogą zobaczyć jego stronę w Google Workspace Marketplace, ale nie mogą go zainstalować. Zamiast tego zobaczą komunikat z informacją, że administrator domeny nie zezwolił na instalację dodatku. Więcej informacji o tym działaniu znajdziesz w artykule Zarządzanie aplikacjami z Google Workspace Marketplace na liście dozwolonych.

Więcej informacji znajdziesz w dokumentacji ustawień instalacji Google Workspace Marketplace.

Integracja aplikacji

W polu Identyfikator URI konfiguracji załączników musisz podać adres URL elementu iframe uruchamiania. Ten adres URL jest używany jako wartość src elementu iframe w ramce iframe załącznika Discovery. Element iframe do wyszukiwania załączników jest używany przez nauczycieli do znajdowania treści lub zadań, które można dołączyć do projektu. Można go ustawić w konsoli projektu Google Cloud.

Konfiguracja identyfikatora URI elementu iframe

Dozwolone prefiksy identyfikatorów URI załączników służą do weryfikowania identyfikatorów URI ustawionych w elemencie AddOnAttachment za pomocą metod *.addOnAttachments.create i *.addOnAttachments.patch. Weryfikacja polega na dopasowaniu dosłownym do prefiksu ciągu znaków i nie dopuszcza użycia symboli wieloznacznych.

Musisz też określić wszystkie prefiksy identyfikatorów URI, z których załączniki są dozwolone w Twoim dodatku. Ta funkcja zwiększa bezpieczeństwo, ponieważ uniemożliwia pobieranie załączników z nieautoryzowanych źródeł.

Ustaw obie te wartości na stronie Konfiguracja aplikacji pakietu SDK Marketplace w projekcie Google Cloud.

Konta testowe

Utwórz konta testowe w domenie demonstracyjnej, aby sprawdzić, czy prywatny dodatek działa prawidłowo. Do przetestowania przełączania się między uczniami w elemencie iframe Sprawdzanie prac uczniów potrzebne są 2 konta uczniów.

Sugerowane konta testowe:

  • Tammy Teacher, tammy.teacher@<your demo domain>
  • Sam Student, sam.student@<twoja domena demonstracyjna>
  • Sally Student, sally.student@<twoja domena demonstracyjna>

Aby utworzyć nowe konto testowe:

  1. Zaloguj się w konsoli administracyjnej.
  2. Kliknij Użytkownicy.
  3. Kliknij Dodaj nowe konto użytkownika (patrz rysunek 1).
  4. Wpisz dane użytkownika i przypisz mu odpowiednie role.

Kliknij Dodaj nowego użytkownika. Rysunek 1. Lokalizacja linku Dodaj nowego użytkownika w konsoli administracyjnej.

Aby utworzyć nową grupę testową:

  1. Zaloguj się w konsoli administracyjnej.
  2. Otwórz Grupy.
  3. Kliknij Utwórz grupę (patrz rysunek 2).
  4. Wpisz członków i właścicieli grupy.

Kliknij Utwórz grupę. Rysunek 2. Lokalizacja linku Utwórz grupę w konsoli administracyjnej.