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 implementacji logowania jednokrotnego Google za pomocą OAuth 2.0 (Google SSO), do autoryzowania żądań wysyłanych przez dodatek oraz do zarządzania jego wyświetlaniem w sklepie Google Workspace Marketplace.

Więcej ogólnych informacji o publikowaniu dodatku w Marketplace znajdziesz w artykule Publikowanie aplikacji.

Tworzenie projektu Google Cloud

Ważna informacja: w pakiecie SDK Google Workspace Marketplace musisz ustawić publiczną widoczność aplikacji dodatku w wersji produkcyjnej. Projekt prywatny może być przydatny do tworzenia i testowania dodatku, ale wymagany jest tylko projekt publiczny.

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 z domeny, w której została ona utworzona, natomiast publiczna aplikacja z Marketplace jest dostępna dla wszystkich użytkowników domen 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 będą dostępne w Marketplace.

Ważne: nie możesz przekonwertować projektu prywatnego na publiczny.

Informacje ogólne o tworzeniu projektu 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 publiczny projekt 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

   Ważne: sprawdź, czy projekt należy do Twojej domeny produkcyjnej i czy jesteś zalogowany w konsoli Google Cloud jako użytkownik tej domeny.
   Ostrzeżenie: do testowania musisz używać wersji Draft projektu. Więcej informacji znajdziesz w artykule Aktualizowanie informacji o aplikacji za pomocą wersji roboczych
   .

2. włączyć 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. W pakiecie SDK Marketplace ustaw Konfigurację aplikacji Widoczność aplikacji na Publiczna i zaznacz pole Niepubliczna.

   Ważna informacja: nie możesz udostępniać ani konwertować projektu prywatnego używanego podczas wewnętrznego opracowywania i testowania.
   Ważna informacja: nie można znaleźć nieupublicznionych aplikacji w Google Workspace Marketplace, przeglądając lub wyszukując. W konfiguracji pakietu SDK Marketplace znajdziesz bezpośredni adres URL, który możesz użyć do zainstalowania dodatku. Informacje o aplikacji mogą znaleźć tylko Google i deweloper. Aplikacja powinna pozostać niepubliczna, dopóki nie będziesz gotowy/gotowa do udostępnienia jej szerokiej publiczności. Na stronie Konfiguracja aplikacji w pakiecie SDK Marketplace możesz włączyć lub wyłączyć wyświetlanie dodatku.

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

6. Twój zespół Google Workspace Marketplace sprawdzi Twoją aplikację. Będą się z Tobą kontaktować za pomocą adresu e-mail dewelopera podanego w pakiecie SDK Marketplace. Gdy aplikacja zostanie zatwierdzona, odznacz pole Niewyświetlana, 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 zalecamy użycie tego projektu do opracowania i przetestowania dodatku w kontrolowanym środowisku.

Aby utworzyć projekt prywatny, musisz mieć dostęp do domeny Google Workspace for Education z licencją Teaching and 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

   Ostrzeżenie: sprawdź, czy projekt należy do domeny demonstracyjnej i czy jesteś zalogowany(-a) w konsoli Google Cloud za pomocą konta administratora tej domeny.

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

   • 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 płatną wersję domeny demonstracyjnej. Przesłanie tego formularza powoduje, że Google uaktualni Twoją domenę demo do Google Workspace for Education Plus z tymi licencjami i umożliwi Twojemu projektowi w chmurze dostęp do interfejsu API dodatków 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łączyć 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 (PUBLISH – opublikować). 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 dla 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.

Ważne: jeśli dodatek wymaga dodatkowych zakresów, uwzględnij je na ekranie zgody OAuth, na karcie Konfiguracja aplikacji pakietu SDK na platformie Marketplace oraz w kodzie aplikacji dodatku. Niezgodne zakresy w tych lokalizacjach mogą powodować problemy podczas instalowania dodatku.

Zakresy uprawnień Classroom są wrażliwe, dlatego przed uruchomieniem dodatku musisz poprosić o weryfikację OAuth. W przeciwnym razie użytkownicy zobaczą komunikat ostrzegający, że aplikacja nie została zweryfikowana, a tylko niewielka liczba użytkowników będzie mogła uzyskać dostęp do Twojego produktu. Więcej informacji o weryfikacji znajdziesz w omówieniu sekwencji weryfikacji.

Ostrzeżenie: jeśli do tworzenia dodatku używasz istniejącego projektu Google Cloud, nie żądaj nowych zakresów w kodzie dla dotychczasowych produktów, dopóki nie zakończy się weryfikacja. Użyj osobnego procesu autoryzacji, środowiska testowego lub flagi funkcji, aby poprosić o te zakresy uprawnień tylko w przypadku tras związanych z dodatkami przed zakończeniem 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 jednego 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 dostęp do danych osobowych, takich jak zdjęcia w pełnej postaci, imiona i nazwiska oraz inne dane osobowe, które użytkownik udostępnił 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.

Ostrzeżenie: aby otrzymywać login_hint podczas kolejnych wizyt tego samego użytkownika, aplikacja musi prosić o co najmniej jeden z poziomów dostępu: userinfo.email lub userinfo.profile.

login_hint to standardowe parametry OpenID Connect, które możesz opcjonalnie przekazać Google podczas logowania się przez Google lub żądania tokena OAuth. Ma ona na celu ułatwienie autoryzacji dla użytkownika.

Zakresy dodatków do Classroom

