Konfiguracja projektu Google Cloud

Na tej stronie znajdziesz informacje o tworzeniu i konfigurowaniu projektów Google Cloud na potrzeby dodatków do Google Classroom. Projekty Google Cloud są używane do implementowania logowania jednokrotnego Google za pomocą OAuth 2.0 (Google SSO), autoryzowania żądań wysyłanych przez dodatek oraz zarządzania jego wyświetlaniem 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 rozwoju, oraz publiczny, dostępny dla użytkowników końcowych. Etykiety „publiczna” i „prywatna” odnoszą się do widoczności aplikacji w Google Workspace Marketplace. Prywatną aplikację z Marketplace mogą zainstalować tylko użytkownicy w domenie, w której została utworzona, a publiczna aplikacja z Marketplace jest dostępna dla dowolnej domeny 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 trafią do Marketplace.

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ą, która jest dostępna dla administratorów, nauczycieli i uczniów. Zanim projekt publiczny zostanie uruchomiony lub zainstalowany, musi zostać sprawdzony i zatwierdzony przez zespół Google Workspace Marketplace.

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

    Tworzenie projektu Google Cloud

  2. Włącz interfejs Classroom API w projekcie Cloud.

    Włączanie interfejsu Classroom API

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

    Włączanie pakietu SDK Google Workspace Marketplace

  4. Ustaw Konfiguracja aplikacji w pakiecie SDK Marketplace dla opcji Widoczność aplikacji na Publiczna i zaznacz pole Niepubliczna.

  5. Wypełnij wymagane pola na stronie Informacje o aplikacji w pakiecie SDK Marketplace i kliknij PUBLISH (Opublikuj).

  6. Twój zespół Google Workspace Marketplace sprawdzi Twoją aplikację. Skontaktują się z Tobą, używając adresu e-mail dewelopera podanego w pakiecie SDK Marketplace. Gdy aplikacja zostanie zatwierdzona, odznacz pole Nie na liście, aby nauczyciele i administratorzy mogli znaleźć ją w Marketplace.

Tworzenie prywatnego projektu Google Cloud

