Krótkie wprowadzenie do JavaScript

Tworzenie aplikacji internetowej w JavaScript, która wysyła żądania do interfejsu Directory API

Krótkie wprowadzenia wyjaśniają, jak skonfigurować i uruchomić aplikację, która wywołuje interfejs Google Workspace API. W tym krótkim wprowadzeniu używamy uproszczonego podejścia do uwierzytelniania, które jest odpowiednie dla środowiska testowego. W przypadku środowiska produkcyjnego zalecamy zapoznanie się z uwierzytelnianiem i autoryzacją przed wybraniem danych logowania, które są odpowiednie dla Twojej aplikacji.

W tym krótkim wprowadzeniu używamy zalecanych przez Google Workspace bibliotek klienta interfejsu API, aby obsługiwać niektóre szczegóły przepływu uwierzytelniania i autoryzacji.

Cele

• Skonfiguruj środowisko.
• Skonfiguruj próbkę.
• Uruchom próbkę.

Wymagania wstępne

• Zainstalowane Node.js i npm.
• Projekt Google Cloud.

• Domena Google Workspace z włączonym dostępem do interfejsu API.
• Konto Google w tej domenie z uprawnieniami administratora.

Konfigurowanie środowiska

Aby ukończyć to krótkie wprowadzenie, skonfiguruj środowisko.

Włączanie interfejsu API

Zanim zaczniesz korzystać z interfejsów API Google, musisz je włączyć w projekcie w chmurze Google. W jednym projekcie Google Cloud możesz włączyć co najmniej 1 interfejs API.

• W konsoli Google Cloud włącz interfejs Directory API.

  Włącz API

Konfigurowanie ekranu zgody OAuth

Jeśli do wykonania zadań z tego krótkiego wprowadzenia używasz nowego projektu w chmurze Google Cloud, skonfiguruj ekran zgody OAuth. Jeśli ten krok został już wykonany w przypadku projektu w chmurze, przejdź do następnej sekcji.

1. W Konsoli interfejsów API Google otwórz Menu menu > Platforma uwierzytelniania Google > Elementy marki.

   Przejdź na stronę Elementy marki

2. Jeśli platforma uwierzytelniania Google została już skonfigurowana, możesz skonfigurować te ustawienia ekranu zgody OAuth w sekcjach Elementy marki, Odbiorcy i Dostęp do danych. Jeśli zobaczysz komunikat Platforma uwierzytelniania Google nie została jeszcze skonfigurowana, kliknij Rozpocznij:
1. W sekcji Informacje o aplikacji w polu Nazwa aplikacji wpisz nazwę aplikacji.
2. W polu Adres e-mail dla użytkowników potrzebujących pomocy wybierz adres e-mail, na który użytkownicy mogą się z Tobą skontaktować, jeśli mają pytania dotyczące zgody.
3. Kliknij Dalej.
4. W sekcji Odbiorcy wybierz Wewnętrzni.
5. Kliknij Dalej.
6. W sekcji Informacje kontaktowe wpisz Adres e-mail, na który chcesz otrzymywać powiadomienia o zmianach w projekcie.
7. Kliknij Dalej.
8. W sekcji Zakończ zapoznaj się z Zasadami dotyczącymi danych użytkownika w usługach interfejsu API Google i jeśli się z nimi zgadzasz, zaznacz pole Akceptuję zasady dotyczące danych użytkownika w usługach interfejsu API Google.
9. Kliknij Dalej.
10. Kliknij Utwórz.
3. Na razie możesz pominąć dodawanie zakresów. W przyszłości, gdy będziesz tworzyć aplikację do użytku poza organizacją Google Workspace, musisz zmienić Typ użytkownika na Zewnętrzny. Następnie dodaj zakresy autoryzacji wymagane przez aplikację. Więcej informacji znajdziesz w pełnym przewodniku Konfigurowanie ekranu zgody OAuth.

Autoryzowanie danych logowania w aplikacji internetowej

Aby uwierzytelniać użytkowników końcowych i uzyskiwać dostęp do danych użytkowników w aplikacji, musisz utworzyć co najmniej 1 identyfikator klienta OAuth 2.0. Identyfikator klienta służy do identyfikowania pojedynczej aplikacji na serwerach OAuth Google. Jeśli Twoja aplikacja działa na kilku platformach, musisz utworzyć osobny identyfikator klienta dla każdej z nich.