Te zakresy dotyczą tylko 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 weryfikacji uruchamiania i operacji 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.
• Wywołania dotyczące konkretnego posta w Google Classroom są ograniczone przez te kontrole:
  • Gdy dodatek ma już co najmniej 1 załącznik w poście, może wysyłać prośby o:
    • Walidacja uruchamiania iframe
    • operacje odczytu, aktualizacji i usuwania załączników;
    • oceny dotyczące tego posta,
  • Gdy iframe Odkrywanie załączników zostanie otwarty po raz pierwszy, dodatek może jeszcze nie mieć załącznika w wiadomości. Dostępny jest parametr zapytania addOnToken, który umożliwia wysyłanie żądań dotyczących:
    • Tworzenie załącznika pod postem (wymagane pole addOnToken)
    • Weryfikacja uruchomienia (addOnToken jest sprawdzana, jeśli jest podana, i jest wymagana, gdy dodatek nie ma żadnego załącznika w poście)

Weryfikacja OAuth

Uwaga: nie możesz utworzyć filmu demonstracyjnego, który przesłałbyś w ramach procesu weryfikacji OAuth. Zamiast tego opublikuj dodatek bez weryfikacji OAuth. W ten sposób powiadomisz zespół Google Workspace Marketplace Review, aby utworzył film demonstracyjny w Twoim imieniu. Następnie zespół ds. weryfikacji prześle Ci film, aby umożliwić Ci jego dołączenie do zgłoszenia weryfikacji OAuth.

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

• Potwierdź tożsamość swojej marki.
• Zweryfikuj wrażliwe zakresy OAuth.

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

Informacje o aplikacji w Google Workspace Marketplace

Ostrzeżenie: po zapisaniu opcji widoczności podczas procesu publikowania nie możesz już zmienić dokonanego wyboru.

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

Informacje o kartach produktów

Listing w Marketplace SDK Store Twojego publicznego projektu Google Cloud podaje nazwę aplikacji i opis przeznaczone dla użytkowników końcowych. Te informacje 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ć tego samego tekstu.
  • Sprawdź, czy 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 podawać kwoty kosztu w opisie na platformie handlowej.
  • Sprawdź, czy w polu Kategoria wybrano wartość. Zasoby edukacyjne lub Narzędzia dla nauczycieli i administratorów mogą być dobrym wyborem dla dodatku do Classroom.
  • Więcej informacji znajdziesz w opisie aplikacji na stronie Marketplace.

Ważne: sprawdź szczegóły aplikacji w przypadku każdego języka, w którym oferujesz dodatek.

• W sekcji Zasoby graficzne:
  • Wszystkie dostarczone zasoby graficzne nie są niewyraźne i spełniają wymagania dotyczące rozmiarów określone w standardach Google Workspace Marketplace.
  • Wszystkie przesłane zrzuty ekranu odzwierciedlają sposób działania dodatku.
• W sekcji Linki do pomocy:
  • Upewnij się, że podano link do Warunków korzystania z aplikacji.
• Dopilnuj, aby Twoja aplikacja była zgodna z wytycznymi dotyczącymi marki interfejsu Google API, które obejmują dozwolone nazwy i opisy.
• Jeśli w swoim profilu odwołujesz się do jakichkolwiek usług Google, używaj ich nazw w formacie podanym w liście znaków towarowych. Pamiętaj, aby w razie potrzeby użyć symbolu znaku towarowego (™). Używaj sformułowania „Dokumenty Google™”, a nie „Dokumenty Google”.

Integracja z usługami licencjonowania i rozliczania Google

Jeśli chcesz, aby aplikacje z Google Workspace Marketplace integrowały się z usługami licencjonowania i płatności Google, zapoznaj się z interfejsem Marketplace API.

Ustawienia instalacji

Dodatki mogą umożliwiać indywidualną instalację oprócz instalacji przez administratora. Na tej stronie opisano różnice między tymi 2 typami instalacji. Nie ma ona na celu promowania żadnego z nich. Na stronie Konfiguracja aplikacji pakietu SDK Google Workspace Marketplace możesz wybrać, czy zezwolić na instalację indywidualną.

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 licencją. Jeśli Twoja aplikacja wymaga licencji, kierowanie instalacji przez administratora może pomóc w zapewnieniu, że licencje są rozpowszechniane i używane w odpowiedniej 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 zwiększyć wygodę użytkowników, ponieważ wymaga mniej kliknięć i nie powoduje zamieszania.

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 w 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 w szerszej grupie.

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 w Google Workspace Marketplace, ale nie mogą go zainstalować. Zamiast tego wyświetla się komunikat informujący, że administrator domeny nie zezwolił na instalację tego dodatku. 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łączników musisz podać adres URL iframe uruchamiania. Ten adres URL jest używany jako wartość iframe src w iframe Attachment Discovery. Nauczyciele korzystają z elementu iframe Discovery, aby znaleźć treści lub aktywności do załączenia w zadaniu. Możesz go ustawić w konsoli projektu Google Cloud.

Dozwolone prefiksy identyfikatorów URI załączników służą do sprawdzania identyfikatorów URI ustawionych w AddOnAttachment za pomocą metod *.addOnAttachments.create i *.addOnAttachments.patch. Walidacja polega na dopasowaniu do dosłownego prefiksu ciągu znaków i nie zezwala na używanie symboli wieloznacznych.

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ł.

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

Konta testowe

Utwórz konta testowe w domenie demonstracyjnej, aby sprawdzić, czy prywatny dodatek działa prawidłowo. Aby przetestować przełączanie się między uczniami w interfejsie iframe Sprawdzania zadań uczniów, potrzebne są 2 konta uczniów.

Sugerowane konta testowe:

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

Aby utworzyć nowe konto testowe:

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

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 rys. 2).
4. Wpisz członków i właścicieli grupy.

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