Ten prywatny projekt reprezentuje aplikację dodatku używaną do tworzenia. Nie jest ona dostępna dla użytkowników spoza domeny, w której została utworzona, ale przed instalacją nie musi być zatwierdzona. Dlatego Google zaleca wykorzystanie tego projektu do opracowania i przetestowania dodatku w środowisku kontrolowanym.

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 zezwolić na dostęp do interfejsu API dodatków Classroom:

  1. Wykonaj czynności wymagane do uzyskania domeny testowej 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, w konsoli administracyjnej sprawdź te informacje:

    • 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 > Dodatkowe usługi 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. Po przesłaniu tego formularza prosisz Google o uaktualnienie domeny demonstracyjnej do Google Workspace for Education Plus z 10 licencjami oraz zezwolenie Twojemu projektowi Cloud na interfejs API dodatków do Classroom.

    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 testowe nauczycieli. W sekcji Licencje każdego nauczyciela sprawdź, czy Google Workspace for Education Plus jest przypisany.

  4. Włącz interfejs Classroom API w projekcie Cloud.

    Włączanie interfejsu Classroom API

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

    Włączanie pakietu SDK Google Workspace Marketplace

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

  7. Wypełnij wymagane pola na stronie Informacje o aplikacji w pakiecie SDK Marketplace i kliknij PUBLISH (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 podany na stronie informacji o aplikacji.

OAuth 2.0

Dostęp do interfejsu Classroom API wymaga zgody użytkownika na dostęp do danych. Uzyskiwane są one przez wysłanie żądania dostępu Google do zakresów OAuth w imieniu zalogowanego użytkownika i otrzymanie tokena, którego można użyć do wywołania interfejsu API w Google Classroom. Zakresy muszą być skonfigurowane w opisie na stronie Google Workspace Marketplace, aby administrator domeny mógł wyrazić zgodę w imieniu użytkowników domeny, jeśli zainstalują dodatek.

Zakresy uprawnień Classroom są wrażliwe, dlatego przed uruchomieniem dodatku musisz poprosić o weryfikację OAuth. W przeciwnym razie użytkownicy zobaczą komunikat ostrzegawczy, że aplikacja nie została zweryfikowana, a tylko niewielka liczba użytkowników będzie mogła uzyskać dostęp do Twojego produktu. Aby dowiedzieć się więcej o weryfikacji, zapoznaj się z omówieniem sekwencji weryfikacji.

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

Uprawnienia użytkownika

Aplikacja internetowa powinna żądać co najmniej 1 z tych zakresów:

  • https://www.googleapis.com/auth/userinfo.email, który umożliwia aplikacji sprawdzanie adresu e-mail użytkownika.
  • https://www.googleapis.com/auth/userinfo.profile, który umożliwia aplikacji dostęp do danych osobowych, takich jak portret, imiona i nazwiska, oraz inne dane osobowe udostępnione przez użytkownika publicznie.

Gdy użytkownik autoryzuje jeden z tych zakresów w Twoim dodatku, jest identyfikowany za pomocą parametru zapytania login_hint. Gdy otworzysz element iframe, ten parametr zostanie przekazany do wszystkich adresów URL Twojej aplikacji internetowej. Jeśli użytkownik nie autoryzował jednego z tych zakresów, login_hint nie zostanie wysłany.

login_hint to standardowe parametry OpenID Connect, które możesz opcjonalnie przekazywać Google podczas korzystania z Logowania przez Google lub żądania tokena OAuth. Ma ona usprawnić proces autoryzacji dla użytkownika.

Zakresy uprawnień 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óry umożliwia dostęp do uruchamiania operacji weryfikacji i odczytu załączników.

Nawet jeśli masz prawidłowy token dostępu OAuth, który wskazuje dane uwierzytelniające użytkownika, wywołania interfejsu API są ograniczone przez dodatkowe wymagania:

  • Wszystkie metody wymagają, aby użytkownik był nauczycielem lub uczniem na zajęciach określonych przez courseId w żądaniu.
  • Aby tworzyć, aktualizować, usuwać załączniki i przekazywać oceny, użytkownik musi być nauczycielem.
  • Połączenia z konkretnym postem w Google Classroom są objęte następującymi weryfikacjami.
    • Gdy dodatek ma już co najmniej jeden załącznik w poście, może wysyłać żądania dotyczące:
      • walidacja uruchamiania iframe.
      • operacje odczytu, aktualizacji i usuwania załączników;
      • Aktualizacje ocen w poście
    • Po pierwszym otwarciu elementu iframe wykrywania załączników dodatek może nie mieć jeszcze załącznika w poście. Dostępny jest parametr zapytania addOnToken, który umożliwia wysyłanie żądań dotyczących:
      • Utworzenie załącznika pod postem (wymagany jest addOnToken)
      • Weryfikacja uruchomienia (addOnToken jest weryfikowana, jeśli jest podana, i jest wymagana, gdy dodatek nie ma załączonego pliku w poście)

Weryfikacja OAuth

Wtyczka Classroom używa interfejsów API Google, aby uzyskać dostęp do danych użytkowników Google.

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

Informacje o aplikacji 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 informacji o aplikacji w Google Workspace Marketplace.

Informacje o kartach produktów

Listing w Marketplace SDK Store Twojego publicznego projektu Google Cloud zawiera nazwę aplikacji i opis przeznaczony dla użytkowników. Informacje te możesz podać w wielu językach w sekcji Szczegóły aplikacji.

W informacjach o produkcie przestrzegaj tych wytycznych:

  • W sekcji Szczegóły aplikacji:

    • Unikaj znaków interpunkcyjnych w nazwie aplikacji. Na przykład zamiast „Mój dodatek firmy My Company” wpisz „Mój dodatek firmy My Company”.

    • Krótki opis i Szczegółowy opis nie mogą zawierać dokładnie tego samego tekstu.

    + Upewnij się, że w polu Ceny wybrano wartość. To pole zawiera opcje Bezpłatna, Płatna z bezpłatnym okresem próbnym, Płatna z bezpłatnymi funkcjami i Płatna. Nie musisz określać kwoty kosztu w informacjach o produkcie w Marketplace.

    • Sprawdź, czy w polu Kategoria wybrano wartość. Dobrym rozwiązaniem mogą być Zasoby akademickie lub Narzędzia dla nauczycieli i administratorów.

    • Więcej informacji znajdziesz w opisie aplikacji na stronie Marketplace.

Integracja z usługami Google dotyczącymi licencjonowania i rozliczeń

Jeśli chcesz umożliwić integrację swoich aplikacji z Google Workspace Marketplace z usługami licencjonowania i rozliczeń Google, otwórz interfejs Marketplace API.

Ustawienia instalacji

Dodatki umożliwiają instalację pojedynczo, a nie tylko przez instalację przez administratora. Na tej stronie opisujemy pewne różnice między tymi dwoma typami instalacji. Nie służy ona do promowania żadnego z tych typów instalacji. Możesz zdecydować, czy zezwolić na indywidualną instalację, na stronie konfiguracji aplikacji pakietu 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 zdecyduje się na to, użytkownicy nie będą proszeni o wyrażenie zgody na żadne zakresy dostępu.

Poniżej przedstawiamy kilka kwestii związanych z instalacją administratora.

  • Większa kontrola Administratorzy mogą ograniczyć dostęp do dodatku.
  • Zgodność z licencjami. Jeśli Twoja aplikacja wymaga licencji, kierowanie instalacji przez administratora może pomóc w zapewnieniu, że licencje są rozpowszechniane i odpowiednio wykorzystywane przez odpowiednią instytucję.
  • Mniejsze obciążenie użytkowników. Instalacja przez administratora zmniejsza obciążenie konfiguracyjne dla nauczycieli i uczniów. Zwiększa to wygodę użytkowników i zmniejsza liczbę kliknięć, a jednocześnie eliminuje ryzyko pomyłek.

Więcej informacji o instalowaniu aplikacji przez administratora znajdziesz w artykule Instalowanie aplikacji z Marketplace w domenie, a więcej o jednostkach organizacyjnych i grupach dostępu – w artykule Jak działa struktura organizacyjna.

Instalacja indywidualna

Indywidualne instalacje dodają dodatek do konta użytkownika. Podczas instalacji użytkownik jest proszony o zgodę na zakresy dostępu dodatku.

Poniżej przedstawiamy kilka kwestii dotyczących poszczególnych instalacji.

  • Ułatwić wdrażanie. Więcej użytkowników może zobaczyć i zainstalować Twój dodatek z Google Workspace Marketplace. Zezwolenie na indywidualną instalację może zachęcić więcej nauczycieli do korzystania z Twojej usługi lub do jej promowania.
  • Testowanie przez administratora. Administrator może zainstalować dany dodatek indywidualnie, aby go przetestować lub ocenić, zanim zatwierdzi go lub zainstaluje dla szerszej 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ą indywidualną instalację. Jeśli dodatek nie znajduje się na liście dozwolonych, użytkownicy nadal mogą zobaczyć jego informacje na stronie Google Workspace Marketplace, ale nie mogą go zainstalować. Zamiast tego zobaczą komunikat informujący, że administrator domeny nie zezwolił na jego instalację. Aby dowiedzieć się więcej o tym, co się dzieje, przeczytaj artykuł Zarządzanie aplikacjami z Google Workspace Marketplace na liście dozwolonych.

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

Integracja aplikacji

W polu Identyfikator URI konfiguracji załącznika musisz podać adres URL elementu iframe uruchamiania. Ten adres URL jest używany jako wartość iframe src w przypadku elementu iframe Discovery z załącznikiem. Element iframe wykrywania załączników jest używany przez nauczycieli do wyszukiwania treści lub działań, które można dołączyć do projektu.

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

Więcej informacji o tych polach znajdziesz na stronie z informacjami o ramkach iframe.

Konta testowe

Utwórz konta testowe w domenie demonstracyjnej, aby zweryfikować prawidłowe działanie dodatku prywatnego. Aby przetestować przełączanie się między uczniami w interfejsie iframe Sprawdzania zadań uczniów, musisz użyć 2 kont uczniów.

Sugerowane konta testowe:

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

Aby utworzyć nowe konto testowe, wykonaj te czynności:

  1. Zaloguj się w konsoli administracyjnej.
  2. Kliknij Użytkownicy.
  3. Kliknij Dodaj nowego użytkownika (zobacz ilustrację 1).
  4. Wpisz dane użytkownika i przypisz odpowiednie role.

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

Aby utworzyć nową grupę testową, wykonaj te czynności:

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

Kliknij Utwórz grupę Rysunek 2. Lokalizacja linku Create a group (Utwórz grupę) w konsoli administracyjnej.