1. W konsoli Google Cloud otwórz Menu menu > Platforma uwierzytelniania Google > Klienci.

   Otwórz stronę Klienci

2. Kliknij Utwórz klienta.
3. Kliknij Typ aplikacji > Aplikacja internetowa.
4. W polu Nazwa wpisz nazwę danych logowania. Ta nazwa jest widoczna tylko w konsoli Google Cloud.
5. Dodaj autoryzowane identyfikatory URI powiązane z aplikacją:
   • Aplikacje po stronie klienta (JavaScript) – w sekcji Autoryzowane źródła JavaScriptu kliknij Dodaj URI. Następnie wpisz identyfikator URI, który ma być używany w żądaniach przeglądarki. Określa on domeny, z których aplikacja może wysyłać żądania do interfejsu API do serwera OAuth 2.0.
   • Aplikacje po stronie serwera (Java, Python itp.)– w sekcji Autoryzowane identyfikatory URI przekierowania kliknij Dodaj URI. Następnie wpisz identyfikator URI punktu końcowego, do którego serwer OAuth 2.0 może wysyłać odpowiedzi.
6. Opcjonalnie: jeśli Twoja aplikacja jest agentem AI, który wykonuje działania w imieniu użytkowników, wybierz Używaj tego klienta w przypadku agenta opartego na AI. Jeśli Twoja aplikacja obsługuje zarówno przepływy pracy agenta AI, jak i standardowe funkcje użytkownika, utwórz osobnych klientów OAuth dla każdego z tych przepływów i każdej z tych funkcji. Po utworzeniu klienta nie możesz zmienić tego ustawienia.
7. Kliknij Utwórz.

   Nowo utworzone dane logowania pojawią się w sekcji Identyfikatory klientów OAuth 2.0.

   Pamiętaj, że w przypadku aplikacji internetowych nie używa się tajnych kluczy klienta.

8. Zapisz identyfikator klienta, aby użyć go później w tym krótkim wprowadzeniu.

Tworzenie klucza interfejsu API

1. W konsoli Google Cloud otwórz Menu menu > Interfejsy API i usługi > Dane logowania.

   Przejdź do danych logowania

2. Kliknij Utwórz dane logowania > Klucz interfejsu API.
3. Wyświetli się nowy klucz interfejsu API.
   • Aby skopiować klucz interfejsu API do użycia w kodzie aplikacji, kliknij Kopiuj content_copy. Klucz interfejsu API można też znaleźć w sekcji „Klucze interfejsu API” w danych logowania projektu.
   • Aby zapobiec nieautoryzowanemu użyciu, zalecamy ograniczenie miejsc i interfejsów API, w których można używać klucza interfejsu API. Więcej informacji znajdziesz w artykule Dodawanie ograniczeń interfejsu API.

Konfigurowanie próbki

1. W katalogu roboczym utwórz plik o nazwie index.html.

2. Wklej do pliku index.html ten przykładowy kod:

   adminSDK/directory/index.html

   Wyświetl w GitHubie
   <!DOCTYPE html>
   <html>
     <head>
       <title>Directory API Quickstart</title>
       <meta charset="utf-8" />
     </head>
     <body>
       <p>Directory API Quickstart</p>
   
       <!--Add buttons to initiate auth sequence and sign out-->
       <button id="authorize_button" onclick="handleAuthClick()">Authorize</button>
       <button id="signout_button" onclick="handleSignoutClick()">Sign Out</button>
   
       <pre id="content" style="white-space: pre-wrap;"></pre>
   
       <script type="text/javascript">
         /* exported gapiLoaded */
         /* exported gisLoaded */
         /* exported handleAuthClick */
         /* exported handleSignoutClick */
   
         // TODO(developer): Set to client ID and API key from the Developer Console
         const CLIENT_ID = '<YOUR_CLIENT_ID>';
         const API_KEY = '<YOUR_API_KEY>';
   
         // Discovery doc URL for APIs used by the quickstart
         const DISCOVERY_DOC = 'https://www.googleapis.com/discovery/v1/apis/admin/directory_v1/rest';
   
         // Authorization scopes required by the API; multiple scopes can be
         // included, separated by spaces.
         const SCOPES = 'https://www.googleapis.com/auth/admin.directory.user.readonly';
   
         let tokenClient;
         let gapiInited = false;
         let gisInited = false;
   
         document.getElementById('authorize_button').style.visibility = 'hidden';
         document.getElementById('signout_button').style.visibility = 'hidden';
   
         /**
          * Callback after api.js is loaded.
          */
         function gapiLoaded() {
           gapi.load('client', initializeGapiClient);
         }
   
         /**
          * Callback after the API client is loaded. Loads the
          * discovery doc to initialize the API.
          */
         async function initializeGapiClient() {
           await gapi.client.init({
             apiKey: API_KEY,
             discoveryDocs: [DISCOVERY_DOC],
           });
           gapiInited = true;
           maybeEnableButtons();
         }
   
         /**
          * Callback after Google Identity Services are loaded.
          */
         function gisLoaded() {
           tokenClient = google.accounts.oauth2.initTokenClient({
             client_id: CLIENT_ID,
             scope: SCOPES,
             callback: '', // defined later
           });
           gisInited = true;
           maybeEnableButtons();
         }
   
         /**
          * Enables user interaction after all libraries are loaded.
          */
         function maybeEnableButtons() {
           if (gapiInited && gisInited) {
             document.getElementById('authorize_button').style.visibility = 'visible';
           }
         }
   
         /**
          *  Sign in the user upon button click.
          */
         function handleAuthClick() {
           tokenClient.callback = async (resp) => {
             if (resp.error !== undefined) {
               throw (resp);
             }
             document.getElementById('signout_button').style.visibility = 'visible';
             document.getElementById('authorize_button').innerText = 'Refresh';
             await listUsers();
           };
   
           if (gapi.client.getToken() === null) {
             // Prompt the user to select a Google Account and ask for consent to share their data
             // when establishing a new session.
             tokenClient.requestAccessToken({prompt: 'consent'});
           } else {
             // Skip display of account chooser and consent dialog for an existing session.
             tokenClient.requestAccessToken({prompt: ''});
           }
         }
   
         /**
          *  Sign out the user upon button click.
          */
         function handleSignoutClick() {
           const token = gapi.client.getToken();
           if (token !== null) {
             google.accounts.oauth2.revoke(token.access_token);
             gapi.client.setToken('');
             document.getElementById('content').innerText = '';
             document.getElementById('authorize_button').innerText = 'Authorize';
             document.getElementById('signout_button').style.visibility = 'hidden';
           }
         }
   
         /**
          * Print the first 10 users in the domain.
          */
         async function listUsers() {
           let response;
           try {
             const request = {
               'customer': 'my_customer',
               'maxResults': 10,
               'orderBy': 'email',
             };
             response = await gapi.client.directory.users.list(request);
           } catch (err) {
             document.getElementById('content').innerText = err.message;
             return;
           }
   
           const users = response.result.users;
           if (!users || users.length == 0) {
             document.getElementById('content').innerText = 'No users found.';
             return;
           }
           // Flatten to string to display
           const output = users.reduce(
               (str, user) => `${str}${user.primaryEmail} (${user.name.fullName})\n`,
               'Users:\n');
           document.getElementById('content').innerText = output;
         }
   
       </script>
       <script async defer src="https://apis.google.com/js/api.js" onload="gapiLoaded()"></script>
       <script async defer src="https://accounts.google.com/gsi/client" onload="gisLoaded()"></script>
     </body>
   </html>

   Zastąp te elementy:

   • YOUR_CLIENT_ID: identyfikator klienta utworzony podczas autoryzowania danych logowania w aplikacji internetowej.
   • YOUR_API_KEY: klucz interfejsu API, który utworzono.

Uruchamianie próbki

1. W katalogu roboczym zainstaluj pakiet http-server:

   npm install http-server
   

2. W katalogu roboczym uruchom serwer WWW:

   npx http-server -p 8000
   

3. W przeglądarce otwórz http://localhost:8000.
4. Zobaczysz prośbę o autoryzację dostępu:
   1. Jeśli nie zalogowano się na konto Google, zaloguj się, gdy pojawi się prośba. Jeśli korzystasz z kilku kont, wybierz jedno z nich, które ma być używane do autoryzacji.
   2. Kliknij Akceptuję.

Aplikacja w JavaScripcie uruchomi się i wywoła interfejs Directory API.

Dalsze kroki

• Wypróbuj interfejsy Google Workspace API w narzędziu API Explorer.
  • Rozwiązywanie problemów z uwierzytelnianiem i autoryzacją
  • Przewodniki dla programistów interfejsu Directory API
  • Dokumentacja referencyjna interfejsu Directory API
  • google-api-javascript-client sekcja w GitHubie